arkgate 4.1.1 → 4.2.1

package/bin/lib/github-enforcement.mjs

@@ -51,7 +51,14 @@ function shellSegments(text) {
       index++;
       continue;
     }
-    if (char === ';' || char === '|' || char === '\n') {
+    if (
+      char === '&' &&
+      (input[index - 1] === '>' || input[index - 1] === '<' || input[index + 1] === '>')
+    ) {
+      current += char;
+      continue;
+    }
+    if (char === ';' || char === '|' || char === '&' || char === '\n') {
       push(char);
       continue;
     }
@@ -70,12 +77,18 @@ function analyzeCommands(commands, script = '') {
     .filter((segment) => DIRECT_ARK.test(executableText(segment.text)))
     .map((segment) => ({
       text: segment.text,
-      enforcing: segment.terminator !== '||' && segment.terminator !== '|',
+      enforcing:
+        segment.terminator !== '||' &&
+        segment.terminator !== '|' &&
+        segment.terminator !== '&',
     }));
   const found = [];
   for (const segment of shellSegments(commands)) {
     const executable = executableText(segment.text);
-    const outerEnforcing = segment.terminator !== '||' && segment.terminator !== '|';
+    const outerEnforcing =
+      segment.terminator !== '||' &&
+      segment.terminator !== '|' &&
+      segment.terminator !== '&';
     if (DIRECT_ARK.test(executable)) {
       found.push({ text: segment.text, enforcing: outerEnforcing });
     } else if (CHECK_SCRIPT.test(executable)) {

package/bin/lib/hook-templates.mjs

@@ -1,19 +1,20 @@
 // Generated from hook-templates.source.mjs — run npm run generate:packaged-tooling.
-import{execCommandParts as i,execRunner as s}from"../ark-shared.mjs";const c="arkgate-mcp";function l(e){const r=s(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",command:`${r} ${c} --session-context --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit",hooks:[{type:"command",command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`}]}]}},null,2)}
-`}function p(e){const r=s(e),o="${CODEX_PROJECT_DIR:-${PWD:-.}}";return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${c} --session-context --root "${o}" --config ark.config.json`}]}],PreToolUse:[{matcher:"ApplyPatch|apply_patch|Write|Edit|MultiEdit",hooks:[{type:"command",timeout:30,command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root "${o}" --config ark.config.json`}]}]}},null,2)}
-`}function g(e){const{command:r,args:o}=i(e,c,["--root",".","--config","ark.config.json"]),t=a=>a.replace(/\\/g,"\\\\").replace(/"/g,'\\"'),n=o.map(a=>`"${t(a)}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Codex project scope).
-# Restart Codex after changes; MCP servers are loaded when the project session starts.
+import{execCommandParts as i,execRunner as s}from"../ark-shared.mjs";const c="arkgate-mcp";function l(o){const r=s(o);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",command:`${r} ${c} --session-context --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit",hooks:[{type:"command",command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function p(o){const r=s(o);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${c} --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} ${c} --hook --hook-repair --fail-on-new-smells --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function f(o){const{command:r,args:e}=i(o,c,["--root",".","--config","ark.config.json"]),t=a=>a.replace(/\\/g,"\\\\").replace(/"/g,'\\"'),n=e.map(a=>`"${t(a)}"`).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 = [${n}]
-`}function f(e){const{command:r,args:o}=i(e,c,["--root",".","--config","ark.config.json"]),t=o.map(n=>`"${n.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Grok Build project scope).
+`}function g(o){const{command:r,args:e}=i(o,c,["--root",".","--config","ark.config.json"]),t=e.map(n=>`"${n.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 u(e){const r=s(e),o="${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}";return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${c} --session-context --root "${o}" --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit|write|search_replace",hooks:[{type:"command",timeout:30,command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root "${o}" --config ark.config.json`}]}]}},null,2)}
-`}function k(e){const r=s(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} ${c} --hook --hook-repair --fail-on-new-smells --root "\${PWD:-.}" --config ark.config.json`}]}]}},null,2)}
-`}function d(e){const{command:r,args:o}=i(e,c,["--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,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 n=t["ark-write-gate"];if(!n||typeof n!="object")return null;const a={...o,"ark-write-gate":n};return`${JSON.stringify(a,null,2)}
-`}function h(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 n={...o};!n.$schema&&t.$schema&&(n.$schema=t.$schema);const a=o.mcp&&typeof o.mcp=="object"&&!Array.isArray(o.mcp)?{...o.mcp}:{};return a.ark=t.mcp.ark,n.mcp=a,`${JSON.stringify(n,null,2)}
-`}export{c as PREFERRED_MCP_BIN,k as antigravityHooks,l as claudeSettings,p as codexHooks,g as codexProjectConfig,u as grokHooks,f as grokProjectConfig,$ as mergeAntigravityArkHook,h as mergeOpencodeArkMcp,d as opencodeProjectConfig};
+`}function u(o){const r=s(o);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${c} --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} ${c} --hook --hook-repair --fail-on-new-smells --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function k(o){const r=s(o);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} ${c} --hook --hook-repair --fail-on-new-smells --root . --config ark.config.json`}]}]}},null,2)}
+`}function d(o){const{command:r,args:e}=i(o,c,["--root",".","--config","ark.config.json"]);return`${JSON.stringify({$schema:"https://opencode.ai/config.json",mcp:{ark:{type:"local",command:[r,...e],enabled:!0}}},null,2)}
+`}function h(o,r){let e,t;try{e=o&&o.trim()?JSON.parse(o):{},t=JSON.parse(r)}catch{return null}if(!e||typeof e!="object"||Array.isArray(e)||!t||typeof t!="object"||Array.isArray(t))return null;const n=t["ark-write-gate"];if(!n||typeof n!="object")return null;const a={...e,"ark-write-gate":n};return`${JSON.stringify(a,null,2)}
+`}function y(o,r){let e,t;try{e=o&&o.trim()?JSON.parse(o):{},t=JSON.parse(r)}catch{return null}if(!e||typeof e!="object"||Array.isArray(e))return null;const n={...e};!n.$schema&&t.$schema&&(n.$schema=t.$schema);const a=e.mcp&&typeof e.mcp=="object"&&!Array.isArray(e.mcp)?{...e.mcp}:{};return a.ark=t.mcp.ark,n.mcp=a,`${JSON.stringify(n,null,2)}
+`}export{c as PREFERRED_MCP_BIN,k as antigravityHooks,l as claudeSettings,p as codexHooks,f as codexProjectConfig,u as grokHooks,g as grokProjectConfig,h as mergeAntigravityArkHook,y as mergeOpencodeArkMcp,d as opencodeProjectConfig};

package/bin/lib/html-report-evolution.mjs

@@ -0,0 +1,114 @@
+export function renderEvolutionSection({
+  originSnapshot,
+  currentSnapshot,
+  originJustCreated,
+  esc,
+  formatDelta,
+  historyMax,
+}) {
+  if (!currentSnapshot) return '';
+  if (originJustCreated || !originSnapshot) {
+    return `<div class="section card evolve">
+        <h2>Origin baseline captured</h2>
+        <p class="dim" style="margin:.2rem 0 0;font-size:.9rem">
+          This is the <b>first</b> architecture snapshot for this project
+          (<code>.ark/reports/origin.json</code> + <code>origin.html</code>).
+          Future reports will show deltas against this starting point so you can prove evolution.
+        </p>
+      </div>`;
+  }
+  const scoreComparable =
+    typeof originSnapshot.arkVersion === 'string' &&
+    originSnapshot.arkVersion.length > 0 &&
+    originSnapshot.arkVersion === currentSnapshot.arkVersion;
+  const rows = [
+    ['Ark score', originSnapshot.score, currentSnapshot.score, '', scoreComparable],
+    ['Governed %', originSnapshot.governedPercent, currentSnapshot.governedPercent, 'pp', true],
+    ['Files in scope', originSnapshot.totalFiles, currentSnapshot.totalFiles, '', true],
+    ['Classified files', originSnapshot.classifiedFiles, currentSnapshot.classifiedFiles, '', true],
+    ['Active violations', originSnapshot.activeViolations, currentSnapshot.activeViolations, '', true],
+    ['Value violations', originSnapshot.valueViolations, currentSnapshot.valueViolations, '', true],
+    ['Type-only violations', originSnapshot.typeOnlyViolations, currentSnapshot.typeOnlyViolations, '', true],
+    ['Layers', originSnapshot.layerCount, currentSnapshot.layerCount, '', true],
+    ['Deny rules', originSnapshot.denyRules, currentSnapshot.denyRules, '', true],
+    ['Gates configured', originSnapshot.gatesOn, currentSnapshot.gatesOn, '', true],
+  ];
+  const originDate = (originSnapshot.generatedAt || '').slice(0, 10) || 'origin';
+  const nowDate = (currentSnapshot.generatedAt || '').slice(0, 10) || 'now';
+  const tr = rows
+    .map(([label, from, to, unit, comparable]) => {
+      const d =
+        comparable && typeof from === 'number' && typeof to === 'number'
+          ? to - from
+          : null;
+      const good =
+        label.includes('violation') || label.includes('Violation')
+          ? d != null && d <= 0
+          : label.includes('Governed') ||
+              label.includes('score') ||
+              label.includes('Classified') ||
+              label.includes('Gates')
+            ? d != null && d >= 0
+            : null;
+      const cls =
+        d == null || d === 0 ? 'flat' : good === true ? 'up' : good === false ? 'down' : 'flat';
+      const delta =
+        d == null
+          ? '—'
+          : unit === 'pp'
+            ? formatDelta(Math.round(d * 10) / 10, { suffix: ' pp' })
+            : formatDelta(d);
+      return `<tr>
+          <td>${esc(label)}</td>
+          <td class="num">${from ?? '—'}</td>
+          <td class="num">${to ?? '—'}</td>
+          <td class="num delta ${cls}">${esc(delta)}</td>
+        </tr>`;
+    })
+    .join('\n');
+  const originLayers = originSnapshot.layerFiles || {};
+  const currentLayers = currentSnapshot.layerFiles || {};
+  const layerKeys = [
+    ...new Set([...Object.keys(originLayers), ...Object.keys(currentLayers)]),
+  ].sort();
+  const layerTr = layerKeys
+    .map((name) => {
+      const from = originLayers[name] || 0;
+      const to = currentLayers[name] || 0;
+      const d = to - from;
+      const cls = d === 0 ? 'flat' : d > 0 ? 'up' : 'down';
+      return `<tr>
+          <td class="ln">${esc(name)}</td>
+          <td class="num">${from}</td>
+          <td class="num">${to}</td>
+          <td class="num delta ${cls}">${esc(formatDelta(d))}</td>
+        </tr>`;
+    })
+    .join('\n');
+  const scoreNote = scoreComparable
+    ? ''
+    : `<p class="dim" style="margin:-.35rem 0 .75rem;font-size:.88rem">
+        Ark score is not comparable across Ark versions
+        (<code>${esc(originSnapshot.arkVersion ?? 'unknown')}</code> →
+        <code>${esc(currentSnapshot.arkVersion ?? 'unknown')}</code>); its Δ is shown as —.
+        Raw coverage, files, violations, layers, rules, and gate metrics remain visible.
+      </p>`;
+  return `<div class="section card evolve">
+      <h2>Evolution vs origin</h2>
+      <p class="dim" style="margin:.15rem 0 .75rem;font-size:.88rem">
+        Origin snapshot <code>${esc(originDate)}</code> → this report <code>${esc(nowDate)}</code>
+        · frozen at <code>.ark/reports/origin.*</code> · reopen origin HTML anytime for the starting picture.
+      </p>
+      ${scoreNote}
+      <table class="layers">
+        <tr><th>Metric</th><th>Origin</th><th>Now</th><th>Δ</th></tr>
+        ${tr}
+      </table>
+      <h3>Files per layer</h3>
+      <table class="layers">
+        <tr><th>Layer</th><th>Origin</th><th>Now</th><th>Δ</th></tr>
+        ${layerTr || '<tr><td colspan="4" class="dim">No layer file data in snapshots.</td></tr>'}
+      </table>
+      <p class="legend">Green Δ = improvement for that metric (↑ coverage/score/gates, ↓ violations). Score Δ is comparable only within the same Ark version. History JSON under <code>.ark/reports/history/</code> (last ${historyMax}).</p>
+    </div>`;
+}

package/bin/lib/html-report.mjs

@@ -21,7 +21,9 @@ import {
 } from './html-report-depth.mjs';
 import { FIX_HINTS } from './violations.mjs';
 import { capabilityBadgesFor, renderAdvisorySections } from './html-report-advisories.mjs';
+import { renderEvolutionSection } from './html-report-evolution.mjs';
 import { arkGitignoreAppendDecision } from './ark-gitignore.mjs';
+import { captureGitSnapshot } from './report-snapshot-context.mjs';
 
 export { arkGitignoreAppendDecision, gitignoreCoversArkState, gitignoreHasArkNegationException } from './ark-gitignore.mjs';
 
@@ -161,6 +163,7 @@ export function buildReportSnapshot({
         return path.basename(root);
       }
     })(),
+    git: captureGitSnapshot(root),
     ok: Boolean(ok),
     mode: mode ?? null,
     score: score ?? null,
@@ -1228,95 +1231,14 @@ export function renderHtmlReport({
     <div class="gates">${enforcementRows}</div>
   </div>
 
-  ${(() => {
-    if (!currentSnapshot) return '';
-    // First report: originSnapshot is null at render time (written to disk just after).
-    if (originJustCreated || !originSnapshot) {
-      return `<div class="section card evolve">
-        <h2>Origin baseline captured</h2>
-        <p class="dim" style="margin:.2rem 0 0;font-size:.9rem">
-          This is the <b>first</b> architecture snapshot for this project
-          (<code>.ark/reports/origin.json</code> + <code>origin.html</code>).
-          Future reports will show deltas against this starting point so you can prove evolution.
-        </p>
-      </div>`;
-    }
-    const rows = [
-      ['Ark score', originSnapshot.score, currentSnapshot.score, ''],
-      ['Governed %', originSnapshot.governedPercent, currentSnapshot.governedPercent, 'pp'],
-      ['Files in scope', originSnapshot.totalFiles, currentSnapshot.totalFiles, ''],
-      ['Classified files', originSnapshot.classifiedFiles, currentSnapshot.classifiedFiles, ''],
-      ['Active violations', originSnapshot.activeViolations, currentSnapshot.activeViolations, ''],
-      ['Value violations', originSnapshot.valueViolations, currentSnapshot.valueViolations, ''],
-      ['Type-only violations', originSnapshot.typeOnlyViolations, currentSnapshot.typeOnlyViolations, ''],
-      ['Layers', originSnapshot.layerCount, currentSnapshot.layerCount, ''],
-      ['Deny rules', originSnapshot.denyRules, currentSnapshot.denyRules, ''],
-      ['Gates configured', originSnapshot.gatesOn, currentSnapshot.gatesOn, ''],
-    ];
-    const originDate = (originSnapshot.generatedAt || '').slice(0, 10) || 'origin';
-    const nowDate = (currentSnapshot.generatedAt || '').slice(0, 10) || 'now';
-    const tr = rows
-      .map(([label, from, to, unit]) => {
-        const d =
-          typeof from === 'number' && typeof to === 'number' ? to - from : null;
-        const good =
-          label.includes('violation') || label.includes('Violation')
-            ? d != null && d <= 0
-            : label.includes('Governed') || label.includes('score') || label.includes('Classified') || label.includes('Gates')
-              ? d != null && d >= 0
-              : null;
-        const cls =
-          d == null || d === 0 ? 'flat' : good === true ? 'up' : good === false ? 'down' : 'flat';
-        const delta =
-          d == null
-            ? '—'
-            : unit === 'pp'
-              ? formatDelta(Math.round(d * 10) / 10, { suffix: ' pp' })
-              : formatDelta(d);
-        return `<tr>
-          <td>${esc(label)}</td>
-          <td class="num">${from ?? '—'}</td>
-          <td class="num">${to ?? '—'}</td>
-          <td class="num delta ${cls}">${esc(delta)}</td>
-        </tr>`;
-      })
-      .join('\n');
-    // Layer file deltas
-    const originLayers = originSnapshot.layerFiles || {};
-    const currentLayers = currentSnapshot.layerFiles || {};
-    const layerKeys = [...new Set([...Object.keys(originLayers), ...Object.keys(currentLayers)])].sort();
-    const layerTr = layerKeys
-      .map((name) => {
-        const from = originLayers[name] || 0;
-        const to = currentLayers[name] || 0;
-        const d = to - from;
-        const cls = d === 0 ? 'flat' : d > 0 ? 'up' : 'down';
-        return `<tr>
-          <td class="ln">${esc(name)}</td>
-          <td class="num">${from}</td>
-          <td class="num">${to}</td>
-          <td class="num delta ${cls}">${esc(formatDelta(d))}</td>
-        </tr>`;
-      })
-      .join('\n');
-    return `<div class="section card evolve">
-      <h2>Evolution vs origin</h2>
-      <p class="dim" style="margin:.15rem 0 .75rem;font-size:.88rem">
-        Origin snapshot <code>${esc(originDate)}</code> → this report <code>${esc(nowDate)}</code>
-        · frozen at <code>.ark/reports/origin.*</code> · reopen origin HTML anytime for the starting picture.
-      </p>
-      <table class="layers">
-        <tr><th>Metric</th><th>Origin</th><th>Now</th><th>Δ</th></tr>
-        ${tr}
-      </table>
-      <h3>Files per layer</h3>
-      <table class="layers">
-        <tr><th>Layer</th><th>Origin</th><th>Now</th><th>Δ</th></tr>
-        ${layerTr || '<tr><td colspan="4" class="dim">No layer file data in snapshots.</td></tr>'}
-      </table>
-      <p class="legend">Green Δ = improvement for that metric (↑ coverage/score/gates, ↓ violations). History JSON under <code>.ark/reports/history/</code> (last ${ARK_REPORT_HISTORY_MAX}).</p>
-    </div>`;
-  })()}
+  ${renderEvolutionSection({
+    originSnapshot,
+    currentSnapshot,
+    originJustCreated,
+    esc,
+    formatDelta,
+    historyMax: ARK_REPORT_HISTORY_MAX,
+  })}
 
   <div class="section card senior">
     <h2>Senior diagnostics</h2>

package/bin/lib/import-resolve.mjs

@@ -35,32 +35,55 @@ export function readTsconfigAliases(ts, root) {
   }
 }
 
+function canonicalPathWithMissingTail(value) {
+  const resolved = path.resolve(value);
+  let current = resolved;
+  const tail = [];
+  while (true) {
+    try {
+      return path.join(fs.realpathSync(current), ...tail.reverse());
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return resolved;
+      tail.push(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
 /**
  * Resolve an import specifier to a repo-relative path.
  * Relative + tsconfig-aliased only; bare packages → undefined.
  */
 export function resolveSpecifierToRel(specifier, fromFilePath, root, tsAliases) {
+  const canonicalRoot = canonicalPathWithMissingTail(root);
   let abs;
   if (specifier.startsWith('./') || specifier.startsWith('../')) {
     if (!fromFilePath) return undefined;
-    const fromAbs = path.isAbsolute(fromFilePath)
-      ? fromFilePath
-      : path.resolve(root, fromFilePath);
-    abs = path.resolve(path.dirname(fromAbs), specifier);
+    const fromAbs = canonicalPathWithMissingTail(
+      path.isAbsolute(fromFilePath) ? fromFilePath : path.resolve(root, fromFilePath)
+    );
+    abs = canonicalPathWithMissingTail(path.resolve(path.dirname(fromAbs), specifier));
   } else {
     const alias = tsAliases.aliases.find((a) => specifier.startsWith(a.from));
     if (!alias) return undefined;
-    abs = path.resolve(tsAliases.baseUrl, `${alias.to}${specifier.slice(alias.from.length)}`);
+    abs = canonicalPathWithMissingTail(
+      path.resolve(tsAliases.baseUrl, `${alias.to}${specifier.slice(alias.from.length)}`)
+    );
   }
-  const rel = path.relative(root, abs).split(path.sep).join('/');
-  return rel.startsWith('..') ? undefined : rel;
+  const relative = path.relative(canonicalRoot, abs);
+  if (path.isAbsolute(relative) || relative.startsWith('..')) return undefined;
+  return relative.split(path.sep).join('/');
 }
 
 function filePathToRel(filePath, root) {
   if (!filePath || typeof filePath !== 'string') return undefined;
-  const abs = path.isAbsolute(filePath) ? filePath : path.resolve(root, filePath);
-  const rel = path.relative(root, abs).split(path.sep).join('/');
-  return rel.startsWith('..') ? undefined : rel;
+  const abs = canonicalPathWithMissingTail(
+    path.isAbsolute(filePath) ? filePath : path.resolve(root, filePath)
+  );
+  const relative = path.relative(canonicalPathWithMissingTail(root), abs);
+  if (path.isAbsolute(relative) || relative.startsWith('..')) return undefined;
+  return relative.split(path.sep).join('/');
 }
 
 function classifyProbe(root, rel, layers) {
@@ -130,4 +153,3 @@ export function createImportTargetResolver(ts, root, config) {
     return undefined;
   };
 }
-

package/bin/lib/install-activation.mjs

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { arkCommand } from '../ark-shared.mjs';
+import { codexProjectMcpIsValid } from './codex-home.mjs';
+import { codexRuntimeActivation } from './enforcement-state.mjs';
+
+export function inspectCodexInstallActivation(root, enabled) {
+  let configuredOnDisk = false;
+  if (enabled) {
+    try {
+      configuredOnDisk = codexProjectMcpIsValid(
+        fs.readFileSync(path.join(root, '.codex', 'config.toml'), 'utf8'),
+        root
+      );
+    } catch {
+      // Missing/unreadable configuration remains explicitly unverified.
+    }
+  }
+  return {
+    codexProjectConfigured: configuredOnDisk,
+    runtimeActivation: codexRuntimeActivation({
+      configuredOnDisk,
+      restartRequired: configuredOnDisk,
+    }),
+  };
+}
+
+export function reportPartialInstall({
+  root,
+  tools,
+  results,
+  homeResults,
+  earlyWritten,
+  codexMcp,
+  runtimeActivation,
+}) {
+  const failed = [...results, ...homeResults]
+    .filter((result) => result.status === 'failed')
+    .map((result) => ({
+      target: result.relativePath ?? '(unknown template)',
+      reason: 'write failed',
+    }));
+  if (codexMcp?.status === 'failed') {
+    failed.push({
+      target: codexMcp.file,
+      reason: codexMcp.message ?? 'Codex MCP registration failed',
+    });
+  }
+  if (failed.length === 0) return false;
+
+  const written = new Set([
+    ...earlyWritten,
+    ...[...results, ...homeResults]
+      .filter((result) => result.status === 'written' || result.status === 'merged')
+      .map((result) => result.relativePath),
+  ]);
+  console.error('\nINSTALL PARTIAL — some artifacts were written; activation is not complete.');
+  console.error('Written:');
+  if (written.size === 0) console.error('  - (none)');
+  for (const relativePath of written) console.error(`  - ${relativePath}`);
+  console.error('Failed:');
+  for (const failure of failed) console.error(`  - ${failure.target}: ${failure.reason}`);
+  console.error('Recovery:');
+  console.error(
+    `  - Fix the listed path or permission error, then re-run ${arkCommand(root, 'ark-check', `--install-agent-gates${tools.size > 0 ? ` --tools ${[...tools].join(',')}` : ''}`)}.`
+  );
+  console.error('  - Existing customized files were preserved; no destructive rollback was attempted.');
+  if (tools.has('codex')) {
+    console.error(`  - Runtime activation: ${JSON.stringify(runtimeActivation)}`);
+  }
+  return true;
+}
+
+export function printCodexActivationHandoff(root, configuredOnDisk, runtimeActivation) {
+  console.log(
+    configuredOnDisk
+      ? '  CODEX MCP CONFIGURED — RUNTIME NOT VERIFIED'
+      : '  CODEX MCP CONFIGURATION UNRESOLVED — RUNTIME NOT VERIFIED'
+  );
+  console.log(`  Runtime activation: ${JSON.stringify(runtimeActivation)}`);
+  console.log(
+    configuredOnDisk
+      ? `  Restart Codex, then call ark_identity with expectedRoot "${path.resolve(root)}".`
+      : '  Repair `.codex/config.toml`, then restart Codex and call ark_identity.'
+  );
+  console.log('  Do not trust MCP verdicts before the project identity matches.');
+}