faberun 0.3.0 → 0.7.0

package/src/cli/skills.mjs

@@ -1,18 +1,38 @@
 /**
- * `skills` argv: list, install.
+ * `skills` argv: list, install, register.
  *
  * Per-operation options only, so `--force` is rejected by `list`. The
- * behavior lives in `installSkills`, exported because `faberun init` installs
- * the same catalogue into a target repository; this file owns the wire, the
- * same split `seat.mjs` uses.
+ * behavior lives in `installSkills` and `registerSkills`, exported because
+ * `faberun init` installs the same catalogue into a target repository and
+ * `faberun setup` registers the skill into every installed harness; this file
+ * owns the wire, the same split `seat.mjs` uses.
+ *
+ * `install` copies the catalogue into a caller-chosen `.claude/skills`.
+ * `register` discovers each installed harness's own skills directory and links
+ * (or, with `--copy`, copies) the `faberun` skill into it. Discovery is a
+ * measured table below, not a probe of live harness state.
  */
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs as parseFlags } from "node:util";
 
+import { faberunHome, installedVersionDir } from "../host/home.mjs";
+import { findExecutable } from "../host/preflight.mjs";
+import { colorLevel, statusToken } from "./brand.mjs";
+
 const SKILLS_DIR = fileURLToPath(new URL("../../skills", import.meta.url));
+const CHECKOUT_SKILL = join(SKILLS_DIR, "faberun");
 
 /** Flags are scoped to the operation that declares them; all others are rejected. */
 /** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
@@ -23,8 +43,64 @@ const OPERATION_OPTIONS = {
     global: { type: "boolean" },
     force: { type: "boolean" },
   },
+  register: {
+    harness: { type: "string" },
+    copy: { type: "boolean" },
+    force: { type: "boolean" },
+    json: { type: "boolean" },
+  },
 };
 
+/**
+ * Where each operator harness keeps the skills a user can add, measured
+ * 2026-09-16 on the machine this node ran on.
+ *
+ * - `claude` -> `~/.claude/skills` and `codex` -> `~/.codex/skills` are the
+ *   documented conventions; on this machine both directories hold symlinks into
+ *   `~/.agents/skills`.
+ * - `agents` -> `~/.agents/skills` is the shared convention. It is registered
+ *   on its own too, because a harness directory is often a symlink to it, and
+ *   it is optional so a machine without it stays quiet.
+ * - `zcode` 0.16.5: `zcode skills list` labels every local, non-plugin entry
+ *   `(user/agents)` and resolves it under `~/.agents/skills`; `~/.zcode` holds
+ *   only plugin and CLI state, so its user skill convention is the shared one.
+ * - `agy` (Antigravity CLI): the installed binary's embedded guide names
+ *   `~/.gemini/config/` as the global customization root and
+ *   `~/.gemini/config/skills/<name>/` as a global skill; the
+ *   `~/.gemini/antigravity-cli/builtin/skills` tree is shipped, read-only.
+ * - `dsh`: `dsh --help` lists no skills command and no skills directory exists,
+ *   so it has no registration target. It is kept in the table to record the
+ *   measurement, and reported as `no skill support`.
+ *
+ * @type {Record<string, {binary: string|null, optional: boolean, dir: ((home: string) => string)|null}>}
+ */
+const HARNESS_SKILL_DIRS = {
+  claude: { binary: "claude", optional: false, dir: (home) => join(home, ".claude", "skills") },
+  codex: { binary: "codex", optional: false, dir: (home) => join(home, ".codex", "skills") },
+  zcode: { binary: "zcode", optional: false, dir: (home) => join(home, ".agents", "skills") },
+  agy: { binary: "agy", optional: false, dir: (home) => join(home, ".gemini", "config", "skills") },
+  dsh: { binary: "dsh", optional: false, dir: null },
+  agents: { binary: null, optional: true, dir: (home) => join(home, ".agents", "skills") },
+};
+
+/** @typedef {(text: string) => void} Writer */
+/**
+ * @typedef {object} SkillTarget
+ * @property {string} harness
+ * @property {string|null} dir
+ * @property {string|null} binary
+ * @property {boolean} installed
+ * @property {boolean} dirExists
+ * @property {boolean} unsupported
+ * @property {boolean} optional
+ */
+/**
+ * @typedef {object} SkillRegistration
+ * @property {string} harness
+ * @property {string|null} dir
+ * @property {"linked"|"copied"|"unchanged"|"skipped"|"no_dir"|"not_installed"|"unsupported"} action
+ */
+
 /**
  * @param {string[]} args
  * @returns {void}
@@ -39,12 +115,30 @@ export function skillsCli(args) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
     return usage();
   }
-  const values = /** @type {{target?: string, global?: boolean, force?: boolean}} */ (parsed.values);
+  const values = /** @type {{target?: string, global?: boolean, force?: boolean, copy?: boolean, json?: boolean, harness?: string}} */ (parsed.values);
   if (operation === "list") {
     if (parsed.positionals.length) return usage();
     for (const name of catalog()) process.stdout.write(`${name}\n`);
     return;
   }
