arkgate 4.1.1 → 4.2.1

package/bin/lib/resident-hook.mjs

@@ -67,20 +67,44 @@ function residentRuntimeIdentity(launcher) {
   return hash.digest('hex');
 }
 
+function realpathOrResolve(value) {
+  const resolved = path.resolve(value);
+  try { return fs.realpathSync(resolved); } catch { return resolved; }
+}
+
+export function residentInvocationIdentity({ root, config, manifest, tsconfig }) {
+  const lexicalRoot = path.resolve(root);
+  const realRoot = realpathOrResolve(lexicalRoot);
+  const projectPath = (value) => {
+    if (!value) return null;
+    const absolute = path.isAbsolute(value)
+      ? path.resolve(value)
+      : path.resolve(lexicalRoot, value);
+    const relative = path.relative(lexicalRoot, absolute);
+    const contained =
+      relative === '' ||
+      (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
+    return realpathOrResolve(contained ? path.resolve(realRoot, relative) : absolute);
+  };
+  return {
+    root: realRoot,
+    config: projectPath(config),
+    manifest: projectPath(manifest),
+    tsconfig: projectPath(tsconfig),
+  };
+}
+
 export function residentHookEndpoint({ root, config, manifest, tsconfig, launcher }) {
-  let realRoot;
-  try { realRoot = fs.realpathSync(root); } catch { realRoot = path.resolve(root); }
+  const invocation = residentInvocationIdentity({ root, config, manifest, tsconfig });
+  const realLauncher = realpathOrResolve(launcher);
   const uid = typeof process.getuid === 'function' ? process.getuid() : 'user';
   const directory = path.join(os.tmpdir(), `arkgate-${uid}`);
   const digest = createHash('sha256').update(JSON.stringify({
-    root: realRoot,
-    config: path.resolve(root, config),
-    manifest: manifest ? path.resolve(root, manifest) : null,
-    tsconfig: tsconfig ? path.resolve(root, tsconfig) : null,
-    launcher: path.resolve(launcher),
-    executable: process.execPath,
+    ...invocation,
+    launcher: realLauncher,
+    executable: realpathOrResolve(process.execPath),
     protocolVersion: RESIDENT_HOOK_PROTOCOL_VERSION,
-    runtimeIdentity: residentRuntimeIdentity(path.resolve(launcher)),
+    runtimeIdentity: residentRuntimeIdentity(realLauncher),
   })).digest('hex').slice(0, 24);
   return {
     directory,

package/bin/lib/rules-inventory.mjs

@@ -11,11 +11,63 @@
 function lineOf(content, index) {
     return content.slice(0, index).split('\n').length;
 }
+function normalizeInventoryPath(file) {
+    return file.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+function ownsIntent(intentPrefixes, intentRoots) {
+    return intentPrefixes.some((prefix) => {
+        const normalized = prefix.trim().replace(/\.+$/, '');
+        return intentRoots.some((root) => normalized === root || normalized.startsWith(`${root}.`));
+    });
+}
+function isDomainLayer(layer, intentPrefixes = []) {
+    return (/domain|entity|aggregate|model/i.test(layer) ||
+        ownsIntent(intentPrefixes, ['Domain']));
+}
+function isControllerEligibleLayer(layer, intentPrefixes = []) {
+    return (/application|orchestration|presentation|adapter|framework|interface|delivery|transport|inbound|controller/i.test(layer) ||
+        ownsIntent(intentPrefixes, [
+            'Application',
+            'Orchestration',
+            'Presentation',
+            'Adapter',
+            'Interface',
+            'Delivery',
+            'Transport',
+        ]));
+}
+function isNonPilotSurface(file) {
+    return (/(?:^|\/)(?:tests?|__tests__|fixtures?|testdata|mocks?|stubs?|examples?|samples?|seeds?|seeders?|migrations?|excluded|exclusions?)(?:\/|$)/i.test(file) ||
+        /(?:^|\/)[^/]*\.(?:test|spec|fixture|mock|stub|seed|seeder)\.[^/]+$/i.test(file) ||
+        /(?:^|\/)(?:seed|seeder|fixture|mock|stub)\.[^/]+$/i.test(file));
+}
 export function buildRulesInventory(input) {
     const candidates = [];
     let seq = 0;
+    const fileLayers = new Map(Object.entries(input.fileLayers ?? {}).map(([file, layer]) => [
+        normalizeInventoryPath(file),
+        layer,
+    ]));
+    const layerIntentPrefixes = new Map((input.layerContexts ?? []).map((layer) => [
+        layer.name,
+        layer.intentPrefixes ?? [],
+    ]));
+    const domainLayer = (input.layerContexts ?? []).find((layer) => isDomainLayer(layer.name, layer.intentPrefixes))?.name ?? 'DomainModel';
     for (const [file, content] of Object.entries(input.fileContents).sort(([a], [b]) => a.localeCompare(b))) {
-        const posix = file.replace(/\\/g, '/');
+        const posix = normalizeInventoryPath(file);
+        // Test data, fixtures, seeds, migrations, and explicit exclusions may retain
+        // representative smells, but are not production extraction pilots.
+        if (isNonPilotSurface(posix))
+            continue;
+        // Generated mirrors are evidence for their canonical source, not a second
+        // extraction candidate.
+        if (/GENERATED FILE\s+[—-]\s+do not edit by hand/i.test(content.slice(0, 320)))
+            continue;
+        const hasGovernedLayer = fileLayers.has(posix);
+        const governedLayer = fileLayers.get(posix);
+        const governedIntentPrefixes = governedLayer
+            ? layerIntentPrefixes.get(governedLayer) ?? []
+            : [];
         // P2-N — clear UI bags only (components/theme/styles). Do NOT blanket-skip all
         // app/pages (server actions / route handlers live there and stay inventoriable).
         const isUiChrome = /(?:^|\/)(?:components|ui|layouts|styles|hooks|theme|tokens|i18n|locales?)(?:\/|$)/i.test(posix) ||
@@ -23,14 +75,22 @@ export function buildRulesInventory(input) {
                 /(?:page|layout|loading|error|template|default)\.(?:tsx|jsx)$/i.test(posix);
         const isApiRoute = /(?:^|\/)(?:app|pages)(?:\/[^/]+)*\/api(?:\/|$)/i.test(posix);
         const isServerAction = /(?:^|\/)actions?(?:\/|\.|$)/i.test(posix) || /['"]use server['"]/.test(content);
-        const isController = /controller|handler|resolver/i.test(file) ||
+        const controllerShape = /controller|handler|resolver/i.test(file) ||
             isApiRoute ||
             isServerAction ||
             (/route\.(?:ts|js|tsx|jsx)$/i.test(posix) && !isUiChrome) ||
             /@(Controller|Get|Post|Put|Delete|Patch)\b/.test(content) ||
             /\bexport\s+(?:async\s+)?function\s+(?:GET|POST|PUT|DELETE|PATCH)\b/.test(content) ||
             /\bexport\s+const\s+(?:GET|POST|PUT|DELETE|PATCH)\s*=/.test(content);
-        const isDomain = /domain|entity|aggregate|model/i.test(file);
+        const isController = hasGovernedLayer
+            ? Boolean(governedLayer &&
+                isControllerEligibleLayer(governedLayer, governedIntentPrefixes) &&
+                controllerShape)
+            : controllerShape;
+        const isDomain = hasGovernedLayer
+            ? Boolean(governedLayer && isDomainLayer(governedLayer, governedIntentPrefixes))
+            : /domain|entity|aggregate|model/i.test(file);
+        const magicConstantEligible = !hasGovernedLayer || isDomain || isController;
         // validation-in-controller (API/Nest/server-action handlers — not pure UI chrome)
         if (isController && !isUiChrome) {
             const valRe = /\b(if\s*\([^)]{0,80}(amount|total|price|qty|quantity|balance)[^)]{0,40}\)|throw new (Error|BadRequest|ValidationError)|z\.object\(|yup\.|class-validator|@Is[A-Z])/g;
@@ -44,8 +104,9 @@ export function buildRulesInventory(input) {
                     line: lineOf(content, m.index),
                     message: 'Business validation appears in a controller/handler — extract an invariant or Domain rule.',
                     confidence: 'direct-evidence',
+                    governedLayer,
                     suggestedArkRule: {
-                        layer: 'DomainModel',
+                        layer: domainLayer,
                         invariantId: `INV-EXTRACT-${seq}`,
                         sensor: 'invariant-coverage',
                     },
@@ -67,9 +128,21 @@ export function buildRulesInventory(input) {
             // Narrow DEFAULT_/REQUEST_/STORAGE_ — only known infra tokens, not all DEFAULT_* seeds
             /^(?:DEFAULT_(?:BASE_URL|TIMEOUT(?:_MS)?|RETRY|PORT|HOST|HEADERS?|CACHE|TTL|MS|LOCALE|LANG|TIMEZONE|TZ)|REQUEST_(?:TIMEOUT(?:_MS)?|HEADERS?|RETRY|ID_PREFIX)|STORAGE_(?:KEY|PREFIX|BUCKET)|DAY_MS$|APP_DOMAIN$|BASE_URL$)$/i.test(name) ||
             // Known I/O bag prefixes that are never domain seeds in field clones
-            /^(?:FAVORITES_STORAGE|LISTINGS_CACHE|DOCS_PATH|METRICS_INTERVAL)/i.test(name);
+            /^(?:FAVORITES_STORAGE|LISTINGS_CACHE|DOCS_PATH|METRICS_INTERVAL)/i.test(name) ||
+            // Development identities and PostgreSQL type OIDs are technical wiring, not
+            // business literals. Keep this narrow so Domain limits/status seeds still surface.
+            /^(?:DEV|DEMO|SEED|FIXTURE)_[A-Z0-9_]+$/i.test(name) ||
+            /^(?:PG|POSTGRES|OID)_[A-Z0-9_]+$/i.test(name) ||
+            /_(?:OID|OIDS)$/i.test(name) ||
+            /^(?:INT2|INT4|INT8|FLOAT4|FLOAT8|NUMERIC|DATE|TIME|TIMESTAMP|TIMESTAMPTZ|JSON|JSONB|UUID)OID$/i.test(name) ||
+            /(?:^|_)(?:SCHEMA|PROTOCOL|RESOLVER|FORMAT)_(?:URL|URI|VERSION|ID|IDENTITY)$/i.test(name);
         while ((magic = magicRe.exec(content)) !== null) {
             const name = magic[2];
+            // With governed layer evidence, generic Tooling/Kernel constants are not
+            // business-rule candidates. Controller-shaped boundaries stay eligible
+            // because business policy can leak into them.
+            if (!magicConstantEligible)
+                continue;
             if (isInfraMagicName(name))
                 continue;
             // P2-N: skip remaining ALL_CAPS noise only on clear UI chrome (not all of app/).
@@ -88,7 +161,8 @@ export function buildRulesInventory(input) {
                 line: lineOf(content, magic.index),
                 message: `Magic business constant ${name} may belong in a Domain policy or invariant catalog.`,
                 confidence: 'heuristic',
-                suggestedArkRule: { layer: 'DomainModel', invariantId: `INV-${name}` },
+                governedLayer,
+                suggestedArkRule: { layer: domainLayer, invariantId: `INV-${name}` },
                 neverMechanicalSafe: true,
             });
         }
@@ -109,8 +183,9 @@ export function buildRulesInventory(input) {
                         line: lineOf(content, c.index),
                         message: `Class ${c[1]} looks anemic (data-heavy, few behaviors).`,
                         confidence: 'heuristic',
+                        governedLayer,
                         suggestedArkRule: {
-                            layer: 'DomainModel',
+                            layer: domainLayer,
                             structureId: 'no-anemic-model',
                             sensor: 'no-anemic-model',
                         },
@@ -131,6 +206,16 @@ export function buildRulesInventory(input) {
                 const mutRe = /this\.\w+\s*=/g;
                 let mut;
                 while ((mut = mutRe.exec(content)) !== null) {
+                    const classStart = content.lastIndexOf('class ', mut.index);
+                    const classHeaderEnd = classStart >= 0 ? content.indexOf('{', classStart) : -1;
+                    const classHeader = classStart >= 0 && classHeaderEnd >= classStart && classHeaderEnd < mut.index
+                        ? content.slice(classStart, classHeaderEnd)
+                        : '';
+                    // Error metadata assignment is constructor wiring, not aggregate
+                    // mutation. Keep the exclusion local to the containing class header.
+                    if (/\bextends\s+(?:Error|[A-Za-z_$][A-Za-z0-9_$]*Error)\b/.test(classHeader)) {
+                        continue;
+                    }
                     const window = content.slice(Math.max(0, mut.index - 200), mut.index + 200);
                     if (!/\b(ensureInvariants|assertInvariants|validate|publish|emit)\b/.test(window)) {
                         seq += 1;
@@ -141,8 +226,9 @@ export function buildRulesInventory(input) {
                             line: lineOf(content, mut.index),
                             message: 'Domain field mutation without nearby guard/publish call.',
                             confidence: 'heuristic',
+                            governedLayer,
                             suggestedArkRule: {
-                                layer: 'DomainModel',
+                                layer: domainLayer,
                                 structureId: 'events-on-mutation',
                                 sensor: 'domain-event-on-mutation',
                             },
@@ -155,6 +241,12 @@ export function buildRulesInventory(input) {
         }
     }
     const contracted = new Set(input.contractedRuleIds ?? []);
+    candidates.sort((a, b) => Number(b.confidence === 'direct-evidence') -
+        Number(a.confidence === 'direct-evidence') ||
+        a.file.localeCompare(b.file) ||
+        a.line - b.line ||
+        a.kind.localeCompare(b.kind) ||
+        a.id.localeCompare(b.id));
     const underContract = candidates.filter((c) => (c.suggestedArkRule?.invariantId && contracted.has(c.suggestedArkRule.invariantId)) ||
         (c.suggestedArkRule?.structureId && contracted.has(c.suggestedArkRule.structureId))).length;
     return {

package/bin/lib/skill-install.mjs

@@ -224,10 +224,12 @@ export function arkPackageVersion() {
 }
 
 // Insert `arkVersion: <v>` into a skill's YAML frontmatter (before its closing
-// `---`). No frontmatter → returned unchanged. Idempotent for a given version.
+// `---`). No frontmatter → returned unchanged. Idempotent for a given version
+// and preserves the checked-out line ending on Windows.
 export function stampSkill(content, version) {
   if (!version) return content;
-  const lines = content.split('\n');
+  const newline = content.includes('\r\n') ? '\r\n' : '\n';
+  const lines = content.split(/\r?\n/);
   if (lines[0] !== '---') return content;
   const closeIdx = lines.indexOf('---', 1);
   if (closeIdx === -1) return content;
@@ -239,7 +241,7 @@ export function stampSkill(content, version) {
   } else {
     lines.splice(closeIdx, 0, `arkVersion: ${version}`);
   }
-  return lines.join('\n');
+  return lines.join(newline);
 }
 
 // Read the `arkVersion:` stamp from an installed skill file. Returns null when
@@ -260,17 +262,61 @@ function skillVersionFromContent(content) {
   return match ? match[1].trim() : null;
 }
 
-// Numeric-tuple compare of dotted versions; true when `a` is strictly older than
-// `b`. Non-numeric/absent segments compare as 0, so "1.7" < "1.7.5".
+const VERSION_PATTERN =
+  /^(0|[1-9]\d*)(?:\.(0|[1-9]\d*))?(?:\.(0|[1-9]\d*))?(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+
+function parseVersion(value, strict) {
+  if (typeof value !== 'string') return null;
+  const match = value.match(VERSION_PATTERN);
+  if (!match || (strict && (match[2] === undefined || match[3] === undefined))) {
+    return null;
+  }
+  const prerelease = match[4]?.split('.') ?? [];
+  if (
+    prerelease.some(
+      (identifier) =>
+        /^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith('0')
+    )
+  ) {
+    return null;
+  }
+  return {
+    core: [match[1], match[2] ?? '0', match[3] ?? '0'],
+    prerelease,
+  };
+}
+
+/** True only for a complete SemVer 2.0.0 version. */
+export function isValidSemver(value) {
+  return parseVersion(value, true) !== null;
+}
+
+// SemVer precedence compare. A one- or two-component numeric core remains
+// accepted for legacy skill stamps, so "1.7" < "1.7.5"; shared catalog metadata
+// uses isValidSemver and therefore requires the complete x.y.z form.
 export function isVersionOlder(a, b) {
-  const parse = (v) => String(v).split('.').map((n) => Number.parseInt(n, 10) || 0);
-  const av = parse(a);
-  const bv = parse(b);
-  const len = Math.max(av.length, bv.length);
-  for (let i = 0; i < len; i += 1) {
-    const x = av[i] ?? 0;
-    const y = bv[i] ?? 0;
-    if (x !== y) return x < y;
+  const av = parseVersion(a, false);
+  const bv = parseVersion(b, false);
+  if (!av || !bv) return false;
+  for (let index = 0; index < 3; index += 1) {
+    const left = BigInt(av.core[index]);
+    const right = BigInt(bv.core[index]);
+    if (left !== right) return left < right;
+  }
+  if (av.prerelease.length === 0 || bv.prerelease.length === 0) {
+    return av.prerelease.length > 0 && bv.prerelease.length === 0;
+  }
+  const length = Math.max(av.prerelease.length, bv.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    const left = av.prerelease[index];
+    const right = bv.prerelease[index];
+    if (left === undefined || right === undefined) return left === undefined;
+    if (left === right) continue;
+    const leftNumeric = /^\d+$/.test(left);
+    const rightNumeric = /^\d+$/.test(right);
+    if (leftNumeric && rightNumeric) return BigInt(left) < BigInt(right);
+    if (leftNumeric !== rightNumeric) return leftNumeric;
+    return left < right;
   }
   return false;
 }
@@ -315,6 +361,74 @@ export function skillContentMatchesTemplate(installedContent, templateContent) {
   return installedId === skillContentIdentity(stampSkill(templateContent, '0.0.0'));
 }
 
+/**
+ * Decide whether one managed skill should be written.
+ *
+ * Repo catalogs belong to that repo's installed package, so an explicit --force
+ * may move them in either direction. Codex home is shared by every repo on the
+ * machine: a package older than the installed home stamp must never win, even
+ * under --force. In both scopes a version-stamp-only difference is a no-op; the
+ * skill body is the capability contract.
+ *
+ * @param {{
+ *   existingContent?: string|null,
+ *   targetContent: string,
+ *   packageVersion?: string|null,
+ *   force?: boolean,
+ *   scope?: 'repo'|'home',
+ * }} input
+ * @returns {{
+ *   action: 'write'|'skip',
+ *   reason: 'missing'|'content-current'|'newer-home-version'|'unknown-source-version'|'existing-preserved'|'content-update',
+ *   scope: 'repo'|'home',
+ *   sourceVersion: string|null,
+ *   installedVersion: string|null,
+ *   conflict: boolean,
+ *   downgradeBlocked: boolean,
+ * }}
+ */
+export function planSkillInstall(input) {
+  const scope = input.scope === 'home' ? 'home' : 'repo';
+  const existingContent = input.existingContent ?? null;
+  const targetContent = String(input.targetContent);
+  const sourceVersion =
+    input.packageVersion ?? skillVersionFromContent(targetContent);
+  const installedVersion = skillVersionFromContent(existingContent);
+  const result = (action, reason, conflict = false, downgradeBlocked = false) => ({
+    action,
+    reason,
+    scope,
+    sourceVersion,
+    installedVersion,
+    conflict,
+    downgradeBlocked,
+  });
+
+  if (existingContent === null) return result('write', 'missing');
+  if (
+    existingContent === targetContent ||
+    skillContentIdentity(existingContent) === skillContentIdentity(targetContent)
+  ) {
+    return result('skip', 'content-current');
+  }
+
+  if (scope === 'home') {
+    if (installedVersion && !sourceVersion) {
+      return result('skip', 'unknown-source-version', true, true);
+    }
+    if (
+      installedVersion &&
+      sourceVersion &&
+      isVersionOlder(sourceVersion, installedVersion)
+    ) {
+      return result('skip', 'newer-home-version', true, true);
+    }
+  }
+
+  if (!input.force) return result('skip', 'existing-preserved', true);
+  return result('write', 'content-update');
+}
+
 /** @returns {Record<string, string>} skill name → template body from package */
 export function skillTemplateBodies() {
   return Object.fromEntries(skillTemplates());
@@ -422,6 +536,96 @@ export function assessSkillCatalogParity(skillNames, skillFile, packageVersion,
   };
 }
 
+const CODEX_HOME_CATALOG = '.arkgate-catalog.json';
+const CODEX_HOME_PENDING_CATALOG = '.arkgate-catalog.pending.json';
+const CATALOG_TOKEN_PATTERN =
+  /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;
+
+function readCodexHomeCatalogMetadata(file, kind) {
+  try {
+    const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (!stat) return { exists: false, valid: false, version: null };
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) {
+      return { exists: true, valid: false, version: null };
+    }
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (kind === 'pending') {
+      const keys =
+        value && typeof value === 'object' && !Array.isArray(value)
+          ? Object.keys(value).sort()
+          : [];
+      const valid =
+        keys.join(',') === 'packageVersion,schemaVersion,token' &&
+        value.schemaVersion === '1.0' &&
+        isValidSemver(value.packageVersion) &&
+        typeof value.token === 'string' &&
+        CATALOG_TOKEN_PATTERN.test(value.token);
+      return {
+        exists: true,
+        valid,
+        version: valid ? value.packageVersion : null,
+      };
+    }
+    if (
+      value?.schemaVersion !== '1.0' ||
+      !isValidSemver(value.packageVersion) ||
+      !Array.isArray(value.skills)
+    ) {
+      return { exists: true, valid: false, version: null };
+    }
+    const seen = new Set();
+    for (const skill of value.skills) {
+      if (
+        !skill ||
+        typeof skill.name !== 'string' ||
+        !/^ark-[a-z0-9-]+$/.test(skill.name) ||
+        typeof skill.contentIdentity !== 'string' ||
+        !/^sha256:[a-f0-9]{64}$/.test(skill.contentIdentity) ||
+        seen.has(skill.name)
+      ) {
+        return { exists: true, valid: false, version: null };
+      }
+      seen.add(skill.name);
+    }
+    return { exists: true, valid: true, version: value.packageVersion };
+  } catch {
+    return { exists: true, valid: false, version: null };
+  }
+}
+
+function codexHomeCatalogState(skillsDir) {
+  const catalog = readCodexHomeCatalogMetadata(
+    path.join(skillsDir, CODEX_HOME_CATALOG),
+    'catalog'
+  );
+  const pending = readCodexHomeCatalogMetadata(
+    path.join(skillsDir, CODEX_HOME_PENDING_CATALOG),
+    'pending'
+  );
+  let floorVersion = catalog.version;
+  if (
+    pending.version &&
+    (!floorVersion || isVersionOlder(floorVersion, pending.version))
+  ) {
+    floorVersion = pending.version;
+  }
+  return {
+    floorVersion,
+    pendingVersion: pending.version,
+    hasMetadata: catalog.exists || pending.exists,
+    metadataInvalid:
+      (catalog.exists && !catalog.valid) || (pending.exists && !pending.valid),
+  };
+}
+
+function newerCodexHomeCatalogVersion(skillsDir, packageVersion, state = null) {
+  if (!isValidSemver(packageVersion)) return null;
+  const floorVersion = (state ?? codexHomeCatalogState(skillsDir)).floorVersion;
+  return floorVersion && isVersionOlder(packageVersion, floorVersion)
+    ? floorVersion
+    : null;
+}
+
 /**
  * Repo + home Codex skill parity against the shipping package skill set.
  * Producer trees (templates/skills) and projects without AGENTS.md return null.
@@ -459,6 +663,14 @@ export function assessCodexSkillParity(root) {
   const home = assessSkillCatalogParity(skillNames, homeSkill, packageVersion, {
     legacyFile: homeLegacy,
   });
+  const homeCatalogState = codexHomeCatalogState(skillsDir);
+  const newerHomeCatalog = newerCodexHomeCatalogVersion(
+    skillsDir,
+    packageVersion,
+    homeCatalogState
+  );
+  const pendingRecoveryRequired =
+    homeCatalogState.pendingVersion !== null && newerHomeCatalog === null;
 
   // Repo catalog matters when .codex is present (Codex host adopted) or repo skills/prompts exist.
   const repoInPlay =
@@ -467,14 +679,23 @@ export function assessCodexSkillParity(root) {
     repo.hasLegacyPrompts;
   // Home is "in play" only when ark skills or legacy prompts were actually installed there
   // (empty $CODEX_HOME/skills is optional multi-project — not debt).
-  const homeInPlay = home.presentCount > 0 || home.hasLegacyPrompts;
+  const homeInPlay =
+    home.presentCount > 0 ||
+    home.hasLegacyPrompts ||
+    homeCatalogState.hasMetadata;
 
   if (!repoInPlay && !homeInPlay) return null;
 
   const repoNeedsAttention =
     repoInPlay && (repo.missing > 0 || repo.stale > 0 || repo.legacyPromptsOnly);
   const homeNeedsAttention =
-    homeInPlay && (home.missing > 0 || home.stale > 0 || home.legacyPromptsOnly);
+    newerHomeCatalog === null &&
+    homeInPlay &&
+    (home.missing > 0 ||
+      home.stale > 0 ||
+      home.legacyPromptsOnly ||
+      pendingRecoveryRequired ||
+      homeCatalogState.metadataInvalid);
 
   return {
     packageVersion,
@@ -485,6 +706,11 @@ export function assessCodexSkillParity(root) {
       inPlay: homeInPlay,
       skillsDir,
       promptsDir,
+      catalogVersion: homeCatalogState.floorVersion,
+      catalogNewerThanPackage: newerHomeCatalog !== null,
+      pendingCatalogVersion: homeCatalogState.pendingVersion,
+      pendingRecoveryRequired,
+      catalogMetadataInvalid: homeCatalogState.metadataInvalid,
     },
     skillsDir,
     promptsDir,
@@ -515,6 +741,14 @@ export function detectCodexHomeGap(root) {
     expectedCount,
     packageVersion,
     skillsDir,
+    catalogVersion: home.catalogVersion,
+    pendingRecoveryRequired: Boolean(home.pendingRecoveryRequired),
+    catalogMetadataInvalid: Boolean(home.catalogMetadataInvalid),
+    catalogStateReason: home.catalogMetadataInvalid
+      ? 'invalid catalog metadata'
+      : home.pendingRecoveryRequired
+        ? 'interrupted catalog commit'
+        : null,
   };
 }
 
@@ -670,20 +904,32 @@ export function detectSkillGaps(root) {
   return gaps;
 }
 
+/**
+ * Preserve the full detected inventory for JSON/reporting, but keep immediate
+ * human remediation scoped to the host running this process.
+ */
+export function skillGapsForActiveHost(skillGaps, env = process.env) {
+  const activeHost = detectActiveAgentHost(env);
+  if (!activeHost) return skillGaps ?? [];
+  return (skillGaps ?? []).filter((gap) => gap.tool === activeHost);
+}
+
 /**
  * Human-facing skill / Codex catalog gap lines for ark-check (non-JSON).
  * @param {string} root
- * @param {{ skillGaps: object[], codexHomeGap: object|null, codexRepoSkillGap: object|null, codexSessionActive: boolean, color: { dim: Function, yellow: Function } }} opts
+ * @param {{ skillGaps: object[], codexHomeGap: object|null, codexRepoSkillGap: object|null, codexSessionActive: boolean, env?: NodeJS.ProcessEnv, color: { dim: Function, yellow: Function } }} opts
  */
 export function printSkillAndCodexGapHints(root, opts) {
   const { skillGaps, codexHomeGap, codexRepoSkillGap, codexSessionActive, color } = opts;
-  if (skillGaps?.length > 0) {
-    const legacyCodex = skillGaps.some((gap) => gap.tool === 'codex' && gap.legacyPromptsOnly);
-    const legacyAdvisory = skillGaps.some(
+  const activeSkillGaps = skillGapsForActiveHost(skillGaps, opts.env);
+  if (activeSkillGaps.length > 0) {
+    const legacyCodex = activeSkillGaps.some(
+      (gap) => gap.tool === 'codex' && gap.legacyPromptsOnly
+    );
+    const legacyAdvisory = activeSkillGaps.some(
       (gap) => gap.tool === 'codex' && gap.legacyAdvisory && gap.catalogComplete
     );
-    // Report Codex legacy separately; never suppress missing/stale for other hosts.
-    const remaining = skillGaps.filter(
+    const remaining = activeSkillGaps.filter(
       (gap) =>
         !(gap.tool === 'codex' && (gap.legacyPromptsOnly || gap.legacyAdvisory))
     );
@@ -727,6 +973,8 @@ export function printSkillAndCodexGapHints(root, opts) {
     if (codexHomeGap.legacyPromptsOnly) parts.push('legacy-prompts-only');
     if (codexHomeGap.missing > 0) parts.push(`${codexHomeGap.missing} missing`);
     if (codexHomeGap.stale > 0) parts.push(`${codexHomeGap.stale} content-behind-package`);
+    if (codexHomeGap.pendingRecoveryRequired) parts.push('interrupted catalog commit');
+    if (codexHomeGap.catalogMetadataInvalid) parts.push('invalid catalog metadata');
     const deferred = !codexSessionActive;
     const deferredNote = deferred
       ? ' Deferred unless you use Codex — not a blocker for Grok/Claude/Cursor. '
@@ -735,7 +983,9 @@ export function printSkillAndCodexGapHints(root, opts) {
       `Codex home skill catalog (${codexSkillsDir()}) behind this Ark (${parts.join(', ')}).` +
       deferredNote +
       `Catalog is $CODEX_HOME/skills/<name>/SKILL.md (not flat prompts). ` +
-      `When using Codex: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --codex-home --force')}`;
+      (codexHomeGap.catalogMetadataInvalid
+        ? 'Inspect the shared catalog metadata before retrying; invalid metadata fails safe.'
+        : `When using Codex: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --codex-home --force')}`);
     console.log(deferred ? color.dim(msg) : color.yellow(msg));
   }
   if (codexRepoSkillGap && codexSessionActive) {