arkgate 4.6.2 → 4.6.4

package/CHANGELOG.md

@@ -5,6 +5,51 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.6.4 — 2026-08-18
+
+**Patch** over **4.6.3**. `ark upgrade` now tells Codex users how to activate the local
+`apply_patch` boundary after upgrading: refresh the project hook, restart Codex/local Desktop,
+trust the exact hook definition, and verify `doctor.writePath` after a governed patch.
+**No required config migration.**
+
+**Status: prepared** (not yet on npm `latest`; see `docs/releases/4.6.4.md`).
+
+### Changed
+
+- **Upgrade JSON:** `whatsNew.items` includes stable id `codex-hard-write` with the exact
+  `--install-agent-gates --tools codex --force` command and evidence to inspect.
+- **Upgrade human output:** **Suggested improvements** prints the same refresh/restart/trust/check
+  path on preview and apply, including nothing-to-apply previews.
+- **Upgrade skill:** flat and Agent Skills guidance tells Codex to exercise a governed
+  `apply_patch` and keeps hosted/specialized/shell/direct/incomplete/human paths CI-backed.
+- **Stale MCP fail-closed:** when process version no longer matches the project install,
+  `ark_identity` reports non-authoritative evidence and project tools return
+  `PROCESS_PACKAGE_STALE` until restart/retarget.
+- **Global CLI handoff:** a modern stale global `ark upgrade` delegates the original invocation
+  to the project-local `node_modules/arkgate/bin/ark.mjs` instead of managing from the wrong PATH
+  version. Pre-4.6.4 globals still require one `npx arkgate upgrade` entry.
+
+## 4.6.3 — 2026-08-18
+
+**Patch** over **4.6.2**. Codex CLI and local ChatGPT Desktop/App Server now get a
+runtime-proven pre-write block for complete `apply_patch` calls. ArkGate accepts the current
+`tool_input.command` payload, while incomplete, hosted, specialized, shell/direct, and human
+write paths remain CI-backed. **No required config migration.**
+
+**Status: published** (npm `latest` from signed tag `v4.6.3`; OIDC run `32167523804`;
+see `docs/releases/4.6.3.md`).
+
+### Changed
+
+- **Codex hook payload:** current `PreToolUse` `apply_patch` bodies are read from
+  `tool_input.command`; historical patch/input/content fields stay compatible.
+- **Operation-scoped hard write:** a complete trusted and runtime-observed local patch can report
+  `hard:true` and exit `2` before disk mutation. Hook files alone stay unverified.
+- **Honesty surfaces:** host matrix, doctor/status, `--require-write-hook codex`, onboarding,
+  upgrade self-service, skills, and public docs now share the same boundary.
+- **All-path backstop:** required `arkgate-check --strict-merge` CI remains mandatory. MCP stays
+  advisory and repair reinjection is not claimed.
+
 ## 4.6.2 — 2026-08-16
 
 **Patch** over **4.6.1**. First-contact copy: a newcomer (human or coding agent) sees what
@@ -12,7 +57,7 @@ to do in a few lines — `arkgate` / `arkgate-check --help`, start wrap-up, doct
 #1, write-gate deny, SessionStart, MCP tool order, and the five doors. Same 13 skill names.
 **No required config migration.**
 
-**Status: prepared** (not yet on npm `latest`; see `docs/releases/4.6.2.md`).
+**Status: published** (on npm `latest`; see `docs/releases/4.6.2.md`).
 
 ### Changed
 

package/README.md

