Upgrade from 1.0.1 to 1.2.0
This page describes direct migration from 1.0.1 to the 1.2.0 release line. Version 1.1.0 was not published separately; its development work is included in 1.2.0 without an intermediate installation. Duplicate Call identity handling, journal-prefix caching, Python notification draining, project-script loading trust, and terminal editing retain the compatibility and permission boundaries below. Public availability and formal qualification require evidence for the same version, commit, and exact artifacts.
Back up and align versions first
- Stop CLI, SDK, Worker, and host processes sharing the state directory. Back up
.coremind/, Sessions, Checkpoints, Run Store, configuration, and external-effect receipts with no writes in flight. - Require Node.js 22.19+ and Python 3.10+. Upgrade every CoreMind npm package, Python SDK, and bundled Worker together to the actual published 1.2.0. Do not upgrade one side while retaining an old Worker. This page does not establish public registry availability or a successful installation.
- Config v2, Protocol v1/v2, and existing V4 Sessions remain supported without rewriting session bodies. New features require capability negotiation; v2 requires matching Schema fingerprints. A matching protocol major version does not justify stripping fields to bypass missing capabilities or fingerprints.
- Do not copy the Worker alone. Linux Shell requires the packaged
vendor/linux-sandboxand architecture-specific helper; missing assets, wrong hashes, or unavailable isolation deny execution. Python continues to call the shared Node Runtime rather than a pure Python implementation.
Sessions, recovery, and model requests
The canonical Session write lease covers history reads, execution, compaction, final persistence, and cancellation settlement. Another holder or process cannot execute concurrently on that Session. Leases require a hard-link-capable local filesystem, not distributed coordination across machines. Creating a Runtime with an explicit Session and ID may create an empty session and public alias; a read-only directory may fail earlier. This does not mean input was admitted or a model was called.
Ordinary Runs refresh history under the lease. A ChatSession holding stale history rejects instead of overwriting newer entries. Reopen and read current history before deciding to submit new input; never automatically replay an unknown request that may have produced external effects. Crash recovery validates lock owners rather than deleting a potentially active lock based only on age.
JSONL recovery truncates only an unrecoverable tail after the valid UTF-8 prefix, preserving file and hard-link identity. Middle corruption or an unfamiliar file identity still rejects rather than silently losing history. Include branching, summaries, operation receipts, and subsequent seq/parent continuity in upgrade checks. System instructions and tool declarations are assembled at request boundaries, outside original session bodies.
Historical thinking enters request views according to Provider/API/model identity. Switching models does not send incompatible thinking as ordinary text. Answers and tool-call pairing remain, and canonical Session entries are not filtered by migration. Local preservation of a model signature does not certify acceptance by an external Provider.
Malformed or truncated final tool-argument structure returns an argument error without structural completion and execution. Permitted escape repair inside a complete string does not permit missing fields, brackets, or strings. A model may then make a new valid call; authorized tools still use the original approval and execution path.
Output-length termination is now failed / model_output_limit, retaining partial text and stop reason. The CLI prints partial text and exits unsuccessfully. Text alone does not establish success or permit the next orchestration step, verification, or attached tool call. A host choosing a new request must reconcile completed effects and budgets; the Runtime does not continue automatically.
Explicit gateway transient errors permit bounded retries. A step that already started a write, external effect, or delegation pauses whole-step replay for human reconciliation. Pure reads retain bounded retries. Parent delegation receipts cannot establish that children had no effects, so even read-only children conservatively pause replay. maxRetries: 0 gains no retries; authentication, quota, and unknown errors do not become retryable.
Duplicate Call identity handling has merged and passed both-platform CI. The Runtime rejects repeated complete Agent/Step/Call identities within a Run and same-Run recovery while preserving the first durable facts and tool binding; valid new Call identities remain usable. Reconcile external results independently: duplicate rejection does not guarantee business idempotency.
Skills, input controls, and MCP
Skills still select directory IDs through agents.<name>.skills. Built-ins and README.md-only projects retain full injection; configDir/skills/<id>/SKILL.md first supplies an index, with bodies loaded through ToolPolicy-controlled load_skill. Built-ins win ID collisions; SKILL wins with a warning when both files exist, and invalid files never fall back. Each source is limited to 256 KiB; resolver results and the snapshot across all Agents separately allow 2 MiB of serialized UTF-8 JSON.
Runtime creation freezes standard Skills; Children and recovery use the original snapshot, and edits require a new Runtime. Missing or corrupt snapshots never fall back to current files. The trusted raw Store contains bodies; public projections, events, and telemetry strip private attached fields. This does not remove bodies from ordinary Sessions or business output, nor prevent a host rewriting its Store and hashes. Skills grant no permissions and do not automatically execute scripts. See the Skills guide.
TypeScript ChatSession.steer/followUp(message, options?) accepts retained { controlId, runId }; the CLI uses /steer text and /follow-up text. Delivery binds to the actual active Turn Runtime at call time. Unready, sealed, or mismatched targets reject without redirecting input to a later turn. Ordinary busy text stays a draft for explicit idle confirmation; late receipts do not clear a newer draft.
Control receipts remain separate from input_* events. Applied is not consumed/completed. Cold recovery may apply accepted controls; applied controls with unknown consumption are explicitly discarded rather than redelivered. A durable-commit/in-memory-delivery crash window remains, without an absolute exactly-once guarantee. Original input, Session, and conversation reconstruction retain their recovery gates.
MCP requires explicit configuration, connection admission, tool authority, and budget. HTTP targets and resource URIs are controlled; Children inherit no authorization. OAuth is host-initiated PKCE/state with controlled loopback, never automatic browser opening or authorization from a 401/403. Authentication establishes credentials, not tool approval. Local services and scripts execute with host authority, not an OS sandbox. Verify external interoperability independently.
Protocol v2 waits for host finalization before returning a current terminal query, an event page containing the current terminal fact, or an expired-cursor terminal projection. A single caller can then start another Run; active concurrent execution still rejects with worker_busy. Historical pauses and older event pages do not prove current quiescence or resolution of all Child business decisions.
Project script loading trust
Configured script tools are imported during Runtime creation. Module top-level code and transitive dependencies execute with host process privileges. Before any configured entry is imported, the host must explicitly approve the complete batch. Missing approval, denial, and callback failures reject with execution_security_violation; cancellation retains aborted. Configurations without project scripts require no decision. Missing script files may retain their previous warning-and-skip behavior; files appearing later cannot acquire approval implicitly.
TypeScript hosts use approveProjectCode(request, signal). The request includes the canonical project directory, sorted and deduplicated entry paths, entry SHA-256 values, and a batch fingerprint. The batch covers effective inherited, independent, and deferred tools of every Agent actually constructed. Each import checks the entry again. Return true only for code the host has reviewed:
const runtime = await CoreMindRuntime.create({
config,
configDir,
approveProjectCode: async (request) => approvedFingerprints.has(request.fingerprint),
});CLI run, chat, and eval share this decision. TTY prompts default to rejection, including empty input, EOF, and cancellation. Prompts go to stderr. Decisions are reused only for the same complete fingerprint in the current command process. Non-TTY input is never consumed as approval: explicitly pass --trust-project-code or --trust-project-code=true for reviewed code. false denies; other values are argument errors. --permission full does not approve imports. doctor and check remain static and do not import project scripts.
Both Python clients accept the boolean-only keyword trust_project_code: bool = False. Set it to True only for reviewed projects. Standard Worker v1/v2 initialize accepts trustProjectCode and advertises projectCodeTrust. The new SDK requires this capability before run/chat or callable registration, even with the default False; it cannot silently downgrade to an older Worker. Upgrade custom Workers alongside the SDK, and generate the v2 fingerprint and bundled Worker together. The single v1 tool-discovery challenge retry retains the original trust field.
Approval of loading grants no tool, file, network, credential, or Child permissions. Tool approval, explicit deny, workspace restrictions, and recovery gates remain active. Entry hashes do not prove immutable transitive dependencies or prevent a host-privileged external process from replacing files after checks; this is not an OS sandbox. Host-loaded extension and callable objects do not trigger duplicate approval. Direct calls to low-level loadScriptTool() or buildTools() mean the caller already trusts the specified code and do not replace configuration-driven Runtime approval.
Fix SDK shutdown after an ordinary project-script denial: preserve the prior quiescent state only when entry inspection has completed and the Runtime has not been created. Read or factory failures and a previously unsettled execution state retain conservative handling.
Custom endpoint authentication
Only custom compatible baseUrl endpoints gain keyless or Header-only use; built-in and native endpoints retain credential requirements. Missing, blank, or failed explicit apiKeyEnv, SecretRef, or sensitive Header references reject without anonymous fallback, even when another Header is available.
Without an explicit key source, a valid existing Provider-ID-derived environment key still applies; ensure it is unset for truly anonymous use. An Authorization environment value contains the complete Bearer <token>; services may instead require X-API-Key. Explicit Authorization overrides the default Bearer with case-insensitive Header names. Keyless requests do not send internal placeholder credentials. Keep sensitive literals out of YAML. CLI, Python, and standard Worker do not gain a SecretResolver automatically; references without a host resolver still reject. A server 401 remains authentication failure, without changing source or logging in automatically.
Bounded output delivery
Non-Ink CLI text and Worker stdio use a bounded encoded queue of 64 MiB UTF-8 / 1024 entries, including in-flight entries. Critical delivery failures report output_delivery_failed. Existing catch-up-capable live events retain their prior semantics; RPC, control, and final bodies are not silently dropped. Backpressure still permits approval/cancellation input. Hard delivery failure stops intake, cancels owned work, and joins accepted work without automatic replay.
The 10-second final flush deadline is not an OS process-kill guarantee and cannot forcibly terminate uncooperative host functions or physical writes already in progress. A disconnected SDK may see only WorkerExitedError. Transport failure does not rewrite prior Runtime facts; cancellation may still produce the original aborted outcome. Queue budgets exclude model generation, transient serialization, Ink rendering, and total process RSS.
Long-lived Python notifications
Python exposes client.drain_notifications() / await async_client.drain_notifications(), atomically taking and clearing events, tool_calls, tool_cancellations, and verification_requests in place. Default received_* retention remains complete. Returned lists are new but share element references, preserve per-bucket order, and provide no global order across buckets. Process or retain the entire batch and route by runId; do not take only events and discard pending host responses.
Draining starts no RPC or Worker and can take existing history before start or after close. It is not a server acknowledgement, tool/cancellation/verification response, callback-queue clear, or overload reset. MCP authentication retains its dedicated handler. Copying is O(N), locally on the original loop even in async use. Regular consumption can release received objects but establishes no automatic memory cap.
v2 durable catch-up is separate: process each events page before saving that page's actual nextCursor per runId. Live notification sequence values are not durable cursors; do not interchange them or derive one by adding one. Draining does not advance cursors; empty pages do not establish terminality, and durable events do not promise exact replay of each dedicated notification. Follow expired-cursor recovery details instead of silently replaying from zero. v1 has no v2 durable catch-up.
Journal cost and terminal editing
The merged critical journal prefix optimization reduces repeated historical parse/serialization work only. The complete text is still read and compared exactly as a string, followed by complete temporary rewriting, synchronization, and atomic publication. Cached text has a 4 MiB UTF-8 total budget and at most 64 cursors; this is not a heap cap. No production throughput or latency gain is promised, and no segmented journal or format migration is introduced.
The TUI provides grapheme-aware cursor movement, middle insertion/deletion, whole-draft Home/End, and at most 50 admitted ordinary user inputs in the current interface. Up saves the draft and Down past the newest entry restores it. Slash commands, approval input, and unadmitted busy submissions are excluded. Approvals freeze normal drafts/history, paste never approves directly, and the complete text is redacted before cursor display. History is memory-only; Delete/word movement, visual-line Home/End, external editors, and universal input-method compatibility are not promised. Existing limits remain 16,384 graphemes / 65,536 UTF-8 bytes with whole-chunk rejection on overflow.
Cutover checks and rollback
On a backup copy, check recovery of old Sessions, branching/summaries, lease conflicts, and legal appends. Then verify allowed/denied real tools, output-limit outcomes, cancellation settlement, and the next Run. Separately accept script trust, custom authentication, notification consumption, and MCP where used. Controlled local fixtures do not certify external Provider/OAuth/MCP interoperability. Formal publication requires strict Provider, both-platform stability/coverage/PTY, and public exact-artifact installation evidence bound to the final commit.
If checks fail, stop new processes, restore programs, SDKs, and Worker together to the actual published 1.0.1, and restore pre-upgrade configuration/state backups. Never run both versions as writers to the same state directory. Old programs must not write newer journals containing facts they do not understand. Reconcile external effects before compensation or retry; restoring local backups does not undo external operations. Published artifacts are immutable. A partial release resumes using the same exact artifacts and identity, never a different rebuild of the same version.