[jpicklyk]

Lands release/4.0 (75df163d) on main by a merge commit. 3.x maintenance continues on release/3.x (cut from main at 5322daf8). This PR retires the pr-base-guard workflow, whose only job was to keep 4.0 work off main.

Full release notes: CHANGELOG.md section ## [4.0.0] (158 KB; the GitHub body limit is 64 KB). The upgrade section follows.

Upgrading from 3.x

4.0 changes the wire contract (tools, request and response shapes, REST routes), the database schema (migrations V18 to V37 plus startup data steps) and the config format. Read this before the first 4.0 start on an existing volume.

• Back up the volume before the first 4.0 start. Migrations V22 (dependency rewrite), V24 (plan_documents into documents), V25 (project_config into config_versions), V26 (work_items recreation) and V29 (role_transitions into events, then dropped) and the type-backfill, traits-from-properties and pin-backfill data steps rewrite data one way. The server also writes a verified <db>.pre-4.0.<yyyyMMddTHHmmssZ>.bak beside the database before the first migration (UPGRADE_BACKUP, default on), but it sits on the same volume, so keep a copy of the whole volume too. The backup is the supported rollback, and a 3.x binary cannot open a V26 or later database.
• Stop every 3.x process first, stdio sessions included. A 3.x binary does not fail closed on a newer database, and a 3.x writer that inserts an IS_BLOCKED_BY row fails the V22 CHECK.
• The first start is slower. It runs the data steps (type-backfill, traits-from-properties, config-canonicalize, pin-backfill) and the item FTS rebuild of V26 before the readiness marker is written; a failed step fails startup as DATA_STEPS and the container reports unhealthy. Raise the Docker --start-period on a large database.
• The migration-lock wait is fixed at 300 s. A second boot waits that long for the first to finish its UPGRADE_BACKUP copy and migration; a first boot of a very large database can outlast it, and the waiter then fails startup closed as SCHEMA_UPDATE and takes no copy. There is no environment key for the wait; start the instances of a shared volume one at a time.
• The mounted global config boots with warnings. The file is imported at every boot and then served from the database. The 3.x top-level keys schema_resolution, orchestration, retrospective and actor_attribution are accepted at boot as stored warnings (returned as configWarnings by GET /api/v1/info); a push of the same text is rejected. Move plugin settings under extensions.claude-code. Any other strict error, a file over 128 KiB, or a project.rootId that is not a depth-0 item of this database fails startup as DATA_STEPS.
• Untyped items get a type. type is required in 4.0. type-backfill gives every item whose type is NULL or blank the schema key the 3.x tag step resolved it to, or untyped when none matched, and traits-from-properties moves properties.traits into the typed traits list.
• In-flight items keep their 3.x schema; new items follow the new precedence. pin-backfill pins every item at the first start to the base schema 3.x gave it, so no gate moves for existing items. An in-flight 3.x parent already in review no longer auto-completes when its last child completes: it needs an explicit advance, and the cascade entry reports reason review-pending. New items resolve by type only: per-root exact type, server exact type, per-root default, server default. Tags no longer select a schema, a server exact type now beats a per-root default, a root that used schema_resolution: isolated now sees server entries, and duplicate trait note keys resolve item-first with required OR'd.
• Stored data moves. Each project_config row becomes version 1 of its root's config (V25, ids preserved); the 3.x transition trail moves into events as backfilled item.transitioned rows (V29); plan_documents become documents (V24; a CRLF body keeps its 3.x hash until it is rewritten); IS_BLOCKED_BY rows are rewritten as BLOCKS (V22); every timestamp is normalized to UTC text (V18).
• Notes written before 4.0 have no owner. 4.0 enforces note ownership (see Added: note ownership), and a 3.x actor id was declared by the caller, so none is trusted as an owner. V34 adds notes.owner_id, NULL for every existing note, and changes no other column: each note keeps its 3.x actor and verification. The first 4.0 upsert of such a note, by any caller allowed to write the item (in its scope, holding write-notes, and the claim holder while the item is claimed), makes that caller the owner and records an audit note.ownership_transferred with from: null and the 3.x actor id as legacyActor; after that, another principal is refused note_owned_by_other unless the key is shared: true or an admin passes takeover: true. In-flight items need no takeover. Until its first 4.0 upsert, such a note can be deleted by any caller allowed to write the item, as in 3.x; this includes notes a 3.x REST token wrote.
• Saved SSE cursors re-fetch once. Event ids are now the durable events seq, above 10^12; a Last-Event-ID saved before the upgrade is answered with sync.lost (unknown_event_id).
• Short ids need 8 hex characters. Every id field takes a full UUID or 8 to 32 hex characters; 3.x accepted shorter prefixes.
• Environment. USE_FLYWAY is removed and ignored (one WARN if still set) and API_WARN_ON_CLAIMED_ADVANCE is removed. SCHEMA_MODE, FTS_INTEGRITY, MCP_TOOL_PROFILE, MCP_ALLOW_UNAUTHENTICATED, the four retention settings (RETENTION_CALL_LOG_DAYS, RETENTION_EVENTS_DAYS, RETENTION_AUDIT_EVENTS_DAYS and RETENTION_LEASE_HISTORY_DAYS) and API_JWKS_MAX_STALE_SECONDS are new, and DATABASE_BUSY_TIMEOUT_MS now governs only the startup paths. The default CORS_ALLOWED_HEADERS gains X-Client-Host and the default CORS_EXPOSE_HEADERS gains X-Req-Id; a deployment that sets either explicitly keeps its own list.
• Clients and the plugin. Every 3.x tool call shape and every 3.x REST resource route is gone (see Removed), and every /api/v1 body is the envelope. The 3.x plugin does not work against a 4.0 server: its hooks fail open, so nothing is blocked, but nothing syncs or gates either. Install the 4.0 plugin (see ### Plugin); to stay on a 3.x server, pin the plugin to the release/3.x ref.
• Key fetches refuse non-public addresses. Every JWKS and OIDC discovery fetch now passes an egress guard: a key source that resolves to a loopback, link-local, private (RFC 1918), CGNAT, unique-local or unspecified address fails, and verification reports unavailable naming the refused address (REST fails the request closed). A private identity provider or a corporate JWKS on 10.0.0.0/8 stops working on upgrade; loopback is admitted only with API_JWKS_ALLOW_INSECURE_URL=true (REST), and other private ranges have no opt-in in 4.0.
• /mcp over HTTP authenticates, and actor is gone. With the REST API on in a credential mode (API_AUTH_MODE=bearer or jwks), every /mcp, /mcp/knowledge and /mcp/director request needs the same Authorization: Bearer credential as /api/v1; without one it answers 401 unauthenticated (the error envelope, never JSON-RPC). MCP_TRANSPORT=http with the API disabled now fails startup (MCP_AUTH) unless MCP_ALLOW_UNAUTHENTICATED=true is set on purpose. Clients stop sending actor: the caller is the transport principal, and a body actor is unknown_parameter. Audit ids written in REST unauthenticated mode change from api:local-unauth to local.
• Document writes need write-docs. Every docs_write op now requires the new write-docs capability, and write-config no longer grants any of them. A token that only had write-config (for example a config-sync token that also pushes plans or rules) is refused with forbidden until write-docs is added to its capabilities list.
• Principal root scope is roots-only. A scope anchor (scope.root_ids) admits exactly the items stamped with that root, so a mid-tree anchor admits nothing. A REST bearer token whose scope.root_ids names an existing non-root fails startup, naming the token; a JWT anchored on a non-root resolves to no principal (401). Creating a root, or moving an item to a root, needs an unrestricted scope or ADMIN.
• DEGRADED_MODE_POLICY is removed and fails startup. Verification fails closed, so there is no policy to choose: unset DEGRADED_MODE_POLICY (any value) before the first 4.0 start, and delete actor_authentication.degraded_mode_policy together with the rest of the actor_authentication block (next entry). A leftover variable stops the server with an error naming it, before the readiness marker is written, because ignoring a security setting an operator believes is in force would be worse than refusing to start. A deployment that relied on accept-cached or accept-self-reported to keep working through a key-set outage now gets 503 unavailable instead (see Changed). Wire clients that read a note's attribution read verification.proofStatus, not verification.status (see Changed).
• actor_authentication is removed, and a leftover block fails startup. No request carries an actor or an actor.proof any more, so the verifier the block configured was consulted by no call, and require_sub_match, jti_replay_protection, DID trust (did_allowlist, did_pattern) and the loose-kid match had no effect. A global config with an actor_authentication: key, whatever its value (a mapping, {}, a scalar or a bare null), now stops the server with an error naming it, before the readiness marker is written; the legacy auditing: key still fails startup too. A per-root push carrying it is rejected at /actor_authentication as an unknown top-level section. REST break: GET /api/v1/info no longer returns actorAuthenticationEnabled; clients that read it must stop. Solo stdio: a server with no AGENT_CONFIG_DIR reads the workspace .taskorchestrator/config.yaml as its global file, so a hook-only actor_authentication: {enabled: true} block there now fails startup too; delete it. The plugin's attribution hook is removed (the server principal is the identity), so there is no plugin-side attribution requirement to configure. A call's identity comes from API_AUTH_MODE alone: the credential's principal (api:<id>), or the single local principal for stdio, /mcp in a local mode and API_AUTH_MODE=none. Move any actor-proof JWKS setup to API_AUTH_MODE=jwks and the API_JWKS_* variables; delete the block before the first 4.0 start.
• The first start folds and prunes. The retention pruner runs right after startup. It folds each completed UTC day of call_log into usage_daily, then deletes call_log rows older than 90 days (folded days only), activity-class events older than 180 days and closed lease intervals older than 365 days; audit events are kept. To keep any of that data, set the matching RETENTION_CALL_LOG_DAYS, RETENTION_EVENTS_DAYS or RETENTION_LEASE_HISTORY_DAYS to 0 before the first start. The database file does not shrink without an offline VACUUM (see Data Retention in current/docs/fleet-deployment.md).
• Credentials without a kind are service. A token-file entry with no kind and a JWT with no to_kind load as kind service (a self-issued did: token is agent). Answering a decision whose class is human-only needs a credential of kind human (kind: human in the token file, to_kind: human in a JWT).
• Stdio and local sessions are one principal. Every stdio session, /mcp in a local mode and API_AUTH_MODE=none run as the single local principal, which owns the notes and claims they write, so separate sessions share them unless they hold seat tokens (see run seats under Added). Separating them otherwise takes credentials.

🤖 Generated with Claude Code