@@ -16,9 +16,9 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.6.1** is on npm `latest` — five doors + a lock on the constitution.
-> **4.6.2** is prepared on this tree (first-contact copy; not yet `latest`).
-> [4.6.2 notes](docs/releases/4.6.2.md) · [4.6.1](docs/releases/4.6.1.md) · [4.6.0](docs/releases/4.6.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.6.3** is on npm `latest` — Codex CLI/local Desktop hard-block complete trusted `apply_patch`.
+> **4.6.4 is prepared** — `ark upgrade` tells Codex how to refresh, trust, restart, and verify it.
+> [4.6.4 notes](docs/releases/4.6.4.md) · [4.6.3](docs/releases/4.6.3.md) · [4.6.2](docs/releases/4.6.2.md) · [4.6.1](docs/releases/4.6.1.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -117,14 +117,15 @@ Details: [docs/use.md](docs/use.md).
 | Claude Code | **Hard** block for listed ops (PreToolUse `Write` / `Edit` / `MultiEdit`) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |
 | Grok Build | **Hard** block for listed ops (PreToolUse `write` / `search_replace` (plus aliases)) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |
 | Google Antigravity | **Hard** block for listed ops (PreToolUse `write_to_file` / `replace_file_content` / `multi_replace_file_content`) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |
-| Cursor | **Hard** block for listed ops (preToolUse `Write` / `StrReplace`) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Envelope may emit (`--hook-repair`); reinjection **not** guaranteed (advisory host) |
-| OpenAI Codex | **Advisory / best-effort** at write (not equivalent to Claude/Grok/Cursor hard block) | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Envelope may emit (`--hook-repair`); reinjection **not** guaranteed (advisory host) |
+| Cursor | **Hard** block for listed ops (preToolUse `Write` / `StrReplace`) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Envelope may emit (`--hook-repair`); reinjection **not** guaranteed |
+| OpenAI Codex | **Hard** block for listed ops (PreToolUse `apply_patch` in Codex CLI and local ChatGPT Desktop/App Server) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Envelope may emit (`--hook-repair`); reinjection **not** guaranteed |
 | OpenCode | **Advisory / best-effort** at write (MCP + optional plugin; not a hard boundary) | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | No hard-boundary payload |
 
 **Read the CI column:** for every host, the repository-wide hard guarantee is a **required**
 GitHub **status context** that runs the CLI — not “CI file present,” and not the CLI binary name alone.
-Codex/OpenCode never get a fake hard write claim. Cursor hard write covers only listed
-`preToolUse` ops when `.cursor/hooks.json` is installed and trusted — Shell/Tab/human edits still rely on CI.
+Codex hard write covers only a complete local `apply_patch`; Cursor covers only listed
+`preToolUse` ops. In both cases the project hook must be installed + trusted, while shell/direct
+filesystem writes, hosted or specialized opt-out paths, and human edits still rely on CI.
 
 This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run `arkgate-check --doctor` (or `ark-check --doctor`) for the evidence actually detected in the current repository.
 <!-- arkgate-host-support:end -->
@@ -133,10 +134,11 @@ This table describes the supported profile **after its files are installed and t
 
 The split above is a deliberate trade-off, not a gap. ArkGate validates at the earliest boundary
 each host offers and enforces at the earliest boundary a repository can make non-bypassable: the
-required merge status. Hard hooks (Claude Code, Grok Build, Google Antigravity) deny the listed
-write operations at write time; advisory surfaces (MCP, rules, OpenCode plugins) coach the agent
-while it works. But any local boundary can be routed around — another tool, a direct filesystem
-write, a human edit — so the only guarantee ArkGate claims for every path is the
+required merge status. Hard hooks (Claude Code, Grok Build, Google Antigravity, Cursor, and
+Codex’s complete local `apply_patch`) deny their listed write operations at write time; advisory
+surfaces (MCP, rules, OpenCode plugins) coach the agent while it works. But any local boundary can
+be routed around — another tool, a hosted/specialized path, a direct filesystem write, or a human
+edit — so the only guarantee ArkGate claims for every path is the
 `arkgate-check --strict-merge` check, and only when the repository makes that status required.
 Local checks optimize feedback speed; the merge gate owns correctness.
 
@@ -214,8 +216,11 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Current release (4.6.1 on npm `latest`) | [docs/releases/4.6.1.md](docs/releases/4.6.1.md) · [CHANGELOG](CHANGELOG.md) |
-| Prepared (4.6.2 — not yet `latest`) | [docs/releases/4.6.2.md](docs/releases/4.6.2.md) |
+| Current release (4.6.3 on npm `latest`) | [docs/releases/4.6.3.md](docs/releases/4.6.3.md) · [CHANGELOG](CHANGELOG.md) |
+| Prepared patch (4.6.4) | [docs/releases/4.6.4.md](docs/releases/4.6.4.md) |
+| Prior (4.6.2) | [docs/releases/4.6.2.md](docs/releases/4.6.2.md) |
+| Prior (4.6.1) | [docs/releases/4.6.1.md](docs/releases/4.6.1.md) |
+| Prior (4.6.0) | [docs/releases/4.6.0.md](docs/releases/4.6.0.md) |
 | Prior (4.5.7) | [docs/releases/4.5.7.md](docs/releases/4.5.7.md) |
 | Prior (4.5.0) | [docs/releases/4.5.0.md](docs/releases/4.5.0.md) |
 | Prior (4.4.0) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) |

package/bin/ark-mcp-runtime.mjs

@@ -358,6 +358,7 @@ function mapAntigravityToolCall(toolCall) {
  * Antigravity: { toolCall: { name, args: { TargetFile, CodeContent, … } } }
  * Cursor:      { tool_name, tool_input, hook_event_name?, workspace_roots? }
  *              Write uses `contents`; StrReplace maps to Edit (path/old_string/new_string).
+ * Codex:       { tool_name: "apply_patch", tool_input: { command: "*** Begin Patch..." } }
  */
 function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_HOOK_EVENT)) {
   const antigravityStyle =
@@ -669,7 +670,10 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       attemptContext?.grokHookEvent ?? Boolean(process.env.GROK_HOOK_EVENT)
     );
   if (toolName === 'ApplyPatch') {
-    const patch = toolInput.patch ?? toolInput.input ?? toolInput.content;
+    // Current Codex CLI/Desktop hook schema uses tool_input.command. Keep the
+    // historical fields for older clients and existing integration fixtures.
+    const patch =
+      toolInput.command ?? toolInput.patch ?? toolInput.input ?? toolInput.content;
     const parsedPatch = codexPatchWrites(patch, args.root);
     // Codex ApplyPatch is only preflighted when Ark can reconstruct every file operation.
     // An incomplete reconstruction must not be mislabeled as atomic or hard enforcement.
@@ -1956,11 +1960,14 @@ export async function runArkMcp({ hookInput } = {}) {
   }
 
   function contextFor(binding) {
+    const processPackage = processPackageHonesty();
     return {
       projectIdentity,
       binding,
-      authoritative: binding.authoritative,
-      processPackage: processPackageHonesty(),
+      // A correctly bound project is still non-authoritative when this long-lived
+      // process loaded a different package version than the project now resolves.
+      authoritative: binding.authoritative && !processPackage.processStale,
+      processPackage,
     };
   }
 
@@ -2037,13 +2044,36 @@ export async function runArkMcp({ hookInput } = {}) {
     );
   }
 
