Upgrade from 1.2 to 1.4
This guide uses published
1.2.0as the baseline for a direct upgrade to the1.4.0release target. GitHub Releases, npm and PyPI determine the latest public stable version. All unpublished1.3.0fixes are included; no intermediate installation is required. Switch only after same-version Releases, npm/PyPI artifacts and final qualification evidence are confirmed. Source and engineering CI establish neither publication, production outcomes nor Provider certification. See the bilingual release notes.
Before upgrading
Stop old CLI, SDK, and Worker processes. Back up configuration, Sessions, RunState, Checkpoints, and business files. Update every CoreMind npm package, the Python SDK, and bundled Worker together to 1.4.0; never run old and new writers against the same state directory. Requirements remain Node.js ≥ 22.19, Python ≥ 3.10, and Git ≥ 2.36 for Git tools.
Existing Config and Protocol major-version boundaries remain: Config v2 stays compatible, deferred still requires explicit Config v3, and Protocol v1 remains supported. Protocol v2 adds task/session DTOs and capabilities; new functionality requires matching the complete Schema fingerprint. ToolPolicy gains optional protectedPaths constructor entries, and the identity argument of authorize() gains optional signal?: AbortSignal; existing calls remain compatible. SDKs and Workers must still match; an unchanged wire shape does not authorize mixing versions. For versions before 1.2, first check the existing 1.0→1.2 migration requirements.
Check behavior changes
Files and framework state
Ordinary business tools cannot write framework-managed persistent state, regardless of permission mode or explicit allow. Keep business outputs on legitimate business paths; recovery, cleanup, and state maintenance remain host responsibilities. Ordinary tool writes to existing files with multiple hard links are rejected, while reads retain existing authorization. A host must explicitly handle link relationships before modification. Keep approval and Checkpoint handling for legitimate workspace files. This does not isolate arbitrary host code.
Workflow output and cancellation
Repeated use of the same agent retains Session history for model context. However, prompt/call step output, saveAs, subsequent interpolation, and transcript contain only newly produced assistant text. If two steps produce A and B, the second result is B. Update business parsers and assertions that relied on repeated historical replies.
The first parallel failure or pause cancels siblings and waits for settlement while preserving the first error; the Run admits no new model calls after ending. All-success results still aggregate in declaration order. Cancellation does not undo started tool operations; reconcile effects using receipts.
Python v1 tool schemas
@client.tool automatic schemas resolve from __future__ import annotations and string annotations for int, str, bool, and existing supported containers. Unresolvable forward references require explicit parameters. Existing explicit schemas remain compatible without expanding complex typing support.
Node still applies existing conversion before validation: for example, the string '5' can become the integer 5 for an int parameter. Arguments are rejected before callable execution when they remain invalid after conversion. The fix does not strictly reject every difference in original input type.
Diff grader
preserveExisting: false only disables existing dirty-content protection; it cannot bypass allowedPaths, forbiddenPaths, requiredPaths, or maxChangedFiles. The change set includes baseline-to-final status or content differences. Dirty files with unchanged status and content do not count, while deleting a file untracked at baseline does. Existing stage/unstage counting and default true protection remain. Check evaluations that relied on omitted changes and align fixtures with the legitimate business scope rather than removing constraints.
Protocol v2 startup failure
Runtime initialization failures after Run acceptance retain the shared classification's stable code, corresponding outcome status, and safe message through query/events. Consumers must use the actual error contract instead of assuming every failure is agent_failed. Unknown unclassified_error conservatively pauses and requires human audit; a pause does not itself establish that resume is safe. That startup-error fix itself adds no error fields and exposes no credentials or raw stacks; new task-management identities and subcodes are described below.
Web-tool settlement
On non-2xx responses or body-read failures, web-fetch/web-search await body cancellation/release cleanup attempts before settling local network activity. Cleanup failure preserves the original HTTP/read error. Normal results, cancellation, permissions, network policy, and the web-fetch 2 MiB limit remain unchanged; no new web-search size contract is introduced.
Readline and doctor
Readline /exit and !exit now request active-Run cancellation before waiting for cleanup, matching the TUI. Pipelines that should let an already-started ordinary response finish naturally should retain the existing EOF path. Idle, approval-wait, and MCP-login-wait behavior remains unchanged. Exit does not automatically roll back started tool effects.
doctor <config-file> reuses the selected Provider's existing credential policy. Legitimate anonymous/Header-only custom endpoints require no unrelated API key; an endpoint with baseUrl remains custom even when its Provider ID matches a built-in one. Explicit missing credentials still fail, and native built-in authentication requirements remain. General diagnostics without a config are unchanged. Checks neither load project scripts nor send Provider requests and prove neither credential validity nor connectivity.
Security-policy support tables and shipped-capability descriptions are corrected without expanding support policy, the 0.3.1 critical-security exception, or private disclosure. See the security policy.
New durable-task and cross-language boundaries
Task definitions, states and migration
TaskSession adds durable phases inside the one Node Runtime. A task checkpoint, optional documents/entries and the next phase share one atomic commit; legacy Session/Run/Workspace data is not converted into tasks. start persists initial state only, and each resume executes one phase. Consumers must handle ready, paused, sleeping, completed and cancelled. Completed/cancelled tasks return their terminal state; concurrent writes are rejected rather than implicitly queued.
Trusted hosts must explicitly raise definition version when changing a definition, Schema, handler, closure or dependency behavior. Supply migrate(previous, signal) to upgrade existing tasks, returning only { phase, checkpoint }. Same-version drift, downgrades and missing/invalid migration fail closed. Failed migration preserves facts; successful migration commits new state atomically before phase execution. Changes to configuration, approvals, tool capabilities or credential routing also require authorityVersion updates; state migration cannot grant new authority. Handlers restart at the persisted phase's top, without restoring memory, timers or JavaScript stacks.
Durable waiting and host alarms
A phase can return absolute UTC-millisecond sleepUntil and persist a sleepId. Hosts recompute waits with nextWake(), call wake using a stable wakeId and the exact sleepId, then explicitly resume. Wake commits ready without running the next phase. If a process exits after wake commits, startup must also query and resume known ready tasks; scanning nextWake alone is insufficient. Handle early, duplicate, stale and terminal notifications using their results, without rebinding old keys or reviving tasks.
Waiting extends no Run, tool, phase or Worker timeout. Hosts own process startup and alarm delivery; no background distributed scheduler is added. Cancellation does not roll back external operations, while closing an idle session does not cancel durable waits.
Keyed calls and effect reconciliation
A phase chooses context.run or context.runCalls under one governed Run. executeTool(key, tool, args) binds the key to the task, phase, definition version, phase Run, arguments, tool and authority identity. Reopening reuses committed results only when original facts establish safety. Await distinct keys sequentially in the original order; changing arguments or inserting/removing/reordering old keys cannot bypass recovery. session.calls(taskId) exposes call/result records, subject to existing commit-size limits.
If Run effects/results commit before the phase does, reconcile the original Run/key/result rather than repeating tools. Unknown effects remain paused for review; do not change keys or create replacement Runs to resend them. Arbitrary JavaScript, random values, time and ungoverned I/O are outside the call ledger. This is not external exactly-once. A write-acknowledgement error does not prove rollback: preserve the directory, close/reopen and inspect task plus original Run facts.
Session branches, forks and path identity
ChatSession adds tree inspection, named branches, durable selection and message-node forks. Continued chat reads the selected history while retaining original messages. Forks receive new session identities without copying old Runs, control receipts or execution authorization. Navigation requires persistent sessions, idle state and existing writer checks. Trees contain complete messages; hosts still own access authorization, and a bound sessionId is not multi-tenant authentication.
Reopening the same physical workspace through Windows long/short paths or directory links checks directory and public-file identity and retains original v4 storage without moving history. Different physical directories and copied files cannot use this recovery path. Alias publication or acknowledgement failure may leave committed facts; inspect original state before forking again or deleting a source.
Upgrade TS, Python and Worker together
Use matching 1.4.0 SDKs and bundled Worker with the complete Protocol v2 Schema fingerprint and independently negotiated durableTasks/sessionBranches capabilities. Existing Protocol v1 behavior remains. Older Workers explicitly reject unsupported capabilities rather than silently degrading. TS and sync/async Python share the existing Node Runtime, task/Run/session facts and error identities, without a Python runtime, fact store or scheduler.
Trusted Node hosts register task definitions with runStdioWorker; the default Worker has no task registry. Python sends definition IDs and JSON, never callables, source, arbitrary module paths or credentials. Host-code loading trust and tool permissions remain separate; trusted handlers are not a sandbox. Task subcodes use details.taskCode with operation/action/sessionId/taskId checks. Cancellation or RPC errors do not establish effect rollback.
See the durable-task guide, session-branch guide and cross-language SDK guide.
Retry and dependency risks
Status-code substrings in request IDs or longer numbers no longer trigger transient retry. Unknown errors retain their original classification and human audit. Upgrade the entire underlying runtime dependency family to 1.5.0 and check that the installed npm graph uses Undici 8.12.3 and minimatch 11.0.3. These versions fall outside the nine advisory ranges recorded in #359. The separate development dependency risk acceptance retains its audit scope and 2026-11-14 expiry. See the security policy.
Tool validation in underlying runtime 1.5.0 can coerce inputs according to the schema, for example converting numeric strings to numbers. Use business inputs to verify that approval, execution, and recovery records use the same effective arguments and that invalid arguments still reject.
An updated dependency catalog can change the default model for some providers. Set provider.model explicitly when your workload requires a fixed model.
Verification and rollback
On a backup copy, verify business writes and state protection, repeated-agent outputs, parallel failure/pause settlement, Python automatic/explicit schemas, Diff change sets, v2 persisted error queries, Web failure cleanup, explicit exit versus EOF, and doctor credential policy. Use existing framework tests and business evaluations; one successful run is not complete release qualification.
On backup state, also verify A→durable wait→process restart→exact wake→reuse original Run/key/result→phase B, comparing TS and sync/async Python status, identity, errors and cancellation. Check session selection/forks, unsupported capabilities/old Worker rejection, authorization and write failures. Ordinary close/reopen is not process-crash acceptance, and offline fixtures do not certify external services.
Formal publication requires strict Provider, both-platform engineering/stability/coverage/real PTY, and public reinstall evidence bound to the final 1.4.0 main commit, Runtime/Worker, and exact artifacts. Older certification cannot substitute for it. Controlled local fixtures do not certify external Provider/OAuth/MCP interoperability.
To roll back, stop new processes, restore programs, SDKs, and Worker together to published 1.2.0, and restore pre-upgrade configuration and persistent-state backups. Older SDKs cannot interpret new task sleep/wakes, call ledgers or durable session selection. Preserve and restore task, Session, Run and Workspace/Checkpoint facts together; never let an older SDK independently resume a new task Run or edit facts/disable validation for compatibility. Old programs must not write facts they cannot understand, and two versions must never write the same state concurrently. Reconcile external effects before compensation or retry. Restoring local files does not undo external operations; published same-version artifacts cannot be overwritten.