arkgate 3.8.1 → 3.8.3

package/bin/lib/managed-upgrade.mjs

@@ -6,8 +6,10 @@ import { codexPrimaryTable, upsertCodexMcpTable } from './codex-home.mjs';
 import { buildManagedAssetCatalog } from './install-migrate.mjs';
 import {
   KNOWN_TOOLS,
+  arkPackageVersion,
   detectActiveAgentHost,
   normalizeToolsList,
+  skillContentIdentity,
 } from './skill-install.mjs';
 
 export const MANAGED_MANIFEST_PATH = 'ark.managed.json';
@@ -36,21 +38,17 @@ function hash(content) {
   return `sha256:${createHash('sha256').update(content).digest('hex')}`;
 }
 
-function normalizedIdentityContent(content, kind) {
-  let text = String(content).replace(/\r\n/g, '\n');
-  if (kind !== 'skill') return text;
-  const lines = text.split('\n');
-  if (lines[0] !== '---') return text;
-  const end = lines.indexOf('---', 1);
-  if (end < 0) return text;
-  for (let index = 1; index < end; index += 1) {
-    if (/^arkVersion:/.test(lines[index])) lines[index] = 'arkVersion:<managed>';
-  }
-  return lines.join('\n');
+function normalizedIdentityContent(content) {
+  return String(content).replace(/\r\n/g, '\n');
 }
 
+/**
+ * Content identity for managed assets. Skill kind delegates to skill-install so
+ * doctor stale detection and upgrade classify never drift (single hasher).
+ */
 export function managedContentIdentity(content, kind = 'gate') {
-  return hash(Buffer.from(normalizedIdentityContent(content, kind)));
+  if (kind === 'skill') return skillContentIdentity(content);
+  return hash(Buffer.from(normalizedIdentityContent(content)));
 }
 
 function isSafeRelativePath(relativePath) {
@@ -271,12 +269,22 @@ function serializeManifest(value) {
 function summaryFor(assets, manifestChanged) {
   const states = {};
   for (const asset of assets) states[asset.state] = (states[asset.state] ?? 0) + 1;
-  const fileChanges = assets.filter((asset) => asset.willApply).length;
+  const applying = assets.filter((asset) => asset.willApply);
+  // Content writes (stale/missing/conflicted accepted) — not version-stamp metadata-only.
+  const wouldWrite = applying.filter((asset) => asset.action !== 'refresh-metadata').length;
+  const metadataRefresh = applying.filter((asset) => asset.action === 'refresh-metadata').length;
+  const customizedPreserved = assets.filter((asset) => asset.state === 'customized').length;
+  const fileChanges = applying.length;
   return {
     total: assets.length,
+    managedAssets: assets.length,
     states,
+    wouldWrite,
+    metadataRefresh,
+    customizedPreserved,
     fileChanges,
     manifestChanged,
+    // Full apply count still includes optional stamp refresh + manifest bookkeeping.
     changed: fileChanges + (manifestChanged ? 1 : 0),
     blocked: assets.filter((asset) => asset.blocked).length,
   };
@@ -505,7 +513,20 @@ export function applyManagedUpgrade(root, plan, expectedPlanDigest) {
   const resolvedRoot = path.resolve(root);
   if (resolvedRoot !== plan.root) throw new Error('managed upgrade plan root mismatch');
   if (plan.summary.blocked > 0) return publicPlan(plan, { blocked: true });
+  const wouldWrite = plan.summary.wouldWrite ?? 0;
+  const metadataRefresh = plan.summary.metadataRefresh ?? 0;
+  // Content already matches: unbound --apply is a no-op (exit success), not a digest error.
+  // Optional stamp-only refresh still requires the preview's exact --plan-digest.
   if (!expectedPlanDigest || expectedPlanDigest !== plan.planDigest) {
+    if (wouldWrite === 0 && (plan.summary.blocked ?? 0) === 0 && !expectedPlanDigest) {
+      return publicPlan(plan, {
+        readOnly: true,
+        applied: false,
+        blocked: false,
+        nothingToApply: true,
+        optionalStampRefresh: metadataRefresh,
+      });
+    }
     throw new Error('managed upgrade plan digest mismatch; run a new preview and use its exact nextCommand');
   }
 
@@ -616,7 +637,55 @@ export function renderManagedUpgrade(plan, options = {}) {
     const consent = asset.requiresConsent ? ' (consent required)' : '';
     console.log(`  ${asset.state.padEnd(10)} ${asset.path}${consent}`);
   }
-  const label = plan.applied ? 'Applied changes' : 'Planned changes';
-  console.log(`${label}: ${plan.summary.changed}; blocked conflicts/deletions: ${plan.summary.blocked}.`);
-  if (!plan.applied) console.log(options.next ?? 'Apply the exact preview with: ark upgrade --apply --no-install');
+  const summary = plan.summary;
+  const managedAssets = summary.managedAssets ?? summary.total ?? plan.assets.length;
+  const wouldWrite = summary.wouldWrite ?? 0;
+  const metadataRefresh = summary.metadataRefresh ?? 0;
+  const customizedPreserved = summary.customizedPreserved ?? summary.states?.customized ?? 0;
+  const blocked = summary.blocked ?? 0;
+  console.log(
+    `Managed assets: ${managedAssets}; would write: ${wouldWrite}; ` +
+      `customized preserved: ${customizedPreserved}; blocked conflicts/deletions: ${blocked}` +
+      (metadataRefresh > 0 ? `; optional stamp refresh: ${metadataRefresh}` : '') +
+      '.'
+  );
+  if (plan.applied) {
+    // Distinguish content writes from optional stamp/metadata bookkeeping.
+    if (wouldWrite === 0 && metadataRefresh > 0) {
+      console.log(
+        `Refreshed ${metadataRefresh} version stamp(s)` +
+          (summary.manifestChanged ? ' and managed manifest' : '') +
+          ' (no content body changes).'
+      );
+    } else {
+      console.log(
+        `Applied ${wouldWrite} content write(s)` +
+          (metadataRefresh > 0 ? `, ${metadataRefresh} stamp refresh(es)` : '') +
+          (summary.manifestChanged ? ', managed manifest' : '') +
+          '.'
+      );
+    }
+    return;
+  }
+  // Content already matches package templates — do not urge --apply as the primary next step.
+  if (wouldWrite === 0 && blocked === 0) {
+    const ver = options.packageVersion ?? arkPackageVersion();
+    const verLabel = ver ? `arkgate@${ver}` : 'the installed arkgate package';
+    console.log(
+      `Nothing to apply — managed content matches ${verLabel} (${customizedPreserved} customized preserved).`
+    );
+    if (metadataRefresh > 0) {
+      console.log(
+        `Optional: ${metadataRefresh} skill stamp(s) lag package version while content is already current.`
+      );
+      const stampCmd = options.optionalStampApply ?? options.next;
+      if (stampCmd) {
+        console.log(`Optional stamp-only apply (not required): ${stampCmd}`);
+      }
+    }
+    return;
+  }
+  console.log(`Planned writes: ${wouldWrite}; blocked conflicts/deletions: ${blocked}.`);
+  if (options.next) console.log(options.next);
+  else console.log('Apply the exact preview with: ark upgrade --apply --no-install');
 }

package/bin/lib/skill-install.mjs

@@ -1,6 +1,7 @@
 /**
  * Tool detection, skill templates, stamping, and skill freshness gaps.
  */
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { arkCommand } from '../ark-shared.mjs';
@@ -206,7 +207,12 @@ export function installedSkillVersion(filePath) {
   } catch {
     return null;
   }
-  const match = content.match(/^arkVersion:\s*(.+)$/m);
+  return skillVersionFromContent(content);
+}
+
+function skillVersionFromContent(content) {
+  if (content == null) return null;
+  const match = String(content).match(/^arkVersion:\s*(.+)$/m);
   return match ? match[1].trim() : null;
 }
 
@@ -225,6 +231,63 @@ export function isVersionOlder(a, b) {
   return false;
 }
 
+/**
+ * Content identity for managed skills — arkVersion stamp is normalized so a lagging
+ * header alone never diverges from the package template (matches managed-upgrade).
+ * @param {string|null|undefined} content
+ * @returns {string|null}
+ */
+export function skillContentIdentity(content) {
+  if (content == null) return null;
+  let text = String(content).replace(/\r\n/g, '\n');
+  const lines = text.split('\n');
+  if (lines[0] === '---') {
+    const end = lines.indexOf('---', 1);
+    if (end >= 0) {
+      for (let index = 1; index < end; index += 1) {
+        if (/^arkVersion:/.test(lines[index])) lines[index] = 'arkVersion:<managed>';
+      }
+      text = lines.join('\n');
+    }
+  }
+  return `sha256:${createHash('sha256').update(text).digest('hex')}`;
+}
+
+/**
+ * True when installed skill body matches the package template for that skill
+ * (version stamp ignored). Used so doctor "stale" aligns with managed upgrade.
+ *
+ * Templates ship without arkVersion; installs are stamped. Identity normalizes
+ * the stamp value, so compare against both the raw template and a stamped copy.
+ * @param {string} installedContent
+ * @param {string|undefined|null} templateContent
+ */
+export function skillContentMatchesTemplate(installedContent, templateContent) {
+  if (templateContent == null || installedContent == null) return false;
+  const installedId = skillContentIdentity(installedContent);
+  if (installedId === skillContentIdentity(templateContent)) return true;
+  // Installed skills are stamped; templates are not — stamp with a dummy version
+  // so arkVersion:<managed> lines align under skillContentIdentity.
+  return installedId === skillContentIdentity(stampSkill(templateContent, '0.0.0'));
+}
+
+/** @returns {Record<string, string>} skill name → template body from package */
+export function skillTemplateBodies() {
+  return Object.fromEntries(skillTemplates());
+}
+
+/**
+ * Count a present skill as stale only when content differs from the package
+ * template AND the arkVersion stamp is missing or older than the package.
+ * Content identity match → never stale (even if header lags).
+ */
+function isInstalledSkillStale(installedContent, templateContent, packageVersion) {
+  if (!packageVersion) return false;
+  if (skillContentMatchesTemplate(installedContent, templateContent)) return false;
+  const installed = skillVersionFromContent(installedContent);
+  return installed === null || isVersionOlder(installed, packageVersion);
+}
+
 export function skillTemplates() {
   const dir = path.join(__packageRoot, 'templates', 'skills');
   // A missing/mispackaged templates dir would otherwise install zero skills with
@@ -263,23 +326,31 @@ export function skillTemplateNames() {
 
 /**
  * Count present / stale / legacy-only skill files for one catalog root.
+ * "stale" means content behind the package template (identity mismatch) with a
+ * missing/older arkVersion stamp — not merely a lagging version header when the
+ * body still matches the template (aligned with managed-upgrade classify).
  * @param {string[]} skillNames
  * @param {(name: string) => string} skillFile path builder
  * @param {string|null} packageVersion
- * @param {{ legacyFile?: (name: string) => string }} [opts]
+ * @param {{ legacyFile?: (name: string) => string, templateBodies?: Record<string, string> }} [opts]
  */
 export function assessSkillCatalogParity(skillNames, skillFile, packageVersion, opts = {}) {
   const expectedCount = skillNames.length;
+  const templates = opts.templateBodies ?? skillTemplateBodies();
   const present = [];
   let stale = 0;
   for (const name of skillNames) {
     const file = skillFile(name);
     if (!fs.existsSync(file)) continue;
-    present.push(name);
-    if (packageVersion) {
-      const installed = installedSkillVersion(file);
-      if (installed === null || isVersionOlder(installed, packageVersion)) stale += 1;
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf8');
+    } catch {
+      // Unreadable path is not a usable install — count as missing (matches detectSkillGaps).
+      continue;
     }
+    present.push(name);
+    if (isInstalledSkillStale(content, templates[name], packageVersion)) stale += 1;
   }
   let legacyCount = 0;
   if (typeof opts.legacyFile === 'function') {
@@ -291,6 +362,7 @@ export function assessSkillCatalogParity(skillNames, skillFile, packageVersion,
   const missing = expectedCount - presentCount;
   const legacyPromptsOnly = presentCount === 0 && legacyCount > 0;
   const hasLegacyPrompts = legacyCount > 0;
+  // Legacy prompts beside a complete modern catalog are not catalog debt.
   const ok = missing === 0 && stale === 0 && !legacyPromptsOnly;
   return {
     ok,
@@ -302,6 +374,7 @@ export function assessSkillCatalogParity(skillNames, skillFile, packageVersion,
     legacyPromptsOnly,
     hasLegacyPrompts,
     legacyCount,
+    catalogComplete: missing === 0 && stale === 0 && presentCount === expectedCount,
   };
 }
 
@@ -490,6 +563,7 @@ export function detectSkillGaps(root) {
   if (fs.existsSync(path.join(root, 'templates', 'skills'))) return [];
   const skillNames = skillTemplateNames();
   if (skillNames.length === 0) return [];
+  const templates = skillTemplateBodies();
   const detected = [];
   if (fs.existsSync(path.join(root, '.claude'))) detected.push('claude');
   if (fs.existsSync(path.join(root, '.cursor'))) detected.push('cursor');
@@ -510,16 +584,21 @@ export function detectSkillGaps(root) {
       const file = path.join(root, target(name));
       if (!fs.existsSync(file)) {
         missing += 1;
-      } else if (version) {
-        // An installed skill with no stamp predates stamping (older Ark), or one
-        // stamped behind the current version is left over from an older install.
-        // Either way the shipped skill has moved on — offer a --force refresh.
-        const installed = installedSkillVersion(file);
-        if (installed === null || isVersionOlder(installed, version)) stale += 1;
+        continue;
+      }
+      let content;
+      try {
+        content = fs.readFileSync(file, 'utf8');
+      } catch {
+        missing += 1;
+        continue;
       }
+      // Content identity match with package template → not stale (version header may lag).
+      if (isInstalledSkillStale(content, templates[name], version)) stale += 1;
     }
     let legacyPromptsOnly = false;
     let hasLegacyPrompts = false;
+    let legacyAdvisory = false;
     if (tool === 'codex') {
       const legacyCount = skillNames.filter((name) =>
         fs.existsSync(path.join(root, '.codex', 'prompts', `${name}.md`))
@@ -527,14 +606,20 @@ export function detectSkillGaps(root) {
       hasLegacyPrompts = legacyCount > 0;
       // Flat prompts without any SKILL.md catalog entries are not loadable.
       legacyPromptsOnly = hasLegacyPrompts && missing === skillNames.length;
+      // Modern catalog complete + leftover flat prompts → advisory only (safe delete).
+      legacyAdvisory =
+        hasLegacyPrompts && !legacyPromptsOnly && missing === 0 && stale === 0;
     }
-    if (missing > 0 || stale > 0 || legacyPromptsOnly) {
+    if (missing > 0 || stale > 0 || legacyPromptsOnly || legacyAdvisory) {
       gaps.push({
         tool,
         missing,
         stale,
         ...(legacyPromptsOnly ? { legacyPromptsOnly: true } : {}),
         ...(hasLegacyPrompts ? { hasLegacyPrompts: true } : {}),
+        ...(legacyAdvisory
+          ? { legacyAdvisory: true, catalogComplete: true }
+          : {}),
       });
     }
   }
@@ -550,8 +635,14 @@ 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(
+      (gap) => gap.tool === 'codex' && gap.legacyAdvisory && gap.catalogComplete
+    );
     // Report Codex legacy separately; never suppress missing/stale for other hosts.
-    const remaining = skillGaps.filter((gap) => !(gap.tool === 'codex' && gap.legacyPromptsOnly));
+    const remaining = skillGaps.filter(
+      (gap) =>
+        !(gap.tool === 'codex' && (gap.legacyPromptsOnly || gap.legacyAdvisory))
+    );
     const missingTotal = remaining.reduce((sum, gap) => sum + gap.missing, 0);
     const staleTotal = remaining.reduce((sum, gap) => sum + gap.stale, 0);
     const tools = remaining.map((gap) => gap.tool).join(', ');
@@ -563,6 +654,13 @@ export function printSkillAndCodexGapHints(root, opts) {
         )
       );
     }
+    if (legacyAdvisory) {
+      console.log(
+        color.dim(
+          'Codex .agents/skills catalog is complete; leftover .codex/prompts/ark-*.md are not loadable and safe to delete (not required).'
+        )
+      );
+    }
     if (missingTotal > 0) {
       console.log(
         color.dim(
@@ -574,7 +672,7 @@ export function printSkillAndCodexGapHints(root, opts) {
     if (staleTotal > 0) {
       console.log(
         color.dim(
-          `${staleTotal} /ark-* skill(s) outdated for ${tools} (this Ark ships newer versions). ` +
+          `${staleTotal} /ark-* skill(s) content behind this Ark package for ${tools}. ` +
             `Refresh: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`
         )
       );
@@ -584,7 +682,7 @@ export function printSkillAndCodexGapHints(root, opts) {
     const parts = [];
     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} outdated`);
+    if (codexHomeGap.stale > 0) parts.push(`${codexHomeGap.stale} content-behind-package`);
     const deferred = !codexSessionActive;
     const deferredNote = deferred
       ? ' Deferred unless you use Codex — not a blocker for Grok/Claude/Cursor. '
@@ -600,7 +698,7 @@ export function printSkillAndCodexGapHints(root, opts) {
     const parts = [];
     if (codexRepoSkillGap.legacyPromptsOnly) parts.push('legacy-prompts-only');
     if (codexRepoSkillGap.missing > 0) parts.push(`${codexRepoSkillGap.missing} missing`);
-    if (codexRepoSkillGap.stale > 0) parts.push(`${codexRepoSkillGap.stale} outdated`);
+    if (codexRepoSkillGap.stale > 0) parts.push(`${codexRepoSkillGap.stale} content-behind-package`);
     console.log(
       color.yellow(
         `Codex repo skill catalog (.agents/skills) needs refresh (${parts.join(', ')}). ` +

package/bin/lib/start-preview.mjs

@@ -70,12 +70,14 @@ function setupBudget(changes) {
     (total, item) => total + (item.afterBase64 ? Buffer.from(item.afterBase64, 'base64').length : 0),
     0
   );
+  // Compact start includes shared MCP + one host registration + CI + AGENTS + config.
+  // Budget raised from 5→8 so .mcp.json always fits (field: grok compact hit the old ceiling).
   return {
     files: generatedChanges.length,
     bytes,
-    maxFiles: 5,
-    maxBytes: 25 * 1024,
-    ok: generatedChanges.length <= 5 && bytes < 25 * 1024,
+    maxFiles: 8,
+    maxBytes: 32 * 1024,
+    ok: generatedChanges.length <= 8 && bytes < 32 * 1024,
   };
 }
 
@@ -84,7 +86,8 @@ function commands(root, args, helpers) {
     return [`ark start --root ${root} --tools ${args.removeHost} --apply`];
   }
   const result = [];
-  if (args.installExplicit && args.install && fs.existsSync(path.join(root, 'package.json'))) {
+  // Default install=true: surface the package pin/install command unless --no-install.
+  if (args.install !== false && fs.existsSync(path.join(root, 'package.json'))) {
     const [command, commandArgs] = helpers.packageInstallArgv(root, `^${helpers.cliVersion()}`);
     result.push(`${command} ${commandArgs.join(' ')}`);
   }
@@ -216,8 +219,9 @@ export async function planStart(args, helpers) {
     if (args.yes) childArgs.push('--yes');
     if (args.force) childArgs.push('--force');
     if (!args.strict) childArgs.push('--no-strict');
-    if (args.installExplicit && args.install) childArgs.push('--install');
-    if (args.installExplicit && !args.install) childArgs.push('--no-install');
+    // Propagate install intent into the shadow plan so package.json pin is in the diff by default.
+    if (args.install === false) childArgs.push('--no-install');
+    else childArgs.push('--install');
     if (args.tools) childArgs.push('--tools', args.tools);
     if (args.requireWriteHook) childArgs.push('--require-write-hook', args.requireWriteHook);
     const planned = spawnSync(process.execPath, [helpers.cliPath, ...childArgs], {

package/bin/lib/upgrade-command.mjs

@@ -55,23 +55,50 @@ function verify(root, json, arkCheck, runArkCheck) {
 export function runUpgradeCommand(args, dependencies) {
   const root = args.root;
   if (args.apply && args.install) {
-    const [command, commandArgs] = dependencies.packageInstallArgv(root);
-    if (!args.json) console.log(`Updating ArkGate: ${command} ${commandArgs.join(' ')}`);
-    const install = spawnSync(command, commandArgs, {
-      cwd: root,
-      stdio: args.json ? ['ignore', 'pipe', 'pipe'] : 'inherit',
-      encoding: 'utf8',
-    });
-    const exitCode = install.status ?? 1;
-    if (exitCode !== 0) {
-      if (args.json && install.stderr) console.error(install.stderr.trim());
+    const skip =
+      typeof dependencies.shouldSkipArkgateInstall === 'function'
+        ? dependencies.shouldSkipArkgateInstall(root, dependencies.cliVersion)
+        : { skip: false };
+    if (skip.skip) {
+      if (!args.json) {
+        console.log(
+          `Package already at arkgate@${skip.installedVersion}; skipping install and recomputing managed preview.`
+        );
+      }
+    } else {
+      const [command, commandArgs] = dependencies.packageInstallArgv(root);
+      if (!args.json) console.log(`Updating ArkGate: ${command} ${commandArgs.join(' ')}`);
+      const install = spawnSync(command, commandArgs, {
+        cwd: root,
+        stdio: args.json ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+        encoding: 'utf8',
+      });
+      const exitCode = install.status ?? 1;
+      if (exitCode !== 0) {
+        if (args.json && install.stderr) console.error(install.stderr.trim());
+        const recovery = `${command} ${commandArgs.join(' ')}`;
+        console.error(
+          `Package update failed (exit ${exitCode}). Fix the install and re-run:\n` +
+            `  ${recovery}\n` +
+            `Then: ark upgrade --no-install --root ${JSON.stringify(root)}` +
+            (args.tools ? ` --tools ${args.tools}` : '') +
+            (!args.strict ? ' --no-strict' : '') +
+            (args.json ? ' --json' : '')
+        );
+        return exitCode;
+      }
+    }
+    // Re-enter via installed CLI so the managed plan uses the newly installed package bytes.
+    let cli;
+    try {
+      cli = installedCli(root);
+    } catch {
       console.error(
-        `Package update failed (exit ${exitCode}). Fix the install and re-run, or use ` +
-          '`ark upgrade --no-install` against the installed version.'
+        'arkgate is not installed in this project after the package step. Install it, then re-run with --no-install.'
       );
-      return exitCode;
+      return 1;
     }
-    return spawnSync(process.execPath, [installedCli(root), ...previewArgs(args)], {
+    return spawnSync(process.execPath, [cli, ...previewArgs(args)], {
       cwd: root,
       stdio: 'inherit',
       encoding: 'utf8',
@@ -83,19 +110,42 @@ export function runUpgradeCommand(args, dependencies) {
     acceptConflicts: args.acceptConflicts,
   });
   if (!args.apply) {
+    const wouldWrite = plan.summary?.wouldWrite ?? 0;
+    const blocked = plan.summary?.blocked ?? 0;
+    const needsApply = wouldWrite > 0 || blocked > 0;
     const command = nextCommand(args, plan.planDigest);
-    if (args.json) console.log(managedUpgradeJson(plan, { nextCommand: command }));
-    else {
+    if (args.json) {
+      // Always expose nextCommand for digest-bound apply (metadata/manifest optional);
+      // nothingToApply flags when content writes are zero so UIs do not urge apply.
+      console.log(
+        managedUpgradeJson(plan, {
+          nextCommand: command,
+          ...(needsApply ? {} : { nothingToApply: true }),
+        })
+      );
+    } else {
+      const metadataRefresh = plan.summary?.metadataRefresh ?? 0;
       renderManagedUpgrade(plan, {
-        next: args.install
-          ? `Update the package and recompute this preview with: ${command}`
-          : `Apply the exact preview with: ${command}`,
+        next: needsApply
+          ? args.install
+            ? `Update the package and recompute this preview with: ${command}`
+            : `Apply the exact preview with: ${command}`
+          : undefined,
+        // Human path: optional digest-bound stamp refresh without urging content apply.
+        ...( !needsApply && metadataRefresh > 0 ? { optionalStampApply: command } : {}),
       });
     }
     return 0;
   }
 
-  const applied = applyManagedUpgrade(root, plan, args.planDigest);
+  let applied;
+  try {
+    applied = applyManagedUpgrade(root, plan, args.planDigest);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    return 2;
+  }
   if (applied.blocked) {
     if (args.json) console.log(JSON.stringify(applied, null, 2));
     else renderManagedUpgrade(applied, {
@@ -103,6 +153,14 @@ export function runUpgradeCommand(args, dependencies) {
     });
     return 1;
   }
+  if (applied.nothingToApply && !applied.applied) {
+    if (args.json) console.log(JSON.stringify(applied, null, 2));
+    else {
+      renderManagedUpgrade(applied);
+      console.log('No managed content writes pending (optional stamp refresh needs --plan-digest).');
+    }
+    return 0;
+  }
   const verification = args.strict
     ? { mode: 'strict-merge', ...verify(root, args.json, dependencies.arkCheck, dependencies.runArkCheck) }
     : { mode: 'skipped', exitCode: 0 };

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

@@ -15,6 +15,43 @@ function installToolsForHost(activeHost) {
     : activeHost;
 }
 
+/**
+ * Human/JSON note when doctor runs outside an agent host: inventory on disk vs
+ * this-invocation hardness (Z10 — never claim hard from assets alone).
+ * @param {{ hosts?: Record<string, unknown>, capabilities?: Record<string, boolean> }|null|undefined} inventory
+ * @param {Record<string, boolean>} capabilities active-host projection
+ * @returns {string}
+ */
+export function buildUnknownHostSessionNote(inventory, capabilities = {}) {
+  const hosts = inventory?.hosts && typeof inventory.hosts === 'object' ? inventory.hosts : {};
+  const onDiskHosts = Object.entries(hosts)
+    .filter(([, record]) => {
+      if (!record || typeof record !== 'object') return false;
+      const caps = /** @type {{ [k: string]: boolean }} */ (record).capabilities ?? {};
+      const configured = Boolean(/** @type {{ configured?: boolean }} */ (record).configured);
+      return (
+        configured ||
+        Boolean(caps['hard-write']) ||
+        Boolean(caps['advisory-write']) ||
+        Boolean(caps['repair-payload'])
+      );
+    })
+    .map(([name]) => name)
+    .sort();
+  const parts = [];
+  if (onDiskHosts.length > 0) {
+    parts.push(`On-disk hosts with write-path assets: ${onDiskHosts.join(', ')}`);
+  }
+  if (inventory?.capabilities?.['merge-gate'] || capabilities['merge-gate']) {
+    parts.push('CI merge gate configured on disk');
+  }
+  parts.push(
+    'This invocation has no active hard-write guarantee (activeHost unknown); ' +
+      'required-status remains unverified without provider evidence'
+  );
+  return `${parts.join('. ')}.`;
+}
+
 export function detectWritePathCapabilities(root, explicitHost, attempt) {
   const model = buildWritePathCapabilityModel(root, explicitHost, attempt);
   const { activeHost, support, capabilities, capabilityEvidence, enforcementLadder, enforcementState, inventory } = model;
@@ -92,6 +129,12 @@ export function detectWritePathCapabilities(root, explicitHost, attempt) {
     };
   }
 
+  /** @type {string|null} */
+  const sessionNote =
+    activeHost === 'unknown'
+      ? buildUnknownHostSessionNote(inventory, capabilities)
+      : null;
+
   return {
     activeHost,
     support,
@@ -101,6 +144,8 @@ export function detectWritePathCapabilities(root, explicitHost, attempt) {
     enforcementLadder,
     enforcementState,
     inventory,
+    // Configured inventory (on-disk hosts) vs this-invocation projection (activeHost).
+    ...(sessionNote ? { sessionNote } : {}),
     // Compatibility projection for existing doctor/API consumers.
     mode,
     prepareWrite: advisoryWrite,