+  function staleProcessFailureResult(binding) {
+    const processPackage = processPackageHonesty();
+    return withProjectContext(
+      {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              ok: false,
+              error: {
+                code: 'PROCESS_PACKAGE_STALE',
+                message: processPackage.nextAction,
+              },
+            }),
+          },
+        ],
+        isError: true,
+      },
+      binding
+    );
+  }
+
   const TOOLS = [
     {
       name: 'ark_identity',
       description:
         'First call. Prove this MCP process is the right project: pass project.expectedRoot ' +
         '(exact absolute root) and reuse the returned projectId. Do this before any other Ark tool. ' +
-        'A missing, unmatched, or different root means restart the host and use the local CLI.',
+        'A missing/unmatched root or processPackage.processStale means restart/retarget the host ' +
+        'and use the project-local CLI until identity and package versions align.',
       inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -3001,6 +3031,13 @@ export async function runArkMcp({ hookInput } = {}) {
           reply(id, bindingFailureResult(binding));
           return;
         }
+        // Keep ark_identity available so the host can diagnose the stale process,
+        // but fail every project tool closed until the MCP server restarts on the
+        // version installed for this root.
+        if (params?.name !== 'ark_identity' && processPackageHonesty().processStale) {
+          reply(id, staleProcessFailureResult(binding));
+          return;
+        }
         try {
           reply(id, withProjectContext(handler(params, binding), binding));
         } catch (error) {

package/bin/ark.mjs

@@ -831,6 +831,7 @@ async function main() {
         packageInstallArgv,
         runArkCheck,
         cliVersion: cliVersion(),
+        rawArgv: process.argv.slice(2),
         shouldSkipArkgateInstall,
       });
     } catch (error) {

package/bin/lib/ci-and-commands.mjs

@@ -370,9 +370,10 @@ ${steps}
 ${placementBody}
 
 The project is only considered Ark-enforced when its host-appropriate write path is configured
-and the CI check passes. Only Claude/Grok/Antigravity/Cursor provide a hard local write boundary
-(Cursor: Write/StrReplace when .cursor/hooks.json is trusted); Codex/OpenCode use
-advisory MCP plus CI. The experimental runtime is not required.
+and the CI check passes. Claude/Grok/Antigravity/Cursor provide hard local boundaries for their
+listed operations. Codex provides a hard boundary for complete local apply_patch when
+.codex/hooks.json is trusted and runtime-observed; hosted/specialized/direct-write paths remain
+CI-backed. OpenCode uses advisory MCP plus CI. The experimental runtime is not required.
 `;
 }
 

package/bin/lib/first-run-help.mjs

@@ -88,8 +88,8 @@ Options:
   --remove-host <host>
                Preview or apply removal of that compact host integration; re-add it with --tools <host>.
   --require-write-hook <host>
-               Require and verify a hard local write hook for Claude, Grok, Antigravity, or Cursor.
-               Codex/OpenCode are advisory-write plus hard CI merge only; impossible requests fail before any write.
+               Require and verify a hard local write hook for Claude, Grok, Antigravity, Cursor, or Codex.
+               Codex covers complete local apply_patch only; OpenCode is advisory-write plus hard CI merge.
 
 Interactive mode (TTY, no --yes): asks what application shape you are building and maps it to a preset.
 Non-interactive (no TTY): uses the same defaults as --yes — never calls readline on a null interface.
@@ -183,10 +183,10 @@ export function checkUsageAll() {
     'transition. Weakening or judgment-required findings fail unless --policy-ack names',
     'every finding and is bound to both policy hashes. Use --policy-base/--policy-base-ref',
     'for an explicit comparison; ARK_POLICY_BASE_REF is the CI environment equivalent.',
-    'Add --require-write-hook claude|grok|antigravity|cursor to validate a hard local write',
-    'boundary for that specific host. Codex and OpenCode expose advisory MCP (plus best-effort',
-    'hooks where applicable) and the shared CI check; merge blocking requires repository policy',
-    'to make that status required.',
+    'Add --require-write-hook claude|grok|antigravity|cursor|codex to validate a hard local',
+    'write boundary for that specific host. Codex covers complete local apply_patch only;',
+    'hosted/specialized/direct-write paths and OpenCode remain CI-backed. Merge blocking requires',
+    'repository policy to make the shared CI status required.',
     '',
     '--require-gates implies --strict-config and fails when the Ark contract in AGENTS.md,',
     'the project-rooted Ark server in .mcp.json, or fail-closed CI is missing/invalid.',
@@ -194,7 +194,7 @@ export function checkUsageAll() {
     '',
     '--install-agent-gates writes AGENTS.md, .mcp.json, and the CI workflow for every',
     'project, plus tool-specific templates. Known tools: claude, cursor, codex, grok',
-    '(Claude/Grok/Antigravity/Cursor hard-write hooks when covered; Codex advisory MCP;',
+    '(Claude/Grok/Antigravity/Cursor hard-write hooks when covered; Codex hard local apply_patch;',
     'shared CI check for all) and',
     'windsurf, cline, copilot, kiro, roo, continue, gemini',
     '(instruction-tier rule files derived from the same contract).',

package/bin/lib/host-support-matrix.mjs

@@ -17,7 +17,7 @@
  */
 function hostProfile(label, hookPath, hookSurface, hookOperations, hardWrite, repairPayload, extras = {}) {
   // EH07: repair envelope emission ≠ reinjection guarantee.
-  // Codex hooks may emit --hook-repair JSON while reinjection stays host-dependent / not hard.
+  // Cursor/Codex hooks may emit --hook-repair JSON while reinjection stays host-dependent.
   const repairEnvelopeEmitted =
     extras.repairEnvelopeEmitted === true || repairPayload === true;
   const repairReinjectionGuaranteed = hardWrite === true && repairPayload === true;
@@ -94,15 +94,15 @@ export const HOST_SUPPORT_MATRIX = Object.freeze({
   codex: hostProfile(
     'OpenAI Codex',
     '.codex/hooks.json',
-    'Best-effort PreToolUse `apply_patch`; Code Mode hosts may bypass the event',
+    'PreToolUse `apply_patch` in Codex CLI and local ChatGPT Desktop/App Server',
     ['apply_patch'],
-    false,
+    true,
     false,
     {
-      // Install writes --hook-repair; envelope can be emitted; reinjection is not guaranteed.
+      // Install writes --hook-repair; envelope can emit, but host reinjection is not guaranteed.
       repairEnvelopeEmitted: true,
       operationCoverage: {
-        apply_patch: false,
+        apply_patch: true,
         shell: false,
         'pre-commit': false,
       },
@@ -152,15 +152,12 @@ export function renderHostSupportMatrixMarkdown() {
   const rows = HOST_SUPPORT_HOSTS.map((host) => {
     const profile = HOST_SUPPORT_MATRIX[host];
     const capabilities = profile.capabilities;
-    // Fail-closed honesty: Codex/OpenCode never claim hard write; CI is required-status.
-    // Cursor claims hard only for listed preToolUse ops when hooks are installed + trusted.
+    // Fail-closed honesty: hard hosts claim only listed operations when hooks are
+    // installed + trusted. OpenCode remains advisory; CI is required-status.
     // hookSurface already includes "PreToolUse/preToolUse …" — do not prefix again.
     let local;
     if (capabilities['hard-write']) {
       local = `**Hard** block for listed ops (${profile.hookSurface}) when installed + trusted`;
-    } else if (host === 'codex') {
-      local =
-        '**Advisory / best-effort** at write (not equivalent to Claude/Grok/Cursor hard block)';
     } else if (host === 'opencode') {
       local =
         '**Advisory / best-effort** at write (MCP + optional plugin; not a hard boundary)';
@@ -172,7 +169,7 @@ export function renderHostSupportMatrixMarkdown() {
     if (capabilities['repair-reinjection-guaranteed']) {
       repair = 'Emitted on hook deny; host must re-inject (hard path when installed + trusted)';
     } else if (capabilities['repair-envelope-emitted']) {
-      repair = 'Envelope may emit (`--hook-repair`); reinjection **not** guaranteed (advisory host)';
+      repair = 'Envelope may emit (`--hook-repair`); reinjection **not** guaranteed';
     } else {
       repair = 'No hard-boundary payload';
     }
@@ -188,8 +185,9 @@ ${rows}
 
 **Read the CI column:** for every host, the repository-wide hard guarantee is a **required**
 GitHub **status context** that runs the CLI — not “CI file present,” and not the CLI binary name alone.
-Codex/OpenCode never get a fake hard write claim. Cursor hard write covers only listed
-\`preToolUse\` ops when \`.cursor/hooks.json\` is installed and trusted — Shell/Tab/human edits still rely on CI.
+Codex hard write covers only a complete local \`apply_patch\`; Cursor covers only listed
+\`preToolUse\` ops. In both cases the project hook must be installed + trusted, while shell/direct
+filesystem writes, hosted or specialized opt-out paths, and human edits still rely on CI.
 
 This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run \`arkgate-check --doctor\` (or \`ark-check --doctor\`) for the evidence actually detected in the current repository.`;
 }
@@ -226,8 +224,8 @@ export function doctorWritePathHonestyMessage(activeHost, hardWriteActive) {
   if (host === 'cursor' && !hardWriteActive) {
     return `Cursor: pre-write block is supported for Write/StrReplace when .cursor/hooks.json is installed + trusted; without runtime-observed hook evidence, the block is unverified. ${mergeBoundary}.`;
   }
-  if (host === 'codex') {
-    return `Codex: edits are warning only (not blocked) at write time. ${mergeBoundary}.`;
+  if (host === 'codex' && !hardWriteActive) {
+    return `Codex: a trusted PreToolUse hook can block complete local apply_patch calls in CLI and Desktop; without fresh runtime-observed apply_patch evidence, the block is unverified. Specialized/hosted paths and direct writes still rely on CI. ${mergeBoundary}.`;
   }
   if (host === 'opencode') {
     return `OpenCode: edits are warning only (not blocked). ${mergeBoundary}.`;

package/bin/lib/managed-upgrade.mjs

@@ -725,7 +725,7 @@ export function buildPostUpgradeChecks(root, options = {}) {
     neverGateInput: true,
     checks,
     mcpNote:
-      'If you used Ark MCP this session: restart/retarget MCP after package bump so process arkgateVersion matches project install; always pass project.expectedRoot + expectedProjectId (WI01). Prefer project-local CLI until identity matched and versions align.',
+      'If you used Ark MCP this session: restart/retarget after the package bump. A stale process is non-authoritative and project tools return PROCESS_PACKAGE_STALE; always pass project.expectedRoot + expectedProjectId. Prefer project-local CLI until identity and package versions align.',
   };
 }
 

package/bin/lib/status-command.mjs

@@ -299,7 +299,7 @@ export function collectStatusFacts(options = {}) {
       ? writePath.activeHost.trim().toLowerCase()
       : String(activeHost).trim().toLowerCase();
   const matrix = HOST_SUPPORT_MATRIX[hostKey] ?? null;
-  // Soft only when the host is known and matrix hard-write is false (Cursor/Codex/OpenCode).
+  // Soft only when the host is known and matrix hard-write is false (currently OpenCode).
   const softWriteHost = Boolean(matrix && matrix.capabilities?.['hard-write'] !== true);
   const writePathHonesty = buildWritePathHonesty(hostKey, hardWriteActive, {
     packageInstalled: writePath?.enforcementState?.localWrite?.installed !== false,

package/bin/lib/upgrade-command.mjs

@@ -148,8 +148,9 @@ function staleCliRefuseMessage(detail) {
  * project's installed arkgate. Legacy global 2.x mutates skills; a newer
  * project pin must not be managed by an older outside-tree binary.
  *
- * Allow: no local install; CLI package root inside the project install tree
- * (realpath); running CLI version >= project installed version (including newer globals).
+ * Allow directly: no local install or CLI package root inside the project install tree
+ * (realpath). Any outside-tree modern CLI prefers a project-local handoff, even at the same
+ * or newer version, so one checkout never manages another through PATH state.
  *
  * @param {string} root project root for --root
  * @param {{
@@ -157,7 +158,7 @@ function staleCliRefuseMessage(detail) {
  *   cliPackageRoot?: string|null,
  *   projectPackageJsonPath?: string|null,
  * }} [options]
- * @returns {{ refuse: boolean, reason: string, message?: string, cliVersion?: string|null, projectVersion?: string|null, cliPackageRoot?: string|null, projectPackageRoot?: string|null }}
+ * @returns {{ refuse: boolean, handoff?: boolean, reason: string, message?: string, cliVersion?: string|null, projectVersion?: string|null, cliPackageRoot?: string|null, projectPackageRoot?: string|null }}
  */
 export function evaluateStaleUpgradeCli(root, options = {}) {
   const projectPkgPath =
@@ -272,7 +273,8 @@ export function evaluateStaleUpgradeCli(root, options = {}) {
 
   return {
     refuse: false,
-    reason: 'outside-cli-ok',
+    handoff: true,
+    reason: 'outside-cli-project-local-preferred',
     cliVersion,
     projectVersion,
     cliPackageRoot,
@@ -325,6 +327,15 @@ function verify(root, json, arkCheck, runArkCheck) {
   return { exitCode: result.status ?? 1, stderr: result.stderr?.trim() || undefined };
 }
 
+function runProjectLocalCli({ root, script, argv }) {
+  const result = spawnSync(process.execPath, [script, ...argv], {
+    cwd: root,
+    stdio: 'inherit',
+    env: { ...process.env, ARK_PROJECT_LOCAL_HANDOFF: '1' },
+  });
+  return result.status ?? 1;
+}
+
 export function runUpgradeCommand(args, dependencies) {
   const root = args.root;
   // Fail closed before install/plan when PATH resolves a global/stale CLI older
@@ -339,6 +350,28 @@ export function runUpgradeCommand(args, dependencies) {
           cliVersion: dependencies?.cliVersion,
           cliPackageRoot: dependencies?.cliPackageRoot,
         });
+  if (staleGuard?.refuse || staleGuard?.handoff) {
+    const projectLocalScript =
+      typeof staleGuard.projectPackageRoot === 'string'
+        ? path.join(staleGuard.projectPackageRoot, 'bin', 'ark.mjs')
+        : null;
+    if (
+      process.env.ARK_PROJECT_LOCAL_HANDOFF !== '1' &&
+      Array.isArray(dependencies?.rawArgv) &&
+      projectLocalScript &&
+      fs.existsSync(projectLocalScript)
+    ) {
+      const handoff =
+        typeof dependencies.runProjectLocalCli === 'function'
+          ? dependencies.runProjectLocalCli
+          : runProjectLocalCli;
+      return handoff({
+        root,
+        script: projectLocalScript,
+        argv: dependencies.rawArgv,
+      });
+    }
+  }
   if (staleGuard?.refuse) {
     const message = staleGuard.message || 'Refusing ark upgrade: stale CLI.';
     if (args.json) {

package/bin/lib/upgrade-whats-new.mjs

@@ -65,6 +65,15 @@ export function buildUpgradeWhatsNewSuggestions() {
         why:
           'Project skills follow this pin. Shared homes stay on the newest ArkGate on the machine (additive; never downgrade). Orphan 2.x global skills stop coaching the wrong version.',
       },
+      {
+        id: 'codex-hard-write',
+        title: 'Codex complete local apply_patch block',
+        try: 'npx arkgate-check --install-agent-gates --tools codex --force',
+        inspect:
+          '.codex/hooks.json trust + doctor.writePath after a runtime-observed apply_patch',
+        why:
+          'After upgrade, refresh the project hook, restart Codex or local Desktop, and trust the exact hook definition. Only a complete observed apply_patch is hard; hosted, specialized, shell/direct, incomplete, and human paths still rely on required CI.',
+      },
       {
         id: 'deep-module-coach',
         title: 'Deep-module coach (hot paths + deepening)',
@@ -129,7 +138,16 @@ export function buildUpgradeWhatsNewSuggestions() {
         try: 'ark_identity with project.expectedRoot; read processPackage on every tool',
         inspect: 'processPackage.processPackageMismatch / processStale + nextAction',
         why:
-          'One user, many checkouts: after package bump, restart MCP so process arkgateVersion matches install. Prefer project-local CLI until identity matched and versions align.',
+          'One user, many checkouts: after package bump, restart MCP so process arkgateVersion matches install. A stale process is non-authoritative and project tools fail closed until restart.',
+      },
+      {
+        id: 'process-version-recovery',
+        title: 'Stale MCP / global CLI recovery',
+        try: 'npx arkgate upgrade --json',
+        inspect:
+          'processPackage.processStale + PROCESS_PACKAGE_STALE; project-local CLI handoff for stale global upgrade',
+        why:
+          'A long-lived MCP on an older package can no longer return authoritative project evidence. A newer global ArkGate that is older than this project automatically hands `ark upgrade` to the project-local CLI instead of staying stuck on PATH.',
       },
     ],
   };

package/bin/lib/write-path-capabilities.mjs

@@ -219,6 +219,9 @@ function requiredWriteOperations(relativePath) {
   if (relativePath === '.cursor/hooks.json' || relativePath.startsWith('.cursor/hooks')) {
     return ['Write', 'StrReplace'];
   }
+  if (relativePath === '.codex/hooks.json' || relativePath.startsWith('.codex/hooks')) {
+    return ['apply_patch'];
+  }
   return ['Write', 'Edit', 'MultiEdit'];
 }
 
@@ -445,6 +448,7 @@ export function detectWritePathInventory(root) {
   const grokHook = hookEvidence(root, '.grok/hooks/ark-write-gate.json');
   const antigravityHook = hookEvidence(root, '.agents/hooks.json');
   const cursorHook = cursorHookEvidence(root);
+  const codexHook = hookEvidence(root, '.codex/hooks.json');
   const hosts = {
     claude: hostRecord(
       claudeHook.hard,
@@ -478,11 +482,11 @@ export function detectWritePathInventory(root) {
       [],
       merge
     ),
-    // Codex 0.123+ emits PreToolUse for the native apply_patch handler, but some
-    // Code Mode hosts execute deferred nested writes without dispatching that
-    // project hook. Keep the installed hook as best-effort protection; do not
-    // report a hard boundary that cannot be verified for every write surface.
-    codex: hostRecord([], codexMcpEvidence(root), [], merge),
+    // Current Codex CLI and local ChatGPT Desktop/App Server synchronously run
+    // PreToolUse for apply_patch. Disk evidence remains unverified until a fresh
+    // covered invocation; hosted/specialized/direct-write paths stay outside scope.
+    // Repair envelopes may emit, but host reinjection is not guaranteed.
+    codex: hostRecord(codexHook.hard, codexMcpEvidence(root), [], merge),
     // OpenCode: MCP only (plugin hooks are incomplete / subagent-bypassable).
     opencode: hostRecord([], opencodeMcpEvidence(root), [], merge),
   };

package/bin/lib/write-path-detect.mjs

@@ -111,9 +111,9 @@ export function detectWritePathCapabilities(root, explicitHost, attempt) {
   } else if (mode === 'mcp-only') {
     const honesty =
       activeHost === 'codex'
-        ? 'Codex local write is advisory (MCP + best-effort hooks.json — not a hard boundary; ' +
-          'not equivalent to Claude/Grok PreToolUse hard-write + repair). ' +
-          'The hard merge backstop is CI --strict-merge plus a required status check.'
+        ? 'Codex MCP is advisory because no complete Ark apply_patch hook was detected. ' +
+          'Install and trust .codex/hooks.json for the operation-scoped pre-write block; ' +
+          'CI --strict-merge plus a required status remains the all-path merge boundary.'
         : activeHost === 'opencode'
           ? 'OpenCode local write is advisory (MCP + optional experimental plugin — not a hard boundary; ' +
             'not equivalent to Claude/Grok/Antigravity PreToolUse hard-write). ' +