arkgate 4.8.23 → 4.8.24

package/bin/lib/hook-templates.mjs

@@ -1,22 +1,24 @@
 // Generated from hook-templates.source.mjs — run npm run generate:packaged-tooling.
-import{execCommandParts as l,execRunner as i}from"../ark-shared.mjs";const s="arkgate-mcp";function h(e){const r=i(e);return`${JSON.stringify({version:1,hooks:{preToolUse:[{command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env CURSOR_PROJECT_DIR --config ark.config.json`,matcher:"Write|StrReplace",failClosed:!0,timeout:30}]}},null,2)}
-`}function y(e){const r=i(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",command:`${r} ${s} --session-context --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit",hooks:[{type:"command",command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
-`}function $(e){const r=i(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${s} --session-context --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"ApplyPatch|apply_patch|Write|Edit|MultiEdit",hooks:[{type:"command",timeout:30,command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
-`}function O(e){const{command:r,args:o}=l(e,s,["--root",".","--config","ark.config.json"]),t=a=>a.replace(/\\/g,"\\\\").replace(/"/g,'\\"'),c=o.map(a=>`"${t(a)}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Codex project scope).
+import{execCommandParts as d,execRunner as g}from"../ark-shared.mjs";const p="arkgate-mcp";function S(r){const t=g(r);return`${JSON.stringify({version:1,hooks:{preToolUse:[{command:`${t} ${p} --hook --hook-repair --fail-on-new-smells --root . --root-env CURSOR_PROJECT_DIR --config ark.config.json`,matcher:"Write|StrReplace",failClosed:!0,timeout:30}]}},null,2)}
+`}function R(r){const t=g(r);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",command:`${t} ${p} --session-context --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit",hooks:[{type:"command",command:`${t} ${p} --hook --hook-repair --fail-on-new-smells --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function _(r){const t=g(r);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${t} ${p} --session-context --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"ApplyPatch|apply_patch|Write|Edit|MultiEdit",hooks:[{type:"command",timeout:30,command:`${t} ${p} --hook --hook-repair --fail-on-new-smells --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function C(r){const{command:t,args:o}=d(r,p,["--root",".","--config","ark.config.json"]),e=n=>n.replace(/\\/g,"\\\\").replace(/"/g,'\\"'),s=o.map(n=>`"${e(n)}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Codex project scope).
 # CONFIGURED ON DISK \u2014 RUNTIME NOT VERIFIED.
 # Restart Codex, then call ark_identity with expectedRoot before trusting MCP verdicts.
 [mcp_servers.ark]
-command = "${t(r)}"
-args = [${c}]
-`}function R(e){const{command:r,args:o}=l(e,s,["--root",".","--config","ark.config.json"]),t=o.map(c=>`"${c.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Grok Build project scope).
+command = "${e(t)}"
+args = [${s}]
+`}function E(r){const{command:t,args:o}=d(r,p,["--root",".","--config","ark.config.json"]),e=o.map(s=>`"${s.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Grok Build project scope).
 # Restart Grok (or /mcps \u2192 refresh) after changes. Also loads repo-root .mcp.json.
 [mcp_servers.ark]
-command = "${r.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"
-args = [${t}]
-`}function _(e){const r=i(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${s} --session-context --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit|write|search_replace",hooks:[{type:"command",timeout:30,command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
-`}function A(e){const r=i(e);return`${JSON.stringify({"ark-write-gate":{PreToolUse:[{matcher:"write_to_file|replace_file_content|multi_replace_file_content",hooks:[{type:"command",timeout:30,command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --config ark.config.json`}]}]}},null,2)}
-`}function j(e){const{command:r,args:o}=l(e,s,["--root",".","--config","ark.config.json"]);return`${JSON.stringify({$schema:"https://opencode.ai/config.json",mcp:{ark:{type:"local",command:[r,...o],enabled:!0}}},null,2)}
-`}function E(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o)||!t||typeof t!="object"||Array.isArray(t))return null;const c=t.hooks,p=(Array.isArray(c?.preToolUse)?c.preToolUse:[]).find(n=>n&&typeof n=="object"&&typeof n.command=="string"&&/arkgate-mcp|ark-mcp/.test(n.command)&&/\s--hook(?:\s|$)/.test(` ${n.command} `));if(!p)return null;const m=o.hooks&&typeof o.hooks=="object"&&!Array.isArray(o.hooks)?{...o.hooks}:{},f=Array.isArray(m.preToolUse)?[...m.preToolUse]:[],k=n=>n&&typeof n=="object"&&typeof n.command=="string"&&/arkgate-mcp|ark-mcp/.test(n.command)&&/\s--hook(?:\s|$)/.test(` ${n.command} `)&&(typeof n.matcher!="string"||/Write/.test(n.matcher)||/StrReplace/.test(n.matcher)),g=f.filter(n=>!k(n));m.preToolUse=[...g,p];const u={...o,version:o.version??t.version??1,hooks:m};return`${JSON.stringify(u,null,2)}
-`}function S(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o)||!t||typeof t!="object"||Array.isArray(t))return null;const c=t["ark-write-gate"];if(!c||typeof c!="object")return null;const a={...o,"ark-write-gate":c};return`${JSON.stringify(a,null,2)}
-`}function C(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o))return null;const c={...o};!c.$schema&&t.$schema&&(c.$schema=t.$schema);const a=o.mcp&&typeof o.mcp=="object"&&!Array.isArray(o.mcp)?{...o.mcp}:{};return a.ark=t.mcp.ark,c.mcp=a,`${JSON.stringify(c,null,2)}
-`}export{s as PREFERRED_MCP_BIN,A as antigravityHooks,y as claudeSettings,$ as codexHooks,O as codexProjectConfig,h as cursorHooks,_ as grokHooks,R as grokProjectConfig,S as mergeAntigravityArkHook,E as mergeCursorArkHook,C as mergeOpencodeArkMcp,j as opencodeProjectConfig};
+command = "${t.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"
+args = [${e}]
+`}function v(r){const t=g(r);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${t} ${p} --session-context --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit|write|search_replace",hooks:[{type:"command",timeout:30,command:`${t} ${p} --hook --hook-repair --fail-on-new-smells --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function J(r){const t=g(r);return`${JSON.stringify({"ark-write-gate":{PreToolUse:[{matcher:"write_to_file|replace_file_content|multi_replace_file_content",hooks:[{type:"command",timeout:30,command:`${t} ${p} --hook --hook-repair --fail-on-new-smells --root . --config ark.config.json`}]}]}},null,2)}
+`}function N(r){const{command:t,args:o}=d(r,p,["--root",".","--config","ark.config.json"]);return`${JSON.stringify({$schema:"https://opencode.ai/config.json",mcp:{ark:{type:"local",command:[t,...o],enabled:!0}}},null,2)}
+`}function x(r,t){let o,e;try{o=r&&r.trim()?JSON.parse(r):{},e=JSON.parse(t)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o)||!e||typeof e!="object"||Array.isArray(e))return null;const s=e.hooks,k=(Array.isArray(s?.preToolUse)?s.preToolUse:[]).find(a=>a&&typeof a=="object"&&typeof a.command=="string"&&/arkgate-mcp|ark-mcp/.test(a.command)&&/\s--hook(?:\s|$)/.test(` ${a.command} `));if(!k)return null;const u=o.hooks&&typeof o.hooks=="object"&&!Array.isArray(o.hooks)?{...o.hooks}:{},l=Array.isArray(u.preToolUse)?[...u.preToolUse]:[],f=a=>a&&typeof a=="object"&&typeof a.command=="string"&&/arkgate-mcp|ark-mcp/.test(a.command)&&/\s--hook(?:\s|$)/.test(` ${a.command} `)&&(typeof a.matcher!="string"||/Write/.test(a.matcher)||/StrReplace/.test(a.matcher)),c=l.filter(a=>!f(a));u.preToolUse=[...c,k];const i={...o,version:o.version??e.version??1,hooks:u};return`${JSON.stringify(i,null,2)}
+`}const O=/(?:^|[\s/])(?:arkgate-mcp|ark-mcp)(?:\.mjs)?(?:\s|$)/,j=/\s--(?:hook|session-context)(?:\s|$)/;function A(r){return!!r&&typeof r=="object"&&typeof r.command=="string"&&O.test(` ${r.command} `)&&j.test(` ${r.command} `)}function P(r,t){let o,e;try{o=r&&r.trim()?JSON.parse(r):{},e=JSON.parse(t)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o)||!e||typeof e!="object"||Array.isArray(e))return null;const s=e.hooks;if(!s||typeof s!="object"||o.hooks!==void 0&&(!o.hooks||typeof o.hooks!="object"||Array.isArray(o.hooks)))return null;const n={...o.hooks??{}};for(const[k,u]of Object.entries(s)){if(!Array.isArray(u))continue;const l=n[k];if(l!==void 0&&!Array.isArray(l))return null;const f=[];for(const c of l??[]){if(!c||typeof c!="object"||!Array.isArray(c.hooks)){f.push(c);continue}const i=c.hooks.filter(a=>!A(a));i.length===c.hooks.length?f.push(c):i.length>0&&f.push({...c,hooks:i})}n[k]=[...f,...u]}return`${JSON.stringify({...o,hooks:n},null,2)}
+`}function m(r){const t=o=>typeof o=="string"?o.replace(/arkgate@[^\s"']+/g,"arkgate@*"):Array.isArray(o)?o.map(t):o&&typeof o=="object"?Object.fromEntries(Object.keys(o).sort().map(e=>[e,t(o[e])])):o;return JSON.stringify(t(r))}function h(r,t){try{const o=JSON.parse(r),e=JSON.parse(t);return!o||typeof o!="object"||Array.isArray(o)||!e||typeof e!="object"||Array.isArray(e)?null:{existing:o,generated:e}}catch{return null}}function y(r){return{status:"removed",text:Object.keys(r).length===0?null:`${JSON.stringify(r,null,2)}
+`}}function U(r,t){const o=h(r,t);if(!o)return{status:"unreadable"};const{existing:e,generated:s}=o;if(e.hooks===void 0)return{status:"absent"};if(!e.hooks||typeof e.hooks!="object"||Array.isArray(e.hooks))return{status:"unreadable"};const n={...e.hooks};let k=0;for(const[l,f]of Object.entries(s.hooks??{})){if(!Array.isArray(f)||n[l]===void 0)continue;if(!Array.isArray(n[l]))return{status:"unreadable"};const c=new Set(f.map(m)),i=[];for(const a of n[l]){if(!(a&&typeof a=="object"&&Array.isArray(a.hooks)&&a.hooks.some(A))){i.push(a);continue}if(!c.has(m(a)))return{status:"customized"};k+=1}i.length>0?n[l]=i:delete n[l]}if(k===0)return{status:"absent"};const u={...e,hooks:n};return Object.keys(n).length===0&&delete u.hooks,y(u)}function T(r,t){const o=h(r,t);if(!o)return{status:"unreadable"};const{existing:e,generated:s}=o,n=e.hooks?.preToolUse;if(n===void 0)return{status:"absent"};if(!Array.isArray(n))return{status:"unreadable"};const k=new Set((Array.isArray(s.hooks?.preToolUse)?s.hooks.preToolUse:[]).map(m)),u=[];let l=0;for(const i of n){if(!(i&&typeof i=="object"&&typeof i.command=="string"&&/arkgate-mcp|ark-mcp/.test(i.command)&&/\s--hook(?:\s|$)/.test(` ${i.command} `))){u.push(i);continue}if(!k.has(m(i)))return{status:"customized"};l+=1}if(l===0)return{status:"absent"};const f={...e.hooks};u.length>0?f.preToolUse=u:delete f.preToolUse;const c={...e,hooks:f};return Object.keys(f).length===0&&delete c.hooks,Object.keys(c).length===1&&c.version===(s.version??1)&&delete c.version,y(c)}function D(r,t){const o=h(r,t);if(!o)return{status:"unreadable"};const{existing:e,generated:s}=o;if(!Object.prototype.hasOwnProperty.call(e,"ark-write-gate"))return{status:"absent"};if(m(e["ark-write-gate"])!==m(s["ark-write-gate"]))return{status:"customized"};const n={...e};return delete n["ark-write-gate"],y(n)}function H(r,t){let o,e;try{o=r&&r.trim()?JSON.parse(r):{},e=JSON.parse(t)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o)||!e||typeof e!="object"||Array.isArray(e))return null;const s=e["ark-write-gate"];if(!s||typeof s!="object")return null;const n={...o,"ark-write-gate":s};return`${JSON.stringify(n,null,2)}
+`}function w(r,t){let o,e;try{o=r&&r.trim()?JSON.parse(r):{},e=JSON.parse(t)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o))return null;const s={...o};!s.$schema&&e.$schema&&(s.$schema=e.$schema);const n=o.mcp&&typeof o.mcp=="object"&&!Array.isArray(o.mcp)?{...o.mcp}:{};return n.ark=e.mcp.ark,s.mcp=n,`${JSON.stringify(s,null,2)}
+`}export{p as PREFERRED_MCP_BIN,J as antigravityHooks,R as claudeSettings,_ as codexHooks,C as codexProjectConfig,S as cursorHooks,v as grokHooks,E as grokProjectConfig,H as mergeAntigravityArkHook,P as mergeClaudeStyleArkHooks,x as mergeCursorArkHook,w as mergeOpencodeArkMcp,N as opencodeProjectConfig,D as removeAntigravityArkHook,U as removeClaudeStyleArkHooks,T as removeCursorArkHook};

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

@@ -37,7 +37,9 @@ function hostProfile(label, hookPath, hookSurface, hookOperations, hardWrite, re
     }),
     // Host-native "deny when the checker cannot run" flag (FS-permission analog).
     // required = schema field must be true for hard-write evidence (Cursor failClosed).
-    // unsupported = host has no documented flag; hook-crash behavior is host-owned.
+    // unsupported = host has no documented flag. ark-mcp --hook fails closed itself
+    // (exit 2 / host deny) when its checker cannot run for a governed source write;
+    // only a crash of node itself before the launcher runs stays host-owned.
     // none = advisory host; no local write block.
     nativeFailClosed: extras.nativeFailClosed ?? (hardWrite ? 'unsupported' : 'none'),
     // EH07 minimum ops matrix (hard=false for soft hosts on every listed op).

package/bin/lib/import-resolve.mjs

@@ -56,7 +56,19 @@ export function readTsconfigAliases(ts, root) {
     if (!configPath) return { baseUrl: root, aliases: [] };
     const read = ts.readConfigFile(configPath, ts.sys.readFile);
     if (read.error) return { baseUrl: root, aliases: [] };
-    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(configPath));
+    // Options-only parse: `fileNames` are unused here. With the real `ts.sys` the
+    // parser walked the whole `include` tree on every write-hook call (#205 twin).
+    const optionsOnlyHost = {
+      useCaseSensitiveFileNames: ts.sys.useCaseSensitiveFileNames,
+      readDirectory: () => [],
+      fileExists: (fileName) => ts.sys.fileExists(fileName),
+      readFile: (fileName) => ts.sys.readFile(fileName),
+    };
+    const parsed = ts.parseJsonConfigFileContent(
+      read.config,
+      optionsOnlyHost,
+      path.dirname(configPath)
+    );
     const opts = parsed.options || {};
     const baseUrl = opts.baseUrl || path.dirname(configPath);
     const aliases = [];

package/bin/lib/install-migrate.mjs

@@ -10,6 +10,7 @@ import {
   execRunner,
   presentLockfiles,
 } from '../ark-shared.mjs';
+import { npxArkgatePrefixLength } from './package-manager.mjs';
 import {
   codexPromptsDir,
   codexSkillsDir,
@@ -29,6 +30,7 @@ import {
   grokHooks,
   grokProjectConfig,
   mergeAntigravityArkHook,
+  mergeClaudeStyleArkHooks,
   mergeCursorArkHook,
   mergeOpencodeArkMcp,
   opencodeProjectConfig,
@@ -39,6 +41,7 @@ import {
   compactRouterHost,
   mergeArkMcpJson,
   MCP_JSON_GATE_FILES,
+  CLAUDE_STYLE_HOOK_FILES,
   writeTemplate,
 } from './gate-files.mjs';
 import {
@@ -119,7 +122,10 @@ export function staleRunnerGateFiles(root) {
       continue;
     }
     const ark = json?.mcpServers?.ark;
-    if (ark && ark.command && ark.command !== want.split(' ')[0]) stale.push(rel);
+    if (!ark || !ark.command) continue;
+    // Unpinned project: a bare `npx <bin>` MCP entry 404s the same way a text command does.
+    const barePinnedNpx = want.startsWith('npx ') && npxArkgatePrefixLength(ark.args) === 0;
+    if (ark.command !== want.split(' ')[0] || barePinnedNpx) stale.push(rel);
   }
   return stale;
 }
@@ -341,6 +347,18 @@ export function runMigrateCommands(root) {
   warnLockfileConflict(root);
 }
 
+/** Shared host files Ark merges into (keeps sibling servers / hooks / keys). */
+function mergeableGateFile(relativePath) {
+  if (relativePath === 'opencode.json') return { fn: mergeOpencodeArkMcp, forceReplaces: false };
+  if (relativePath === '.cursor/hooks.json') return { fn: mergeCursorArkHook, forceReplaces: false };
+  if (relativePath === '.agents/hooks.json') return { fn: mergeAntigravityArkHook, forceReplaces: false };
+  if (CLAUDE_STYLE_HOOK_FILES.includes(relativePath)) {
+    return { fn: mergeClaudeStyleArkHooks, forceReplaces: true };
+  }
+  if (MCP_JSON_GATE_FILES.includes(relativePath)) return { fn: mergeArkMcpJson, forceReplaces: true };
+  return null;
+}
+
 export function runInstallAgentGates(args) {
   const root = args.root;
   if (args.migrateCommands) {
@@ -454,6 +472,11 @@ export function runInstallAgentGates(args) {
         `Added package.json script "typecheck": "${typecheckBootstrap.script}" (tsconfig present; local/CI parity).`
       );
     }
+    if (typecheckBootstrap.reason === 'no-typescript' && !args.compact && !args.json) {
+      console.log(
+        'tsconfig/jsconfig found but typescript is not a dependency — skipped the "typecheck" script and CI step (add typescript as a devDependency, then "typecheck": "tsc --noEmit").'
+      );
+    }
   }
   const catalog = buildManagedAssetCatalog({
     root,
@@ -518,81 +541,24 @@ export function runInstallAgentGates(args) {
       if (merged === existing) return { relativePath, status: 'skipped' };
       return writeTemplate(root, relativePath, merged, true);
     }
-    if (relativePath === 'opencode.json') {
-      const fullPath = path.join(root, relativePath);
-      let existing = '';
-      try {
-        existing = fs.readFileSync(fullPath, 'utf8');
-      } catch {
-        // Missing project config → write the generated Ark MCP block.
-      }
-      if (!existing) {
-        return writeTemplate(root, relativePath, content, true);
-      }
-      const merged = mergeOpencodeArkMcp(existing, content);
-      if (merged == null) {
-        return { relativePath, status: 'skipped-non-ark' };
-      }
-      if (merged === existing) return { relativePath, status: 'skipped' };
-      return writeTemplate(root, relativePath, merged, true);
-    }
-    if (relativePath === '.cursor/hooks.json') {
-      const fullPath = path.join(root, relativePath);
-      let existing = '';
-      try {
-        existing = fs.readFileSync(fullPath, 'utf8');
-      } catch {
-        // Missing hooks file → write generated Cursor preToolUse gate.
-      }
-      if (!existing) {
-        return writeTemplate(root, relativePath, content, true);
-      }
-      const merged = mergeCursorArkHook(existing, content);
-      if (merged == null) {
-        return { relativePath, status: 'skipped-non-ark' };
-      }
-      if (merged === existing) return { relativePath, status: 'skipped' };
-      // Upsert Ark preToolUse without requiring --force; never wipe sibling hooks.
-      return writeTemplate(root, relativePath, merged, true);
-    }
-    if (relativePath === '.agents/hooks.json') {
-      const fullPath = path.join(root, relativePath);
-      let existing = '';
-      try {
-        existing = fs.readFileSync(fullPath, 'utf8');
-      } catch {
-        // Missing hooks file → write generated ark-write-gate map.
-      }
-      if (!existing) {
-        return writeTemplate(root, relativePath, content, true);
-      }
-      const merged = mergeAntigravityArkHook(existing, content);
-      if (merged == null) {
-        return { relativePath, status: 'skipped-non-ark' };
-      }
-      if (merged === existing) return { relativePath, status: 'skipped' };
-      // Upsert ark-write-gate without requiring --force; never wipe sibling named hooks.
-      return writeTemplate(root, relativePath, merged, true);
-    }
-    if (MCP_JSON_GATE_FILES.includes(relativePath)) {
-      const fullPath = path.join(root, relativePath);
+    const merge = mergeableGateFile(relativePath);
+    if (merge) {
+      // Upsert Ark's entry into a shared host file without --force; never wipe sibling keys.
       let existing = '';
       try {
-        existing = fs.readFileSync(fullPath, 'utf8');
+        existing = fs.readFileSync(path.join(root, relativePath), 'utf8');
       } catch {
-        // Missing MCP JSON → write generated ark server.
-      }
-      if (!existing) {
-        return writeTemplate(root, relativePath, content, true);
+        // Missing file → write the generated Ark template.
       }
-      const merged = mergeArkMcpJson(existing, content);
+      if (!existing) return writeTemplate(root, relativePath, content, true);
+      const merged = merge.fn(existing, content);
       if (merged == null) {
-        return args.force
+        // Unmergeable file: never guess. --force replaces it only where that is explicit consent.
+        return merge.forceReplaces && args.force
           ? writeTemplate(root, relativePath, content, true)
           : { relativePath, status: 'skipped-non-ark' };
       }
       if (merged === existing) return { relativePath, status: 'skipped' };
-      // Upsert mcpServers.ark without requiring --force; never wipe sibling servers.
       return writeTemplate(root, relativePath, merged, true);
     }
     return writeTemplate(
@@ -794,14 +760,25 @@ export function runInstallAgentGates(args) {
     }
     if (tools.has('codex') && !args.compact) {
       console.log('  Codex write path (honest):');
-      console.log('    - Local: advisory MCP + best-effort .codex/hooks.json (not a hard boundary).');
-      console.log('    - Hard merge backstop: CI --strict-merge + required status check.');
-      console.log('    - Not equivalent to Claude/Grok PreToolUse hard-write + repair.');
+      console.log('    - Local: .codex/hooks.json PreToolUse hard-blocks a complete local apply_patch (Codex CLI / local Desktop) once the project is trusted and a hook run is runtime-observed; on disk it is configured, not verified.');
+      console.log('    - Outside that claim (hosted tools, hook opt-out, shell writes, incomplete patch reconstruction): CI --strict-merge + required status check.');
+      console.log('    - Repair envelopes may emit, but Codex reinjection is not guaranteed (unlike Claude/Grok hard-write + repair).');
     }
     if (args.codexHome) {
-      console.log(
-        `  Codex: refreshed home skills under ${codexSkillsDir()}/<name>/SKILL.md (Codex skill catalog).`
-      );
+      // Report what the home write actually did (it is skipped when the project catalog exists).
+      if (homeResults.some((r) => r.status === 'written')) {
+        console.log(
+          `  Codex: refreshed home skills under ${codexSkillsDir()}/<name>/SKILL.md (Codex skill catalog).`
+        );
+      } else if (homeResults.some((r) => r.status === 'failed')) {
+        console.log(`  Codex: home skills NOT written under ${codexSkillsDir()} (see failures above).`);
+      } else if (homeResults.length === 0) {
+        console.log(
+          '  Codex: home skills not written — project .agents/skills is the catalog (Codex reads repo scope).'
+        );
+      } else {
+        console.log(`  Codex: home skills under ${codexSkillsDir()} already current (no changes).`);
+      }
     } else if (tools.has('codex') && skills.length > 0 && !args.compact) {
       console.log(
         '  Codex: project skills at `.agents/skills/<name>/SKILL.md` (Agent Skills REPO scope).'

package/bin/lib/invariant-coverage.mjs

@@ -8,6 +8,7 @@
  * Pure CLI helper (bin/lib/invariant-coverage.mjs). Zero Node I/O.
  */
 
+import { findClassDeclarations, findMemberContainers, objectLiteralMemberNames, scanClassMembers, } from './class-source-scan.mjs';
 /** Adopted + catalogued invariants, but no declared tests path (P2 §10). */
 export const INVARIANT_TESTS_PATH_RULE_ID = 'INVARIANT_TESTS_PATH_MISSING';
 export const INVARIANT_TESTS_PATH_MESSAGE = 'This project is adopted and has domain invariants, but ark.config.json does not name a real tests path. Add coverage.testGlobs or coverage.coverageRoots pointing at the folder where those tests live, then re-run. Without that path, coverage is an empty checkbox.';
@@ -185,6 +186,38 @@ function declarationShape(content, name) {
     }
     return undefined;
 }
+/**
+ * `Name.member` coverage: the member must be declared inside the body of
+ * `class Name` (exported, default-exported, abstract, or local), a
+ * `const Name = class { … }` expression, a `namespace Name { … }` (function or
+ * const member), or a `const Name = { … }` object literal, in this file. A
+ * member of another container, a free function, or a file that merely mentions
+ * the name does not count.
+ */
+function classMemberShape(content, className, member) {
+    const hasClassMethod = (body) => scanClassMembers(body).members.some((m) => m.kind === 'method' && m.name === member);
+    for (const decl of findClassDeclarations(content)) {
+        if (decl.name !== className || decl.bodyStart == null)
+            continue;
+        if (hasClassMethod(content.slice(decl.bodyStart, decl.bodyEnd ?? content.length))) {
+            return 'method';
+        }
+    }
+    for (const container of findMemberContainers(content, className)) {
+        const body = content.slice(container.bodyStart, container.bodyEnd);
+        if (container.kind === 'class-expression' && hasClassMethod(body))
+            return 'method';
+        if (container.kind === 'object' && objectLiteralMemberNames(body).includes(member)) {
+            return 'method';
+        }
+        if (container.kind === 'namespace') {
+            const shape = declarationShape(body, member);
+            if (shape === 'function' || shape === 'const')
+                return shape;
+        }
+    }
+    return undefined;
+}
 function lineAt(content, index) {
     const start = content.lastIndexOf('\n', index - 1) + 1;
     const end = content.indexOf('\n', index);
@@ -298,7 +331,8 @@ function symbolNeedle(symbol) {
     const name = parts[parts.length - 1] ?? '';
     if (!name)
         return undefined;
-    const className = parts.length > 1 ? (parts[0] ?? null) : null;
+    // `Aggregate.method` (or `ns.Aggregate.method`): the segment before the member names the class.
+    const className = parts.length > 1 ? (parts[parts.length - 2] || null) : null;
     return { className, name };
 }
 function declaredLabel(invariant) {
@@ -344,9 +378,9 @@ function rankCoverage(invariant, files, scanTests = true) {
             const content = files.fileContents[file];
             if (!content)
                 continue;
-            if (needle.className && !content.includes(needle.className))
-                continue;
-            const shape = declarationShape(content, needle.name);
+            const shape = needle.className
+                ? classMemberShape(content, needle.className, needle.name)
+                : declarationShape(content, needle.name);
             if (!shape)
                 continue;
             declaration = { file, shape };
@@ -513,10 +547,14 @@ export function evaluateInvariantCoverage(input) {
         // Covered if the policy says this verdict counts.
         // When coverage declares neither test nor symbol, require at least description-only advisory presence = not covered.
         const requiresEvidence = inv.coverage?.test === true || Boolean(symbol) || inv.coverage === undefined;
+        // `coverage.test: false` without a symbol declares zero evidence. That opt-out is
+        // advisory-only: on an enforced invariant it is reported uncovered (never a false
+        // green), not refused at load, so the rest of the contract still evaluates.
+        const zeroEvidenceOptOut = inv.coverage?.test === false && !symbol;
         const covered = requiresEvidence && counts
             ? true
-            : inv.coverage?.test === false && !symbol
-                ? true // explicitly no coverage requirements
+            : zeroEvidenceOptOut && inv.mode !== 'enforced'
+                ? true // explicitly no coverage requirements (advisory-only opt-out)
                 : counts;
         // Partial only when tests are missing *and* no other evidence (e.g. symbol) completed coverage.
         const partial = testGlobsMissing && wantsTest && !counts;
@@ -562,11 +600,13 @@ export function evaluateInvariantCoverage(input) {
                     ? coverageBudgetExhausted
                         ? `Invariant ${inv.id} coverage cannot be proven (${budgetDetail}); reporting partial, not covered.`
                         : `Invariant ${inv.id} coverage cannot be proven (test globs missing or empty); reporting partial, not covered (never-had-tests).`
-                    : // The sentence is the verdict. It names a title, a declaration
-                        // shape, a bare mention, or silence — it does not re-scan.
-                        `Invariant ${inv.id}: ${describeCoverage(inv, ev)} (${kind === 'tests-disappeared'
-                            ? 'tests-disappeared — a suite exists'
-                            : 'never-had-tests — the scan found no tests at all'}). ArkGate matches declared text; it never executes tests.`) +
+                    : zeroEvidenceOptOut
+                        ? `Invariant ${inv.id} is enforced but declares no evidence (coverage.test is false and no coverage.symbol); set coverage.symbol, drop test:false, or keep mode "advisory".`
+                        : // The sentence is the verdict. It names a title, a declaration
+                            // shape, a bare mention, or silence — it does not re-scan.
+                            `Invariant ${inv.id}: ${describeCoverage(inv, ev)} (${kind === 'tests-disappeared'
+                                ? 'tests-disappeared — a suite exists'
+                                : 'never-had-tests — the scan found no tests at all'}). ArkGate matches declared text; it never executes tests.`) +
                     (partial && coverageBudgetExhausted ? budgetExhaustedTail : discardTail),
                 file: inv.provenance.sourceFile,
                 line: 1,
@@ -608,6 +648,14 @@ export function canPromoteInvariant(coverage) {
             reason: `Invariant ${coverage.invariantId} is uncovered; add a test title or symbol before promoting to enforced.`,
         };
     }
+    // A `coverage.test: false` opt-out without a symbol reports covered with no
+    // evidence at all. That is fine while advisory; it is not a basis for enforcing.
+    if (Array.isArray(coverage.evidence) && coverage.evidence.length === 0) {
+        return {
+            ok: false,
+            reason: `Invariant ${coverage.invariantId} declares no evidence (coverage.test:false and no symbol); add coverage.symbol or a test title before promoting to enforced.`,
+        };
+    }
     // Promotion is the moment coverage stops being advice, so an evidence file
     // the project itself says its runner does not walk cannot carry it.
     if (coverage.outsideDeclaredRoots === true) {

package/bin/lib/mcp-adoption.mjs

@@ -53,8 +53,14 @@ export const MCP_RUNNER_ARGV = new Set(['exec', '--config.verify-deps-before-run
 // The runner token immediately before an ark command in a text command string.
 // Matches npm/yarn runners and both pnpm forms (legacy `pnpm exec` + verify-deps-safe form).
 // Longer bin names first so `arkgate-check` is not partially matched as `ark`.
+// The pinned npx form (`npx -y -p arkgate@x`) comes first so it is replaced whole.
 export const RUNNER_BEFORE_ARK =
-  /\b(?:npx|pnpm --config\.verify-deps-before-run=false exec|pnpm exec|yarn)(?= (?:arkgate-check|arkgate-mcp|arkgate|ark-check|ark-mcp|ark)\b)/g;
+  /\b(?:npx -y -p arkgate@[^\s"'`]+|npx|pnpm --config\.verify-deps-before-run=false exec|pnpm exec|yarn)(?= (?:arkgate-check|arkgate-mcp|arkgate|ark-check|ark-mcp|ark)\b)/g;
+
+/** npx pinned-package argv (`-y`, `-p`, `arkgate@x`) — runner noise, not a server flag. */
+function isPinnedNpxArgv(entry) {
+  return /^(?:-y|--yes|-p|--package|--package=arkgate(?:@\S+)?|arkgate@\S+)$/.test(entry);
+}
 
 /** Keep only MCP server flags from existing args (drop runner tokens + any ark* bin names). */
 
@@ -66,6 +72,7 @@ export function stripMcpServerArgs(args) {
     (entry) =>
       typeof entry === 'string' &&
       !MCP_RUNNER_ARGV.has(entry) &&
+      !isPinnedNpxArgv(entry) &&
       !ARK_MCP_BINS.has(entry) &&
       !ARK_CHECK_BINS.has(entry) &&
       !ARK_CLI_BINS.has(entry)
@@ -89,6 +96,7 @@ export function stripOpencodeMcpCommand(command) {
     if (
       runners.has(base) ||
       MCP_RUNNER_ARGV.has(entry) ||
+      isPinnedNpxArgv(entry) ||
       ARK_MCP_BINS.has(base) ||
       ARK_MCP_BINS.has(entry) ||
       ARK_CHECK_BINS.has(base) ||