+  if (operation === "register") {
+    if (parsed.positionals.length) return usage();
+    try {
+      const results = registerSkills({
+        harnesses: splitHarnesses(values.harness),
+        copy: values.copy === true,
+        force: values.force === true,
+        env: process.env,
+        level: values.json === true ? 0 : colorLevel(process.env, process.stdout.isTTY),
+        stdout: values.json === true ? () => {} : (text) => process.stdout.write(text),
+      });
+      if (values.json === true) process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      return usage();
+    }
+    return;
+  }
   const skillsDir = values.global
     ? join(homedir(), ".claude", "skills")
     : join(values.target ? resolve(values.target) : process.cwd(), ".claude", "skills");
@@ -88,6 +182,212 @@ export function installSkills({ names, skillsDir, force, stdout }) {
   return { installed, skipped };
 }
 
+/**
+ * The harness skills directories that exist on this machine, in table order,
+ * deduplicated by directory. `zcode` and the shared `agents` entry name the
+ * same `~/.agents/skills`; whichever is installed first claims it. A filter of
+ * harness names limits the result and rejects a name that is not in the table.
+ *
+ * @param {{env?: NodeJS.ProcessEnv, harnesses?: string[], isInstalled?: (name: string) => boolean}} [options]
+ * @returns {SkillTarget[]}
+ */
+export function discoverSkillTargets(options = {}) {
+  const env = options.env ?? process.env;
+  const home = skillHome(env);
+  const requested = options.harnesses && options.harnesses.length ? options.harnesses : null;
+  if (requested) {
+    for (const name of requested) {
+      if (!Object.hasOwn(HARNESS_SKILL_DIRS, name)) {
+        throw new Error(`no harness named "${name}" (choose from ${Object.keys(HARNESS_SKILL_DIRS).join(", ")})`);
+      }
+    }
+  }
+  const filter = requested ? new Set(requested) : null;
+  const isInstalled = options.isInstalled ?? ((name) => findExecutable(name) !== null);
+  /** @type {SkillTarget[]} */
+  const targets = [];
+  const claimed = new Set();
+  for (const [harness, entry] of Object.entries(HARNESS_SKILL_DIRS)) {
+    if (filter && !filter.has(harness)) continue;
+    const dir = entry.dir ? entry.dir(home) : null;
+    const installed = entry.binary ? isInstalled(entry.binary) : true;
+    if (dir && claimed.has(dir)) continue;
+    if (installed && dir && !entry.optional) claimed.add(dir);
+    targets.push({
+      harness,
+      dir,
+      binary: entry.binary,
+      installed,
+      dirExists: dir !== null && existsSync(dir),
+      unsupported: dir === null,
+      optional: entry.optional,
+    });
+  }
+  return targets;
+}
+
+/**
+ * Link or copy the `faberun` skill into every installed harness's skills
+ * directory. A harness whose binary is absent is reported and skipped; one
+ * whose directory is missing is a `[warn]` unless `force` creates it. A real
+ * directory already at the destination is left alone unless `force`. The
+ * caller owns the wire and the streams; `--json` passes a no-op writer.
+ *
+ * @param {{harnesses?: string[], copy?: boolean, force?: boolean, env?: NodeJS.ProcessEnv, level?: number, stdout?: Writer, isInstalled?: (name: string) => boolean}} [options]
+ * @returns {SkillRegistration[]}
+ */
+export function registerSkills(options = {}) {
+  const env = options.env ?? process.env;
+  const home = skillHome(env);
+  const stdout = options.stdout ?? ((text) => process.stdout.write(text));
+  const level = options.level ?? 0;
+  const force = options.force === true;
+  const source = skillSource(env);
+  const targets = discoverSkillTargets({ env, harnesses: options.harnesses, isInstalled: options.isInstalled });
+  /** @type {SkillRegistration[]} */
+  const results = [];
+  for (const target of targets) {
+    if (target.unsupported || target.dir === null) {
+      results.push({ harness: target.harness, dir: null, action: "unsupported" });
+      stdout(`${statusToken("ok", level)} ${target.harness} · no skill support\n`);
+      continue;
+    }
+    const dir = target.dir;
+    const destination = join(dir, "faberun");
+    if (!target.installed) {
+      results.push({ harness: target.harness, dir: destination, action: "not_installed" });
+      stdout(`${statusToken("ok", level)} ${target.harness} · not installed\n`);
+      continue;
+    }
+    if (!target.dirExists && !force) {
+      if (target.optional) continue;
+      results.push({ harness: target.harness, dir: destination, action: "no_dir" });
+      stdout(`${statusToken("warn", level)} ${target.harness} · no skills directory (${displayPath(dir, home)})\n`);
+      continue;
+    }
+    mkdirSync(dir, { recursive: true });
+    const action = options.copy === true ? copySkill(source, destination, force) : linkSkill(source, destination, force);
+    results.push({ harness: target.harness, dir: destination, action });
+    const path = displayPath(destination, home);
+    if (action === "skipped") {
+      stdout(`${statusToken("warn", level)} ${target.harness} · ${path} · exists, use --force\n`);
+    } else {
+      stdout(`${statusToken("ok", level)} ${target.harness} · ${path} · ${action}\n`);
+    }
+  }
+  return results;
+}
+
+/**
+ * The skill tree a registration points at: `$FABERUN_HOME/current/skills/faberun`
+ * when this CLI runs from the installed home layout, so the link follows every
+ * update, and this checkout's `skills/faberun` otherwise.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string}
+ */
+function skillSource(env) {
+  const home = faberunHome(env);
+  return installedVersionDir(process.argv[1], home) ? join(home, "current", "skills", "faberun") : CHECKOUT_SKILL;
+}
+
+/**
+ * @param {string} source
+ * @param {string} destination
+ * @param {boolean} force
+ * @returns {"linked"|"unchanged"|"skipped"}
+ */
+function linkSkill(source, destination, force) {
+  const existing = lstatOrNull(destination);
+  if (existing) {
+    if (existing.isSymbolicLink() && !force && resolvesTo(destination, source)) return "unchanged";
+    if (!existing.isSymbolicLink() && !force) return "skipped";
+    rmSync(destination, { recursive: true, force: true });
+  }
+  symlinkSync(source, destination);
+  return "linked";
+}
+
+/**
+ * @param {string} source
+ * @param {string} destination
+ * @param {boolean} force
+ * @returns {"copied"|"unchanged"|"skipped"}
+ */
+function copySkill(source, destination, force) {
+  const existing = lstatOrNull(destination);
+  if (existing) {
+    if (existing.isDirectory() && !force) return "unchanged";
+    if (!force && !existing.isSymbolicLink()) return "skipped";
+    rmSync(destination, { recursive: true, force: true });
+  }
+  cpSync(source, destination, { recursive: true });
+  return "copied";
+}
+
+/**
+ * @param {string} path
+ * @returns {import("node:fs").Stats|null}
+ */
+function lstatOrNull(path) {
+  try {
+    return lstatSync(path);
+  } catch {
+    // A path that does not exist has no stats; the caller treats that as "free".
+    return null;
+  }
+}
+
+/**
+ * @param {string} destination
+ * @param {string} source
+ * @returns {boolean}
+ */
+function resolvesTo(destination, source) {
+  try {
+    return realpathSync(destination) === realpathSync(source);
+  } catch {
+    // Either path may be a dangling symlink; it cannot already point at source.
+    return false;
+  }
+}
+
+/**
+ * The home directory the skill directories hang off. `HOME` is honoured so a
+ * test or an install can point the whole discovery at a temporary tree.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string}
+ */
+function skillHome(env) {
+  const configured = env.HOME;
+  if (typeof configured === "string" && configured) return configured;
+  return homedir();
+}
+
+/**
+ * Render a path under the home directory as `~/…` for the human lines; the
+ * machine-readable `dir` stays absolute.
+ *
+ * @param {string} path
+ * @param {string} home
+ * @returns {string}
+ */
+function displayPath(path, home) {
+  const prefix = home.endsWith(sep) ? home : `${home}${sep}`;
+  if (path === home) return "~";
+  return path.startsWith(prefix) ? `~${sep}${path.slice(prefix.length)}` : path;
+}
+
+/**
+ * @param {string|undefined} text
+ * @returns {string[]}
+ */
+function splitHarnesses(text) {
+  if (typeof text !== "string" || !text) return [];
+  return [...new Set(text.split(",").map((name) => name.trim()).filter(Boolean))];
+}
+
 /**
  * @returns {string[]} catalogue entries that carry a SKILL.md
  */
