@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/forge_protection.ts

@@ -1,5 +1,5 @@
 /**
- * The five `forge_protection` rows, read from the forge rather than guessed.
+ * The six `forge_protection` rows, read from the forge rather than guessed.
  *
  * `road-to-adversarial-verification-and-long-runs` Phase 3.2. ADR-268 § 3 trades
  * the owner's confirmation for a mechanical check, and branch protection is the
@@ -45,13 +45,26 @@ export interface ProtectionRow {
     readonly detail: string;
 }
 
-/** The five rows, in the order the blocker's own table lists them. */
+/**
+ * The rows, in the order the blocker's own table lists them, plus the
+ * authority-surface row added 2026-10-12.
+ *
+ * **Why the sixth row exists.** A governance hold elsewhere in this package is
+ * declared resolved when this very command reports an external approver for the
+ * authority surface. Measured 2026-10-12: no row spoke about required reviewers
+ * at all, so that condition was unanswerable in EITHER direction — and a
+ * condition whose test cannot run is not a strict one, it is an unmeasured one.
+ * The row exists to make the negative answerable: it reports `unsatisfied` while
+ * no forge-side approval requirement covers the default branch, which is a
+ * machine-readable fact where silence was.
+ */
 export const PROTECTION_ROW_IDS: readonly string[] = [
     'default_branch_protected',
     'required_checks_present',
     'force_push_disabled',
     'auto_merge_available',
     'deploy_via_pipeline_only',
+    'authority_surface_external_approval',
 ] as const;
 
 /** What a caller must supply for a row to be readable. `null` = not read. */
@@ -210,6 +223,55 @@ function hasRule(rs: RulesetDetail, type: string): boolean {
     return (rs.rules ?? []).some((r) => r.type === type);
 }
 
+/**
+ * The `pull_request` rule's approval surface, as this row reads it.
+ *
+ * A NARROW PROJECTION of the real payload, declared the same way
+ * {@link EnvironmentPolicy} is and for the same reason: the response also
+ * carries `allowed_merge_methods`, `dismiss_stale_reviews_on_push`,
+ * `required_review_thread_resolution` and more, and naming only the three
+ * fields this decision rests on says which ones it rests on.
+ */
+interface ApprovalParameters {
+    readonly required_approving_review_count?: number;
+    readonly require_code_owner_review?: boolean;
+    readonly required_reviewers?: readonly unknown[];
+}
+
+/** The `pull_request` rule's parameters across `rs`, or `null` when it has none. */
+function approvalParameters(rs: RulesetDetail): ApprovalParameters | null {
+    for (const r of rs.rules ?? []) {
+        if (r.type !== 'pull_request') continue;
+        const p = r.parameters;
+        if (p === null || typeof p !== 'object') return {};
+        return p as ApprovalParameters;
+    }
+    return null;
+}
+
+/**
+ * Which forge-side mechanisms, if any, make an approving review mandatory.
+ *
+ * Three mechanisms, because GitHub has three and reading one would report "no
+ * approval required" for a repository that requires one by a different route:
+ * a numeric approving-review count, code-owner review (the path-scoped route,
+ * resolved through `CODEOWNERS`), and an explicit `required_reviewers` list.
+ */
+export function approvalMechanisms(rulesets: readonly RulesetDetail[]): string[] {
+    const found: string[] = [];
+    for (const rs of rulesets) {
+        const p = approvalParameters(rs);
+        if (p === null) continue;
+        const count = p.required_approving_review_count ?? 0;
+        if (count >= 1) found.push(`required_approving_review_count=${String(count)}`);
+        if (p.require_code_owner_review === true) found.push('require_code_owner_review');
+        if ((p.required_reviewers ?? []).length > 0) {
+            found.push(`required_reviewers=${String((p.required_reviewers ?? []).length)}`);
+        }
+    }
+    return found;
+}
+
 function requiredContexts(rs: RulesetDetail): string[] {
     for (const r of rs.rules ?? []) {
         if (r.type !== 'required_status_checks') continue;
@@ -352,9 +414,85 @@ export function forgeProtectionRows(reading: ForgeReading): ProtectionRow[] {
               },
     );
 
+    rows.push(authorityApprovalRow(covering));
+
     return rows;
 }
 
+/**
+ * The authority-surface row — and the one row that states what it does NOT
+ * establish, because overstating it is the specific failure here.
+ *
+ * It answers ONE of the three assertions a hold of this kind rests on:
+ *
+ * 1. *declared intent* — which surfaces a committed policy says need approval.
+ *    Not read here: that declaration lives in the candidate branch, so reading
+ *    it from the candidate would let the change under review supply its own
+ *    permission.
+ * 2. *observed forge state* — whether the live configuration actually requires
+ *    an approving review, and whether an unconditional bypass voids it. **This
+ *    is the half the row reads**, and it is the only one of the three a forge
+ *    payload can carry.
+ * 3. *principal qualification* — whether the approver is a genuinely separate
+ *    person who accepted the duty and is reachable. Not derivable from any API
+ *    response: membership and permissions are readable, custody and willingness
+ *    are not.
+ *
+ * So `satisfied` means *a forge-side approval requirement exists and no
+ * unconditional bypass voids it* — never *the approval comes from someone other
+ * than the author*. A caller that needs the stronger claim gets it from a live
+ * test, not from this row, and the detail line says so rather than leaving a
+ * reader to infer the narrower meaning.
+ *
+ * The bypass clause is not decoration: an approval requirement a listed actor
+ * may skip unconditionally is advisory, so reporting it `satisfied` would be
+ * the quiet false positive the three-state row type exists to prevent.
+ */
+function authorityApprovalRow(covering: readonly RulesetDetail[] | null): ProtectionRow {
+    if (covering === null) {
+        return {
+            id: 'authority_surface_external_approval',
+            state: 'unread',
+            source: SOURCE.rulesets,
+            detail: 'the rulesets were not queried',
+        };
+    }
+    const mechanisms = approvalMechanisms(covering);
+    if (mechanisms.length === 0) {
+        return {
+            id: 'authority_surface_external_approval',
+            state: 'unsatisfied',
+            source: SOURCE.rulesets,
+            detail:
+                'no covering ruleset requires an approving review — no approving-review count, ' +
+                'no code-owner review and no required reviewers. Any principal with write access ' +
+                'can therefore merge an authority-surface change alone.',
+        };
+    }
+    const bypass = covering.flatMap((rs) =>
+        (rs.bypass_actors ?? []).filter((a) => a.bypass_mode === 'always'),
+    );
+    if (bypass.length > 0) {
+        return {
+            id: 'authority_surface_external_approval',
+            state: 'unsatisfied',
+            source: SOURCE.rulesets,
+            detail:
+                `an approval requirement exists (${mechanisms.join(', ')}) but ` +
+                `${String(bypass.length)} actor(s) may bypass it unconditionally, so it does not bind`,
+        };
+    }
+    return {
+        id: 'authority_surface_external_approval',
+        state: 'satisfied',
+        source: SOURCE.rulesets,
+        detail:
+            `an approving review is required and unbypassable (${mechanisms.join(', ')}). ` +
+            'This states the forge requirement ONLY — it does not establish that the approver ' +
+            'is a principal distinct from the author, which no API response can show.',
+    };
+}
+
 /**
  * The human ACTION lines for rows that are not satisfied.
  *

package/src/scripts/_lib/global_deploy_inventory.ts

@@ -35,16 +35,28 @@
  * Schema (JSON):
  *
  *     {
- *       "schema_version": 1,
+ *       "schema_version": 2,
  *       "tools": {
  *         "<tool_id>": {
  *           "anchor": "/abs/path/to/anchor",
- *           "files": ["skills/foo/SKILL.md", ...]   // anchor-relative, sorted
+ *           "files": ["skills/foo/SKILL.md", ...],  // anchor-relative, sorted
+ *           "digests": {                             // schema 2, additive
+ *             "skills/foo/SKILL.md": {
+ *               "installed_sha256": "…",             // the bytes we wrote
+ *               "packaged_sha256": "…"               // the bytes we ship now; null = retired
+ *             }
+ *           }
  *         }
  *       }
  *     }
+ *
+ * Schema 2 is ADDITIVE: `files` keeps its schema-1 meaning, so every reader that treats it
+ * as a path allowlist works unchanged on either schema, and a schema-1 file
+ * loads as an inventory without digests. The digests are the user-scoped
+ * ownership ledger: written on every global deploy whatever directory the
+ * install ran from, and read by the reaper so an edit is seen before an unlink.
  */
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -56,7 +68,7 @@ export type EnvMap = Record<string, string | undefined>;
 /** Loosely-typed inventory dict, mirroring Python's `dict`. */
 export type Inventory = Record<string, unknown>;
 
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 export const INVENTORY_BASENAME = "deployed-files.json";
 export const INVENTORY_ENV = "AGENT_CONFIG_DEPLOY_INVENTORY";
 