@@ -100,6 +400,8 @@ function catalog() {
 
 /** @returns {void} */
 function usage() {
-  process.stderr.write("usage: faberun skills <list|install> [<name>...] [--target <dir>] [--global] [--force]\n");
+  process.stderr.write("usage: faberun skills <list|install|register> [<name>...] [--target <dir>] [--global] [--force] [--copy] [--harness <a,b>] [--json]\n");
   process.exitCode = 2;
 }
+
+export default OPERATION_OPTIONS;

package/src/cli.mjs

@@ -87,7 +87,7 @@ export function hasDetachedBootstrapNonce() {
 }
 
 /** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
-const COMMAND_OPTIONS = {
+export const COMMAND_OPTIONS = {
   run: { detach: { type: "boolean" }, "base-ref": { type: "string" } },
   resume: { detach: { type: "boolean" }, node: { type: "string" }, reconcile: { type: "string" }, answer: { type: "string" } },
   supervise: { detach: { type: "boolean" }, interval: { type: "string" } },
@@ -102,7 +102,7 @@ const COMMAND_OPTIONS = {
   "bulk-read": { question: { type: "string" }, paths: { type: "string", multiple: true }, json: { type: "boolean" } },
   next: { cwd: { type: "string" }, json: { type: "boolean" } },
   update: { check: { type: "boolean" }, json: { type: "boolean" } },
-  setup: { yes: { type: "boolean" }, harnesses: { type: "string" }, worker: { type: "string" }, judge: { type: "string" }, json: { type: "boolean" } },
+  setup: { yes: { type: "boolean" }, harnesses: { type: "string" }, worker: { type: "string" }, judge: { type: "string" }, "no-skill": { type: "boolean" }, json: { type: "boolean" } },
   init: { cwd: { type: "string" }, yes: { type: "boolean" }, "no-skill": { type: "boolean" }, agentkit: { type: "boolean" }, greenfield: { type: "boolean" }, stable: { type: "boolean" }, json: { type: "boolean" } },
   metrics: METRICS_OPTIONS,
 };
@@ -251,6 +251,7 @@ async function main(argv) {
       harnesses: typeof values.harnesses === "string" ? values.harnesses : undefined,
       worker: typeof values.worker === "string" ? values.worker : undefined,
       judge: typeof values.judge === "string" ? values.judge : undefined,
+      skill: values["no-skill"] !== true,
       json: values.json === true,
       env: process.env,
       isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),

package/src/contract/final-verification.mjs

@@ -5,8 +5,11 @@
  * `contract.finalVerification` is the contract-wide proof that the phase as a
  * whole closes: the controller runs it before the judge on the phase-terminal
  * node (the node no other node depends on), so no final checkpoint is ever
- * approved on partial verification. The persisted node-snapshot shape for
- * verification evidence lives here too, next to the schema it records.
+ * approved on partial verification. `contract.sharedVerification` carries the
+ * same command schema but is appended to every node's attempt and integration
+ * candidate, for the fast repository ratchets a node's write set can break.
+ * The persisted node-snapshot shape for verification evidence lives here too,
+ * next to the schema it records.
  */
 
 import { Buffer } from "node:buffer";
@@ -29,6 +32,32 @@ export function validateFinalVerification(value, label = "contract.finalVerifica
   return validateVerificationCommands(value, label);
 }
 
+/**
+ * Validate the optional contract-level `sharedVerification` field. It carries
+ * the identical verification-command schema as `finalVerification`; only the
+ * audience differs.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {VerificationCommand[]|undefined}
+ */
+export function validateSharedVerification(value, label = "contract.sharedVerification") {
+  if (value === undefined) return undefined;
+  return validateVerificationCommands(value, label);
+}
+
+/**
+ * The contract's `sharedVerification` commands, which every node's verification
+ * carries on both its attempt and its integration candidate. Absent means none,
+ * so a contract that declares nothing is unchanged.
+ *
+ * @param {{sharedVerification?: VerificationCommand[]}} contract
+ * @returns {VerificationCommand[]}
+ */
+export function sharedVerificationCommands(contract) {
+  return contract.sharedVerification ?? [];
+}
+
 /**
  * The contract's `finalVerification` commands when this node is the one that
  * closes the phase, otherwise none. A node is phase-terminal when no other

package/src/contract/index.mjs

@@ -4,7 +4,7 @@ import { dirname, resolve } from "node:path";
 import { loadTaskPacket, renderWorkerPrompt } from "./task-packet.mjs";
 import { RESERVED_ARTICLES } from "./articles.mjs";
 import { validateDefinitionOfDone } from "./definition-of-done.mjs";
-import { validateFinalVerification } from "./final-verification.mjs";
+import { validateFinalVerification, validateSharedVerification } from "./final-verification.mjs";
 import { VERIFICATION_LIMITS } from "./verification.mjs";
 import {
   validateCapabilityRequirements,
@@ -23,7 +23,7 @@ export { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION } from "../harnesses/index.mj
 const CONTRACT_FIELDS = new Set([
   "schemaVersion", "contractVersion", "id", "campaignId", "goal", "cwd", "sourceIdentity",
   "maxParallel", "pollIntervalMs", "stallTimeoutSec", "timeoutSec",
-  "runtimeDefaults", "runtimes", "nodes", "warnings", "finalVerification", "nodeAdvisory",
+  "runtimeDefaults", "runtimes", "nodes", "warnings", "finalVerification", "sharedVerification", "nodeAdvisory",
 ]);
 const DEFAULTS_FIELDS = new Set(["worker", "judge"]);
 const NODE_FIELDS = new Set([
@@ -39,7 +39,7 @@ const GATE_REVIEWS = new Set(["none", "advisory", "blocking"]);
 
 /** @typedef {{structuredOutput?: boolean, promptTransport?: "stdin"|"argv", sandbox?: boolean, permissions?: boolean, continuation?: boolean, tokenBudget?: boolean, costBudget?: boolean, usage?: boolean, cost?: boolean}} CapabilityRequirements */
 
-/** @typedef {{kind: string, id?: string, campaignId?: string, contractId?: string, nodeId?: string, cwd?: string, gitHead?: string|null, dirtyTreeFingerprint?: string|null, packetHashes?: Record<string, string>, harnessVersions?: Record<string, string|null>}} SourceIdentity */
+/** @typedef {{kind: string, id?: string, campaignId?: string, contractId?: string, nodeId?: string, cwd?: string, gitHead?: string|null, dirtyTreeFingerprint?: string|null, packetHashes?: Record<string, string>, harnessVersions?: Record<string, string|null>, baseRef?: string|null}} SourceIdentity */
 
 /** @typedef {{argv: string[], cwd?: string, timeoutSec?: number, repeat?: number, env?: string[]}} VerificationCommand */
 
@@ -51,7 +51,7 @@ const GATE_REVIEWS = new Set(["none", "advisory", "blocking"]);
 
 /** @typedef {{id: string, type: string, phase: string, runtime?: string, dependsOn: string[], taskPacket: TaskPacket, taskPacketFile?: string, prompt: string, definitionOfDone: import("./definition-of-done.mjs").DefinitionOfDoneItem[], gate: ValidatedGate, timeoutSec?: number, requiredCapabilities: CapabilityRequirements, packetHash: string, sourceIdentity: SourceIdentity, replayPolicy: "safe"|"reconcile"|"never"}} ValidatedNode */
 
-/** @typedef {{schemaVersion: number, contractVersion: string, id: string, campaignId: string, goal: string, cwd: string, sourceIdentity: SourceIdentity, runtimes: Record<string, ValidatedRuntime>, runtimeDefaults: {worker?: string, judge?: string}, nodes: ValidatedNode[], maxParallel: number, pollIntervalMs: number, stallTimeoutSec: number, timeoutSec: number, finalVerification?: VerificationCommand[], nodeAdvisory?: NodeAdvisoryPolicy, warnings: string[]}} ValidatedContract */
+/** @typedef {{schemaVersion: number, contractVersion: string, id: string, campaignId: string, goal: string, cwd: string, sourceIdentity: SourceIdentity, runtimes: Record<string, ValidatedRuntime>, runtimeDefaults: {worker?: string, judge?: string}, nodes: ValidatedNode[], maxParallel: number, pollIntervalMs: number, stallTimeoutSec: number, timeoutSec: number, finalVerification?: VerificationCommand[], sharedVerification?: VerificationCommand[], nodeAdvisory?: NodeAdvisoryPolicy, warnings: string[]}} ValidatedContract */
 /** @typedef {{costUsd?: number, durationSec?: number}} NodeAdvisoryPolicy */
 
 /** @typedef {"pending"|"running"|"done"|"no-op"|"blocked"|"failed"|"exhausted"|"stalled"|"canceled"} NodeStatus */
@@ -79,7 +79,7 @@ const GATE_REVIEWS = new Set(["none", "advisory", "blocking"]);
 /** @typedef {{history: RoutingHistoryEntry[], currentOverride: RoutingOverride|null, assignments?: RuntimeAssignments, availability?: Record<string, RuntimeAvailability>, tierExhaustion?: TierExhaustion, tierExhaustionCycle?: number}} RoutingState */
 /** @typedef {{revision?: number, heartbeatCount: number, dryHeartbeatCount: number, progressSignature?: string|null, lastHeartbeatAt: string|null, lastProgressAt: string|null, nextCheckAt?: string|null}} ProgressState */
 /** @typedef {{status: "unassigned"|"provisioning"|"ready"|"failed"|"removed", path: string|null, branch: string|null, commit: string|null, baseSha?: string|null, sealedSha?: string|null, sealError?: string|null, previousAttempt?: number|null}} WorktreeState */
-/** @typedef {{schemaVersion: number, contractVersion: string, id: string, type: string, sourceIdentity: SourceIdentity, packetHash: string, status: NodeStatus, phase: NodePhase, attempt: number, revisions: number, judgeFailures?: number, review?: ("none"|"advisory"|"blocking"), runtime: RuntimeSnapshot|null, blockedBy: string[], startedAt: string|null, updatedAt: string, result: unknown, gate: GateResult|null, error: SnapshotError|null, usage?: Usage, costUsd?: number, routing?: RoutingState|null, progress?: ProgressState|null, worktree?: WorktreeState|null, integratedHead?: string|null, invocations?: Invocation[], executionOverrides?: ExecutionOverride[], verification?: VerificationState|null, scope?: BoundedScope|null, scopeFindings?: ScopeFindings|null, previousAttempt?: string, sessionPolicy?: {forceFresh?: boolean}|null}} NodeSnapshot */
+/** @typedef {{schemaVersion: number, contractVersion: string, id: string, type: string, sourceIdentity: SourceIdentity, packetHash: string, status: NodeStatus, phase: NodePhase, attempt: number, revisions: number, judgeFailures?: number, review?: ("none"|"advisory"|"blocking"), runtime: RuntimeSnapshot|null, blockedBy: string[], startedAt: string|null, updatedAt: string, result: unknown, gate: GateResult|null, error: SnapshotError|null, usage?: Usage, costUsd?: number, routing?: RoutingState|null, progress?: ProgressState|null, worktree?: WorktreeState|null, integratedHead?: string|null, invocations?: Invocation[], executionOverrides?: ExecutionOverride[], verification?: VerificationState|null, scope?: BoundedScope|null, scopeFindings?: ScopeFindings|null, previousAttempt?: string, sessionPolicy?: {forceFresh?: boolean}|null, declaredReadBytes?: number|null}} NodeSnapshot */
 /** @typedef {{path: string, sha: string}} ControllerIdentity */
 /** @typedef {{schemaVersion: number, contractVersion: string, pid: number, processStartToken: string|null, startedAt: string, sourceIdentity: SourceIdentity, controllerIdentity?: ControllerIdentity, integrationRef?: string, identityWarnings?: string[], relaunchCount?: number, lastRelaunchProgressAt?: string|null, attention?: {code: string, message: string, at: string}|null, contractDigest?: string, scopeDecision?: ScopeDecision, autoRetries?: Record<string, {code: string, at: string}>}} RunMetadata */
 /** @typedef {{at: string, base: string|null, dirtyTreeFingerprint: string|null}} ScopeDecision */
@@ -147,7 +147,7 @@ export function validateContract(raw, contractPath, options = {}) {
   }
   const rawNodes = /** @type {JsonObject[]} */ (raw.nodes);
   const ids = new Set();
-  /** @type {{path: string, label: string}[][]} */
+  /** @type {{path: string, label: string, kind: "read"|"acknowledged"}[][]} */
   const deferredReadsByNode = [];
   const nodes = rawNodes.map((node, index) => {
     assertObject(node, `nodes[${index}]`);
@@ -165,12 +165,12 @@ export function validateContract(raw, contractPath, options = {}) {
     if (!Array.isArray(dependsOn) || dependsOn.some((id) => typeof id !== "string")) {
       throw new TypeError(`nodes[${index}].dependsOn must be an array of ids`);
     }
-    // A readFiles entry that names a file no dependency has produced yet is a
-    // missing read today, but the graph is not known until every node is
-    // loaded. Collect the candidate here; the second pass below resolves each
-    // against the node's transitive closure once all packets and dependsOn
-    // edges are in hand.
-    /** @type {{path: string, label: string}[]} */
+    // A readFiles -- or scopeAcknowledged -- entry that names a file no
+    // dependency has produced yet is a missing path today, but the graph is not
+    // known until every node is loaded. Collect the candidate here; the second
+    // pass below resolves each against the node's transitive closure once all
+    // packets and dependsOn edges are in hand.
+    /** @type {{path: string, label: string, kind: "read"|"acknowledged"}[]} */
     const deferredReads = [];
     const taskPacket = loadTaskPacket(node, contractDir, cwd, index, { deferMissingReads: true, deferredReads, persisted });
     deferredReadsByNode.push(deferredReads);
@@ -234,21 +234,22 @@ export function validateContract(raw, contractPath, options = {}) {
   }
   assertAcyclic(nodes);
 
-  // Second pass: a readFiles entry deferred at packet load is accepted only
-  // when some transitive dependency produces it -- declares the identical path
-  // in its writeFiles, or the path sits under a dependency's directory-shaped
-  // writeRoots entry (a file-shaped entry authorizes exactly that path). Every
-  // other caller of validateTaskPacket keeps rejecting the missing read inline;
-  // this graph-aware deferral is a contract-loading capability only. Persisted
-  // loads never defer -- they skipped the existence probe, so there is nothing
-  // to resolve and nothing to stat.
+  // Second pass: a readFiles or scopeAcknowledged entry deferred at packet
+  // load is accepted only when some transitive dependency produces it --
+  // declares the identical path in its writeFiles, or the path sits under a
+  // dependency's directory-shaped writeRoots entry (a file-shaped entry
+  // authorizes exactly that path). Every other caller of validateTaskPacket
+  // keeps rejecting the missing path inline; this graph-aware deferral is a
+  // contract-loading capability only. Persisted loads never defer -- they
+  // skipped the existence probe, so there is nothing to resolve and nothing to
+  // stat.
   if (!persisted) {
     for (const [index, node] of nodes.entries()) {
       const deferredReads = deferredReadsByNode[index];
       if (deferredReads.length === 0) continue;
       const closure = transitiveDependencyClosure(node, nodes);
       for (const { path, label } of deferredReads) {
-        if (!dependencyCoversRead(closure, path, cwd)) {
+        if (!dependencyCoversPath(closure, path, cwd)) {
           throw new TypeError(`${label} does not exist: ${path}`);
         }
       }
@@ -351,13 +352,15 @@ export function validateContract(raw, contractPath, options = {}) {
     stallTimeoutSec: positiveNumber(raw.stallTimeoutSec ?? 300, "contract.stallTimeoutSec"),
     timeoutSec: positiveNumber(raw.timeoutSec ?? 2_400, "contract.timeoutSec"),
     finalVerification: validateFinalVerification(raw.finalVerification, "contract.finalVerification"),
+    sharedVerification: validateSharedVerification(raw.sharedVerification, "contract.sharedVerification"),
     nodeAdvisory: validateNodeAdvisory(raw.nodeAdvisory),
     warnings,
   });
   // The persisted load is a replay, not a re-authoring: it accepts only bytes
   // whose digest matches the decision frozen at launch. A changed DAG, gate,
-  // runtime selection, timeout, definition of done or finalVerification leaves
-  // every packetHash untouched, so only this digest refuses it.
+  // runtime selection, timeout, definition of done, finalVerification or
+  // sharedVerification leaves every packetHash untouched, so only this digest
+  // refuses it.
   if (persisted && options.contractDigest !== undefined && contractDigest(raw) !== options.contractDigest) {
     throw new TypeError("persisted contract does not match the contractDigest recorded at run creation; the stored contract was modified after the run was created");
   }
@@ -593,7 +596,7 @@ function transitiveDependencyClosure(node, nodes) {
 }
 
 /**
- * Whether a transitive dependency produces the deferred read: it declares the
+ * Whether a transitive dependency produces the deferred path: it declares the
  * identical path in `writeFiles`, or the path sits under a directory-shaped
  * `writeRoots` entry. A `writeRoots` entry that names an existing regular file
  * authorizes exactly that path and nothing beneath it, mirroring the
@@ -604,7 +607,7 @@ function transitiveDependencyClosure(node, nodes) {
  * @param {string} cwd
  * @returns {boolean}
  */
-function dependencyCoversRead(closure, path, cwd) {
+function dependencyCoversPath(closure, path, cwd) {
   for (const dependency of closure) {
     const packet = dependency.taskPacket;
     if ((packet.writeFiles ?? []).includes(path)) return true;

package/src/contract/runtime.mjs

@@ -41,7 +41,7 @@ const PRICING_FIELDS = new Set(["inputPerMTok", "cachedInputPerMTok", "outputPer
 const SNAPSHOT_RUNTIME_FIELDS = new Set(["id", ...RUNTIME_FIELDS, "capabilities"]);
 const CAPABILITY_FIELDS = new Set([
   "structuredOutput", "promptTransport", "sandbox", "permissions", "continuation", "tokenBudget", "costBudget",
-  "usage", "cost", "toolPolicy", "streamsOutput", "maxArgvPromptBytes",
+  "usage", "cost", "toolPolicy", "streamsOutput", "signalsProcesses", "maxArgvPromptBytes",
 ]);
 /** @typedef {{id: string, type?: string, runtime?: string, gate: {runtime?: string}, status?: NodeStatus, errorCode?: string, currentRuntime?: string}} RoutableNode */
 /** @typedef {{status?: NodeStatus, errorCode?: string, currentRuntime?: string, assignment?: string, availability?: Record<string, RuntimeAvailability>}} RoutingEvent */
@@ -187,6 +187,10 @@ export function validateCapabilities(value, label) {
   for (const name of ["structuredOutput", "sandbox", "permissions", "continuation", "tokenBudget", "costBudget", "usage", "cost", "toolPolicy", "streamsOutput"]) {
     if (typeof value[name] !== "boolean") throw new TypeError(`${label}.${name} must be boolean`);
   }
+  // `signalsProcesses` is tri-state: null is a sandbox nobody has measured.
+  if (value.signalsProcesses !== null && typeof value.signalsProcesses !== "boolean") {
+    throw new TypeError(`${label}.signalsProcesses must be boolean or null`);
+  }
   if (!["stdin", "argv"].includes(/** @type {string} */ (value.promptTransport))) {
     throw new TypeError(`${label}.promptTransport is invalid`);
   }

package/src/contract/snapshot.mjs

@@ -129,7 +129,7 @@ export function validateNodeSnapshot(value, expectedNode = null) {
     "schemaVersion", "contractVersion", "id", "type", "sourceIdentity", "packetHash", "status", "phase",
     "attempt", "revisions", "judgeFailures", "runtime", "blockedBy", "startedAt", "updatedAt", "result", "gate", "error", "usage",
     "costUsd", "routing", "progress", "worktree", "invocations", "executionOverrides", "verification", "scope",
-    "scopeFindings", "review", "previousAttempt", "sessionPolicy", "integratedHead",
+    "scopeFindings", "review", "previousAttempt", "sessionPolicy", "integratedHead", "declaredReadBytes",
   ]), "node snapshot");
   validateMetadata(value, "node snapshot");
   requireId(value.id, "node snapshot.id");
@@ -166,6 +166,12 @@ export function validateNodeSnapshot(value, expectedNode = null) {
   validateSnapshotError(value.error, "node snapshot.error");
   if (value.usage !== undefined) validateUsage(value.usage, "node snapshot.usage");
   if (value.costUsd !== undefined) nonNegativeNumber(value.costUsd, "node snapshot.costUsd");
+  // The summed byte size of the node's declared readFiles in the attempt
+  // worktree at dispatch time -- the one quantity the controller can measure
+  // about a packet's reference load, since the worker reads the files itself.
+  if (value.declaredReadBytes !== undefined && value.declaredReadBytes !== null) {
+    nonNegativeInteger(value.declaredReadBytes, "node snapshot.declaredReadBytes");
+  }
   if (value.routing !== undefined && value.routing !== null) validateRoutingState(value.routing, "node snapshot.routing");
   if (value.progress !== undefined && value.progress !== null) validateProgressState(value.progress, "node snapshot.progress");
   if (value.worktree !== undefined && value.worktree !== null) validateWorktreeState(value.worktree, "node snapshot.worktree");