@@ -374,6 +386,13 @@ function as_posix(p: string): string {
  * directories — the preview surface for `agent-config install --dry-run`. The selection
  * logic (orphan diff, containment proof, directory guard) is identical to the
  * live path, so the preview is exact.
+ *
+ * An orphan whose bytes differ from the digest the ledger recorded writing is
+ * NOT deleted: the user edited a file the package retired, and an unlink would
+ * destroy that edit without it ever being seen. Its absolute path is pushed to
+ * `retained` instead, so the caller can say so and keep the record. Orphans are
+ * read from `files` AND from the recorded digests, because a retained file is
+ * no longer shipped and stays recorded only there.
  */
 export function reap_stale(
   tool_id: string,
@@ -381,6 +400,7 @@ export function reap_stale(
   current_files: Set<string>,
   inventory: Inventory,
   dry_run = false,
+  retained: string[] | null = null,
 ): string[] {
   const tools = (inventory["tools"] as Record<string, unknown> | undefined) ?? {};
   const entry = tools[tool_id];
@@ -402,7 +422,11 @@ export function reap_stale(
 
   const deleted: string[] = [];
   const prune_candidates = new Set<string>();
-  const orphans = difference(prev_files as unknown[], current_files);
+  const digests = digests_of_entry(e);
+  // A preview cannot know which sidecars the real run stages again, and a
+  // staged sidecar is kept — so the preview never names one as would-delete.
+  const recorded = [...digests].filter(([, d]) => !(dry_run && d.kind === "sidecar")).map(([rel]) => rel);
+  const orphans = difference([...(prev_files as unknown[]), ...recorded], current_files);
   for (const rel of sorted_strings(orphans)) {
     if (typeof rel !== "string" || !rel || rel.startsWith("/") || rel.startsWith("..")) {
       continue;
@@ -424,6 +448,10 @@ export function reap_stale(
     if (lst && lst.isDirectory() && !lst.isSymbolicLink()) {
       continue; // never delete directories
     }
+    if (lst !== null && edited_since_install(target, digests.get(rel))) {
+      retained?.push(target);
+      continue;
+    }
     if (dry_run) {
       // Preview: report only what is actually on disk and would go.
       if (path_exists(target) || (lst !== null && lst.isSymbolicLink())) {
@@ -472,6 +500,12 @@ export function reap_stale(
  * `dry_run=true` returns the would-delete set (tagged orphans actually present
  * on disk) WITHOUT unlinking or pruning — the preview surface for
  * `agent-config install --dry-run`. Selection logic is identical to the live path.
+ *
+ * The tag survives a user's edit, so it proves we WROTE the file, never that it
+ * is still what we wrote. A tagged orphan the ledger (`digests`) recorded with
+ * a digest its bytes no longer match is pushed to `retained` and kept, exactly
+ * as {@link reap_stale} keeps it. A tagged orphan with no recorded digest — an
+ * install older than the ledger — is still reaped: there is nothing to compare.
  */
 export function reap_tagged_orphans(
   anchor: string,
@@ -479,6 +513,8 @@ export function reap_tagged_orphans(
   current_files: Set<string>,
   package_tag: string,
   dry_run = false,
+  digests: ReadonlyMap<string, LedgerDigest> = new Map(),
+  retained: string[] | null = null,
 ): string[] {
   const anchor_resolved = resolve_path(expanduser(anchor));
   const deleted: string[] = [];
@@ -529,6 +565,10 @@ export function reap_tagged_orphans(
       if (!hit) {
         continue;
       }
+      if (edited_since_install(md, digests.get(rel))) {
+        retained?.push(md);
+        continue;
+      }
       if (dry_run) {
         deleted.push(md);
         continue;
@@ -559,6 +599,7 @@ export function record_deploy(
   anchor: string,
   current_files: Set<string>,
   inventory: Inventory,
+  digests: ReadonlyMap<string, LedgerDigest> | null = null,
 ): Inventory {
   if (
     typeof inventory["tools"] !== "object" ||
@@ -568,14 +609,126 @@ export function record_deploy(
     inventory["tools"] = {};
   }
   const tools = inventory["tools"] as Record<string, unknown>;
-  tools[tool_id] = {
+  const record: Record<string, unknown> = {
     anchor: String(anchor),
     files: sorted_strings([...current_files]),
   };
+  // Omitted rather than emptied when the caller has none: an entry written by a
+  // caller that computes no digests reads exactly as a schema-1 entry did.
+  if (digests !== null && digests.size > 0) {
+    record["digests"] = Object.fromEntries(
+      sorted_strings([...digests.keys()]).map((rel) => [rel, { ...digests.get(rel) }]),
+    );
+  }
+  tools[tool_id] = record;
   inventory["schema_version"] = SCHEMA_VERSION;
   return inventory;
 }
 
+/**
+ * One file's ledger record. `kind: "sidecar"` marks package content staged
+ * beside a preserved edit; absent means a deployed file.
+ */
+export interface LedgerDigest {
+  installed_sha256: string;
+  packaged_sha256: string | null;
+  kind?: "sidecar";
+}
+
+/** SHA-256 of the bytes at `p`, or `null` when they cannot be read. */
+export function file_sha256(p: string): string | null {
+  try {
+    return createHash("sha256").update(fs.readFileSync(p)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+/** True when `target` is readable and its bytes differ from the recorded installed digest. */
+function edited_since_install(target: string, rec: LedgerDigest | undefined): boolean {
+  if (rec === undefined) return false;
+  const on_disk = file_sha256(target);
+  if (on_disk !== null) return on_disk !== rec.installed_sha256;
+  // Unreadable bytes are an unknown edit state, so a real file is kept and
+  // reported. A dangling symlink holds no bytes to lose and may still go.
+  try {
+    return !fs.lstatSync(target).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** Parse a tool entry's `digests` map; a malformed record contributes nothing. */
+function digests_of_entry(e: Record<string, unknown>): Map<string, LedgerDigest> {
+  const out = new Map<string, LedgerDigest>();
+  const raw = e["digests"];
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return out;
+  for (const [rel, rec] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof rec !== "object" || rec === null || Array.isArray(rec)) continue;
+    const r = rec as Record<string, unknown>;
+    const installed = r["installed_sha256"];
+    const packaged = r["packaged_sha256"];
+    if (typeof installed !== "string" || installed === "") continue;
+    out.set(rel, {
+      installed_sha256: installed,
+      packaged_sha256: typeof packaged === "string" && packaged !== "" ? packaged : null,
+      ...(r["kind"] === "sidecar" ? { kind: "sidecar" as const } : {}),
+    });
+  }
+  return out;
+}
+
+/**
+ * The ledger records of `tool_id`, keyed anchor-relative. Empty under the same
+ * "not provably ours anymore" conditions as {@link recorded_rel_files} (no
+ * entry, moved anchor, malformed entry), and empty for a schema-1 entry.
+ */
+export function recorded_digests(
+  tool_id: string,
+  anchor: string,
+  inventory?: Inventory | null,
+): Map<string, LedgerDigest> {
+  const inv = inventory ?? load_inventory();
+  const tools = (inv["tools"] as Record<string, unknown> | undefined) ?? {};
+  const entry = tools[tool_id];
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return new Map();
+  const e = entry as Record<string, unknown>;
+  const recorded_anchor = e["anchor"];
+  if (typeof recorded_anchor !== "string") return new Map();
+  if (resolve_path(expanduser(recorded_anchor)) !== resolve_path(expanduser(anchor))) {
+    return new Map();
+  }
+  return digests_of_entry(e);
+}
+
+/**
+ * Every recorded INSTALLED digest across all tools, keyed by absolute path in
+ * both spellings — the lookup the install conflict tracker needs, emitted in
+ * both spellings for the reason {@link recorded_absolute_files} gives.
+ */
+export function recorded_absolute_digests(
+  inventory?: Inventory | null,
+  home?: string | null,
+): Map<string, string> {
+  const inv = inventory ?? load_inventory();
+  const tools = (inv["tools"] as Record<string, unknown> | undefined) ?? {};
+  const out = new Map<string, string>();
+  if (typeof tools !== "object" || tools === null || Array.isArray(tools)) return out;
+  for (const entry of Object.values(tools)) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) continue;
+    const e = entry as Record<string, unknown>;
+    const anchor = e["anchor"];
+    if (typeof anchor !== "string") continue;
+    const expanded = expanduser_at(anchor, home);
+    for (const [rel, rec] of digests_of_entry(e)) {
+      const lexical = path.resolve(expanded, rel);
+      out.set(lexical, rec.installed_sha256);
+      out.set(resolve_path(lexical), rec.installed_sha256);
+    }
+  }
+  return out;
+}
+
 // --- helpers ---------------------------------------------------------------
 
 /** Prune now-empty directories up to (exclusive) the anchor. */

package/src/scripts/_lib/guidelines_lane.ts

@@ -122,7 +122,8 @@ export function rewriteProjectedBodyLinks(body: string, prefix: string): string
     return body
         .replace(BODY_DOCS_RE, (_m, t: string) => prefix + t.replace(/^docs\/guidelines\//, 'guidelines/'))
         .replace(BODY_SRC_FLAT_RE, (_m, t: string) => prefix + t)
-        .replace(BODY_SRC_AGENT_RE, (_m, t: string) => prefix + t);
+        .replace(BODY_SRC_AGENT_RE, (_m, t: string) => prefix + t)
+        .replace(LINK_AGENT_SRC_RE, (_m, t: string) => '](' + prefix + t);
 }
 
 /**
@@ -162,3 +163,13 @@ const BODY_DOCS_RE = /(?:\.\.\/)+(docs\/(?:guidelines|contracts)\/[^)\s]+\.md)/g
 const BODY_SRC_FLAT_RE = /(?:\.\.\/)+src\/((?:rules|skills)\/[^)\s]+\.md)/g;
 const BODY_SRC_AGENT_RE =
     /(?:\.\.\/)+src\/agent-src\/((?:commands|contexts|personas|user-types|templates|scripts)\/[^)\s]+\.md)/g;
+
+/**
+ * A link written from inside `src/` that climbs to `src/agent-src/` without
+ * naming `src/` — `](../../agent-src/contexts/x.md)` from `src/skills/<slug>/`.
+ * It resolves in the source tree and to nothing in the projection, where the
+ * `agent-src/` segment does not exist. Anchored on `](` so only a link target
+ * moves, never a path mentioned in prose or an inline code span.
+ */
+const LINK_AGENT_SRC_RE =
+    /\]\((?:\.\.\/)+agent-src\/((?:commands|contexts|personas|user-types|templates|scripts)\/[^)\s]*)/g;

package/src/scripts/_lib/hand_kinds.ts

@@ -0,0 +1,65 @@
+/**
+ * The closed set of task kinds a hand may be asked to do: bounded, typed,
+ * tool-less work whose output is a proposal the head checks before anything
+ * acts on it.
+ *
+ * Deliberately free of schemas and prompts so the delegation-nudge hook can
+ * import it without paying for them in the hook bundle.
+ */
+
+export const HAND_KINDS = [
+    'classify',
+    'extract',
+    'summarise-given-text',
+    'draft-candidate',
+    'test-candidates',
+    'finding-proposal',
+] as const;
+export type HandKind = (typeof HAND_KINDS)[number];
+
+/**
+ * Work that stays with the paid head whatever route exists: an unpaid route may
+ * propose and score, never decide (ADR-257). These are refused before any route
+ * is chosen.
+ */
+export const HEAD_ONLY_KINDS = ['plan', 'decide', 'chair', 'final-review', 'write'] as const;
+export type HeadOnlyKind = (typeof HEAD_ONLY_KINDS)[number];
+
+const _KINDS: ReadonlySet<string> = new Set<string>(HAND_KINDS);
+const _HEAD_ONLY: ReadonlySet<string> = new Set<string>(HEAD_ONLY_KINDS);
+
+/** How a route is paid for; the two unpaid classes are the hands whose every return the head must verify. */
+export const ROUTE_BILLINGS = ['free-quota', 'self-hosted', 'per-token', 'subscription'] as const;
+export type RouteBilling = (typeof ROUTE_BILLINGS)[number];
+
+export function isUnpaid(billing: RouteBilling): boolean {
+    return billing === 'free-quota' || billing === 'self-hosted';
+}
+
+/** The head's verdict on one hand's return; `skipped` is recorded, never silent. */
+export const VERIFY_VERDICTS = ['pass', 'fail', 'skipped'] as const;
+export type VerifyVerdict = (typeof VERIFY_VERDICTS)[number];
+
+export function isHandKind(raw: unknown): raw is HandKind {
+    return typeof raw === 'string' && _KINDS.has(raw);
+}
+
+/** Leading-verb shapes, most specific first: "propose tests" is not "propose findings" or "draft". */
+const KIND_FROM_PROMPT: ReadonlyArray<readonly [RegExp, HandKind]> = [
+    [/^\s*(?:propose|suggest|draft|write)\s+(?:unit\s+)?test(?:s|\s+cases?|\s+candidates?)?\b/i, 'test-candidates'],
+    [/^\s*(?:propose|list)\s+(?:review\s+)?findings?\b/i, 'finding-proposal'],
+    [/^\s*(?:classify|categori[sz]e|label)\b/i, 'classify'],
+    [/^\s*extract\b/i, 'extract'],
+    [/^\s*summari[sz]e\b/i, 'summarise-given-text'],
+    [/^\s*draft\b/i, 'draft-candidate'],
+];
+
+/** The hand kind a slice names, or null; deterministic, so a nudge can only cite a kind it matched. */
+export function handKindFromPrompt(text: string): HandKind | null {
+    for (const [re, kind] of KIND_FROM_PROMPT) if (re.test(text)) return kind;
+    return null;
+}
+
+export function isHeadOnlyKind(raw: unknown): raw is HeadOnlyKind {
+    return typeof raw === 'string' && _HEAD_ONLY.has(raw);
+}

package/src/scripts/_lib/headless_invocation.ts

@@ -86,9 +86,9 @@ export const PLATFORM_TO_HOST: Readonly<Record<string, string>> = Object.freeze(
 export function resumePrompt(roadmapSlug: string): string {
     return (
         `Resume the claimed roadmap \`${roadmapSlug}\`. ` +
-        `First act: look the checkpoint up by slug (latestCheckpointFor) and verify it ` +
-        `against the worktree before acting on any of it — resume by evidence, never by ` +
-        `bookkeeping. Then run /roadmap:process-full ${roadmapSlug}.`
+        `First act: run \`agent-config run:supervise --verify ${roadmapSlug}\`, which ` +
+        `re-verifies the newest checkpoint against the worktree, before acting on any of ` +
+        `it — resume by evidence, never by bookkeeping. Then run /roadmap:process-full ${roadmapSlug}.`
     );
 }
 

package/src/scripts/_lib/host_capability.ts

@@ -67,6 +67,22 @@ export interface HostCapabilityManifest {
      * stop-loss behaviour — loudly, never silently.
      */
     worker_respawn: boolean;
+    /**
+     * A finished worker can be re-tasked by name and its next run reads more
+     * than half of its first call's input from cache — the warm-reuse path
+     * `_lib/worker_reuse.ts` decides on.
+     *
+     * Independent of `worker_respawn`: that field is mid-task kill-and-respawn,
+     * this one is a re-task at a task boundary. Neither derives the other.
+     * `false` on every host until a dated observation row sets it.
+     */
+    worker_resume: boolean;
+    /**
+     * A forked worker's first call reads the parent's prefix from cache and
+     * keeps the parent's tool pool. Read by the fork guidance in
+     * `subagent-orchestration`; `false` until observed.
+     */
+    fork_shares_cache: boolean;
     /**
      * The host exposes its own structured-ask tool — a native question picker
      * the agent can call instead of rendering a numbered-options block as prose.
@@ -122,6 +138,8 @@ const SAFE_DEFAULT: HostCapabilityManifest = {
     separate_quota_pool: false,
     agent_teams: false,
     worker_respawn: false,
+    worker_resume: false,
+    fork_shares_cache: false,
     structured_ask: false,
     reads_project_mcp_config: false,
     // `true` because the safe answer here is "there is still a step", not
@@ -155,6 +173,8 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
         separate_quota_pool: asBool(src.separate_quota_pool),
         agent_teams: asBool(src.agent_teams),
         worker_respawn: asBool(src.worker_respawn),
+        worker_resume: asBool(src.worker_resume),
+        fork_shares_cache: asBool(src.fork_shares_cache),
         structured_ask: asBool(src.structured_ask),
         reads_project_mcp_config: asBool(src.reads_project_mcp_config),
         // Inverted coercion, matching the inverted default: only an explicit
@@ -267,14 +287,24 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
  *   the archival reading implies an ACTIVE copy of the same clause would bite.
  *   It would not. NOTHING IN THIS TREE EXECUTES A `verify:` CLAUSE'S COMMAND,
  *   archived or active: `_lib/verify_clause.ts` is a parser, and its four
- *   importers — `roadmap_verify_share`, `closure_scan`, `run_continuation_hook`
+ *   importers — `roadmap_verify_share`, `closure_scan`
  *   and `check_verify_expectation_delta` — shell out to nothing but `git`. The
  *   step also scoped itself to its own merge ("returns 0 at merge"), which it
  *   did. Its stated successor was to record the first observed row with its
  *   provenance — which is what this block now is.
+ *
+ * `fork_shares_cache: true` — OBSERVED. claude (Claude Code 2.1.302, a fork
+ *   spawned from a subagent leg, 2026-10-17): the fork's first own call read
+ *   248,334 of 248,939 input tokens from cache, and its tool list was the
+ *   parent's. Artifact:
+ *   `agents/evidence/investigations/host-continuation-observations-2026-10.md`.  code-comment-allow provenance-comment -- the observation protocol makes the artifact citation part of the row
+ *
+ * `worker_resume` — absent, deliberately. The same artifact records a resumed
+ *   leg reading 99.7 % from cache, but it was addressed by the host's per-run
+ *   id rather than a durable name, which the criterion requires.
  */
 const HOST_CAPABILITY_REGISTRY: Readonly<Record<string, Partial<HostCapabilityManifest>>> = {
-    claude: { subagent_spawn: true, parallel_spawn: true, structured_ask: true },
+    claude: { subagent_spawn: true, parallel_spawn: true, structured_ask: true, fork_shares_cache: true },
 };
 
 /**
@@ -380,6 +410,8 @@ const CAPABILITY_FIELDS: readonly CapabilityField[] = [
     'separate_quota_pool',
     'agent_teams',
     'worker_respawn',
+    'worker_resume',
+    'fork_shares_cache',
     'structured_ask',
     'reads_project_mcp_config',
     'mcp_needs_manual_activation',