@staix/agent-hub 0.18.0 → 0.20.0

package/src/hub/check-runner.ts

@@ -53,8 +53,10 @@ interface RunnerTransport {
   kind: "remote"; image: string; platform: string;
   probe(command: ContainerCommand, cleanup: ContainerCommand): Promise<RunnerState>;
   isolate(command: ContainerCommand): Promise<void>;
-  runArgs(receipt: RunReceipt, labels: string[]): string[];
+  runArgs(receipt: RunReceipt, labels: string[], volume?: string): string[];
   copy(command: ContainerCommand, source: string, container: string, signal: AbortSignal): Promise<void>;
+  /** Remote only: bring the lockfile-keyed dependency volume to a verified prepared state and return its name. */
+  prepareDeps?(command: ContainerCommand, receipt: RunReceipt, source: string, signal: AbortSignal, labels: string[]): Promise<string>;
   execArgs(container: string, words: readonly string[]): string[];
   cleanup(command: ContainerCommand, name: string): Promise<boolean>;
   listArgs: string[];
@@ -111,6 +113,7 @@ function runContainer(executable: string, args: string[], options: { signal?: Ab
 export class ContainerRunner {
   private readonly command: ContainerCommand;
   private readonly entries = new Map<string, Entry>();
+  private readonly saves = new Map<string, Promise<void>>();
   private readonly queue: Entry[] = [];
   private active?: Entry;
   private closing = false;
@@ -233,11 +236,25 @@ export class ContainerRunner {
     await this.save(receipt);
     if (entry === this.active && entry) await this.cleanup(receipt.container);
   }
-  private async save(receipt: RunReceipt): Promise<void> {
+  /**
+   * Saves of one run's receipt go one at a time, in the order they were asked for, and each turn serializes the receipt when it runs, not when it was asked (#867): the run's own
+   * completion path and `markStale` save the same receipt concurrently, and an earlier snapshot written last must not undo a stale mark. Each write has its own temp name, so two
+   * writers never share one, and a failed write or rename removes its temp. A failed save rejects only its own caller; the next turn still runs.
+   */
+  private save(receipt: RunReceipt): Promise<void> {
+    const run = receipt.run;
+    const turn = (this.saves.get(run) ?? Promise.resolve()).then(() => this.write(receipt));
+    const tail = turn.catch(() => {});
+    this.saves.set(run, tail);
+    void tail.then(() => { if (this.saves.get(run) === tail) this.saves.delete(run); });
+    return turn;
+  }
+  private async write(receipt: RunReceipt): Promise<void> {
     await mkdir(this.records, { recursive: true, mode: 0o700 });
     const path = join(this.records, `${receipt.run}.json`);
-    const temp = `${path}.${process.pid}.tmp`;
-    await writeFile(temp, JSON.stringify(receipt), { mode: 0o600 }); await rename(temp, path);
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try { await writeFile(temp, JSON.stringify(receipt), { mode: 0o600 }); await rename(temp, path); }
+    catch (error) { await rm(temp, { force: true }).catch(() => {}); throw error; }
   }
   private async drain(): Promise<void> {
     if (this.active) return;
@@ -409,7 +426,10 @@ export class ContainerRunner {
       attemptedContainer = true;
       // Cold VM startup and a <=1.5 GiB source/dependency transfer need their own bounded allowances.
       const labels = ["--label", `agenthub.project=${this.options.projectKey}`, "--label", `agenthub.hub=${process.pid}:${this.signature}`, "--label", `agenthub.run=${r.run}`];
-      const run = await command(this.transport?.runArgs(r, labels) ?? ["run", "--detach", "--rm", "--name", r.container, ...labels, "--network", NETWORK, "--no-dns", "--cpus", "2", "--memory", "4g", "--workdir", "/work", CHECK_IMAGE, "sleep", "600"], 120_000);
+      // Preparation and verification containers reuse this run's name and labels, so cancel, timeout, shutdown, cleanup
+      // confirmation and the orphan sweep need no second ownership path. Each one is confirmed gone before the check starts.
+      const volume = await this.transport?.prepareDeps?.(transportCommand, r, src, entry.abort.signal, labels); this.ensureCurrent(entry);
+      const run = await command(this.transport?.runArgs(r, labels, volume) ?? ["run", "--detach", "--rm", "--name", r.container, ...labels, "--network", NETWORK, "--no-dns", "--cpus", "2", "--memory", "4g", "--workdir", "/work", CHECK_IMAGE, "sleep", "600"], 120_000);
       this.ensureCurrent(entry);
       if (run.code !== 0) { if (this.transport) throw new RemoteTransportError(); throw new Error("runner unavailable: container start failed"); }
       if (this.transport) await this.transport.copy(transportCommand, src, r.container, entry.abort.signal);
@@ -631,8 +651,50 @@ function runRemoteDocker(executable: string, remote: RemoteRunnerConfig, args: s
     });
   });
 }
+const DEPENDENCY_PREFIX = "agenthub-check-deps-";
+const DEPS_PROJECT = "agenthub.deps.project", DEPS_KEY = "agenthub.deps.key";
+/** Newest dependency volumes kept per project, the current one included; older ones are pruned. */
+export const KEEP_DEPENDENCY_VOLUMES = 3;
+/** Content key of a dependency volume: the commit's lockfile hash, Bun version, image architecture and image digest. */
+export function dependencyKey(parts: { lockfile: string; manifest: string; bun: string; arch: string; image: string }): string {
+  return createHash("sha256").update(["agenthub-deps-v2", parts.lockfile, parts.manifest, parts.bun, parts.arch, parts.image].join("\n")).digest("hex");
+}
+/** Files besides bun.lock that decide what `bun install --frozen-lockfile` produces: manifests, Bun and registry config, patches. */
+const INSTALL_INPUT = /(?:^|\/)(?:package\.json|bunfig\.toml|\.npmrc)$|^patches\//;
+/** Scripts bun runs during the root or a workspace install. They can read tracked source, so no manifest hash can bind their output. */
+const INSTALL_LIFECYCLE = ["preinstall", "install", "postinstall", "prepublish", "preprepare", "prepare", "postprepare"];
+/** Hash of every install-affecting file in the staged source, by path and content, so a changed manifest or config never reuses a volume. */
+export async function dependencyManifest(source: string): Promise<string> {
+  const files: string[] = [];
+  const walk = async (dir: string, prefix: string): Promise<void> => {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) { if (entry.name !== "node_modules" && entry.name !== ".git") await walk(join(dir, entry.name), path); }
+      else if (entry.isFile() && INSTALL_INPUT.test(path)) files.push(path);
+      if (files.length > 10_000) throw new Error("install inputs exceed file limit");
+    }
+  };
+  await walk(source, "");
+  const digest = createHash("sha256");
+  for (const path of files.sort()) {
+    const data = await readFile(join(source, path));
+    if (path.endsWith("package.json")) {
+      // A lifecycle script makes node_modules depend on source outside the key. Refuse it rather than reuse a stale volume or
+      // key on the whole tree; the install stays exactly `bun install --frozen-lockfile`, never `--ignore-scripts`.
+      let manifest: unknown;
+      try { manifest = JSON.parse(data.toString("utf8")); } catch { throw new RemoteDependencyError(); }
+      const scripts = manifest && typeof manifest === "object" ? (manifest as { scripts?: unknown }).scripts : undefined;
+      if (scripts !== undefined && (!scripts || typeof scripts !== "object" || Array.isArray(scripts) || INSTALL_LIFECYCLE.some(name => Object.hasOwn(scripts, name)))) throw new RemoteDependencyError();
+    }
+    digest.update(`${path}\0${hash(data)}\0`);
+  }
+  return digest.digest("hex");
+}
+export function dependencyVolume(projectKey: string, key: string): string { return `${DEPENDENCY_PREFIX}${projectKey}-${key.slice(0, 32)}`; }
 /** Distinguish transport failures from deterministic request/snapshot refusals without leaking remote stderr. */
 class RemoteTransportError extends Error { constructor() { super("remote runner unavailable"); } }
+/** The prepared dependency volume could not be proven; a fixed reason, never remote output. */
+class RemoteDependencyError extends Error { constructor() { super("remote dependencies unavailable"); } }
 
 /** Same production strategy for transport-only component/native checks; production uses RemoteRunner's dependency gate. */
 export function remoteRunnerTransport(options: RunnerOptions): RunnerTransport {
@@ -677,6 +739,12 @@ export function remoteRunnerTransport(options: RunnerOptions): RunnerTransport {
     } catch { return false; }
   };
   const hardening = ["--pull", "never", "--network", "none", "--user", "65532:65532", "--read-only", "--tmpfs", "/tmp:rw,nosuid,nodev,size=64m,mode=1777", "--tmpfs", "/home/check:rw,nosuid,nodev,size=16m,uid=65532,gid=65532", "--tmpfs", "/work:rw,nosuid,nodev,size=512m,mode=0755,uid=65532,gid=65532", "--env", "HOME=/home/check", "--env", "TMPDIR=/tmp", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--pids-limit", "64", "--cpus", "4", "--memory", "4g"];
+  // Network is "none" for every run except the single dependency-preparation container.
+  const hardenedFor = (network: "none" | "bridge") => { const args = [...hardening]; args[args.indexOf("--network") + 1] = network; return args; };
+  const mount = (volume: string, readonly: boolean) => ["--mount", `type=volume,src=${volume},dst=/work/node_modules${readonly ? ",readonly" : ""}`];
+  const readyFile = "/work/node_modules/.agenthub-deps-ready";
+  // Observed by the readiness probe: the Bun version and architecture the image actually runs.
+  let observed: { bun: string; arch: string } | undefined;
   const execArgs = (container: string, words: readonly string[]) => ["exec", "--user", "65532:65532", "--workdir", "/work", container, ...words];
   const copy = async (command: ContainerCommand, source: string, container: string, signal: AbortSignal) => {
     try {
@@ -714,10 +782,11 @@ export function remoteRunnerTransport(options: RunnerOptions): RunnerTransport {
           const launched = await command(["run", "--detach", "--rm", "--name", name, "--label", `agenthub.project=${options.projectKey}`, "--label", `agenthub.probe=${probeId}`, ...hardening, remote.image, "sleep", "600"]);
           if (launched.code !== 0) throw new RemoteTransportError();
           await copy(command, source, name, new AbortController().signal);
-          const result = await command(execArgs(name, ["bun", "-e", 'const {networkInterfaces}=await import("node:os"); if(process.getuid?.()!==65532||Object.keys(networkInterfaces()).some(name=>name!=="lo")||await Bun.file("/work/source-proof").text()!=="AHUB_REMOTE_SOURCE")process.exit(2); await Bun.write("/tmp/ready","ok"); try{await Bun.write("/root-write-proof","no");process.exit(3)}catch{} console.log(JSON.stringify({marker:"AHUB_REMOTE_READY",arch:process.arch,platform:process.platform}));']));
-          const observed = result.code === 0 ? JSON.parse(result.stdout) as { marker?: string; arch?: string; platform?: string } : undefined;
-          architecture = observed?.arch === "x64" ? "amd64" : observed?.arch;
-          if (observed?.marker !== "AHUB_REMOTE_READY" || observed.platform !== "linux" || architecture !== metadata.arch) throw new RemoteTransportError();
+          const result = await command(execArgs(name, ["bun", "-e", 'const {networkInterfaces}=await import("node:os"); if(process.getuid?.()!==65532||Object.keys(networkInterfaces()).some(name=>name!=="lo")||await Bun.file("/work/source-proof").text()!=="AHUB_REMOTE_SOURCE")process.exit(2); await Bun.write("/tmp/ready","ok"); try{await Bun.write("/root-write-proof","no");process.exit(3)}catch{} console.log(JSON.stringify({marker:"AHUB_REMOTE_READY",arch:process.arch,platform:process.platform,bun:Bun.version}));']));
+          const proof = result.code === 0 ? JSON.parse(result.stdout) as { marker?: string; arch?: string; platform?: string; bun?: string } : undefined;
+          architecture = proof?.arch === "x64" ? "amd64" : proof?.arch;
+          if (proof?.marker !== "AHUB_REMOTE_READY" || proof.platform !== "linux" || architecture !== metadata.arch || !/^\d+\.\d+\.\d+$/.test(proof.bun ?? "")) throw new RemoteTransportError();
+          observed = { bun: proof.bun!, arch: architecture! };
         } finally { clean = await cleanup(teardown, name); }
         if (!clean) throw new RemoteTransportError();
         return { available: true, platform: `linux/${architecture} (remote docker ${server.Version!.match(/^\d+\.\d+\.\d+/)![0]})` };
@@ -725,20 +794,81 @@ export function remoteRunnerTransport(options: RunnerOptions): RunnerTransport {
       finally { if (probeRoot) await rm(probeRoot, { recursive: true, force: true }).catch(() => {}); }
     },
     async isolate() { /* Fixed --network none needs no mutable host network. */ },
-    runArgs(receipt, labels) {
-      // ponytail: root and prepared dependency readiness remain reserved until 793b; no host path is used.
-      return ["run", "--detach", "--rm", "--name", receipt.container, ...labels, ...hardening,
-        "--mount", `type=volume,src=agenthub-check-deps-unprepared-${options.projectKey},dst=/work/node_modules,readonly`, "--workdir", "/work", remote.image, "sleep", "600"];
+    runArgs(receipt, labels, volume) {
+      // A check never runs without a verified prepared volume, and only ever mounts it read-only; no host path is used.
+      if (!volume) throw new RemoteDependencyError();
+      return ["run", "--detach", "--rm", "--name", receipt.container, ...labels, ...hardenedFor("none"), ...mount(volume, true), "--workdir", "/work", remote.image, "sleep", "600"];
+    },
+    async prepareDeps(command, receipt, source, signal, labels) {
+      if (!observed) throw new RemoteTransportError();
+      const key = dependencyKey({ lockfile: receipt.lockfile, manifest: await dependencyManifest(source), bun: observed.bun, arch: observed.arch, image: digest });
+      const volume = dependencyVolume(options.projectKey, key), name = receipt.container;
+      const ok = (result: CommandResult) => { if (result.code === 255 || result.code === 125) throw new RemoteTransportError(); if (result.code !== 0) throw new RemoteDependencyError(); return result; };
+      // Every step container carries this run's name and labels, so it is confirmed gone before the next one starts.
+      const gone = async () => { if (!await cleanup(command, name)) throw new RemoteTransportError(); };
+      const owner = async (): Promise<"missing" | "ours" | "foreign"> => {
+        const result = await command(["volume", "inspect", volume, "--format", `{"project":{{json (index .Labels "${DEPS_PROJECT}")}},"key":{{json (index .Labels "${DEPS_KEY}")}}}`]);
+        if (result.code === 255) throw new RemoteTransportError();
+        if (result.code !== 0) return "missing";
+        try { const labelled = JSON.parse(result.stdout) as { project?: unknown; key?: unknown }; return labelled.project === options.projectKey && labelled.key === key ? "ours" : "foreign"; } catch { return "foreign"; }
+      };
+      const marker = `await Bun.file(${JSON.stringify(readyFile)})`;
+      const verify = async (): Promise<boolean> => {
+        // Network none, volume read-only: proves the marker for this exact key and that the mount cannot be written.
+        const script = `const t=await ${marker}.text().catch(()=>"");if(t!==${JSON.stringify(key)})process.exit(2);try{await Bun.write(${JSON.stringify(readyFile)},"x");process.exit(3)}catch{}`;
+        const result = await command(["run", "--rm", "--name", name, ...labels, ...hardenedFor("none"), ...mount(volume, true), "--workdir", "/work", remote.image, "bun", "-e", script], { timeoutMs: 60_000 });
+        if (result.code === 255) throw new RemoteTransportError();
+        await gone();
+        return result.code === 0;
+      };
+      const prune = async () => {
+        // Bounded rule: keep the newest few of this project's own prepared volumes, always the current one; nothing else is touched.
+        const listed = await command(["volume", "ls", "--quiet", "--filter", `label=${DEPS_PROJECT}=${options.projectKey}`]);
+        if (listed.code !== 0) return;
+        const own = new RegExp(`^${DEPENDENCY_PREFIX}${options.projectKey}-[a-f0-9]{32}$`);
+        const names = listed.stdout.split("\n").map(line => line.trim()).filter(line => own.test(line));
+        if (names.length <= KEEP_DEPENDENCY_VOLUMES || names.length > 500) return;
+        const rows = await command(["volume", "inspect", ...names, "--format", `{"name":{{json .Name}},"created":{{json .CreatedAt}},"project":{{json (index .Labels "${DEPS_PROJECT}")}},"key":{{json (index .Labels "${DEPS_KEY}")}}}`]);
+        if (rows.code !== 0) return;
+        // Only a volume this runner demonstrably made is a candidate: exact name pattern, our project label and a key label that matches
+        // the name. A volume with an absent or inconsistent key label is someone else's or damaged: it is neither counted nor removed.
+        const volumes = rows.stdout.trim().split("\n").flatMap(line => { try { return [JSON.parse(line) as { name?: unknown; created?: unknown; project?: unknown; key?: unknown }]; } catch { return []; } })
+          .filter((row): row is { name: string; created: string; project: string; key: string } => typeof row.name === "string" && own.test(row.name) && row.project === options.projectKey && typeof row.created === "string"
+            && typeof row.key === "string" && /^[a-f0-9]{64}$/.test(row.key) && row.name === dependencyVolume(options.projectKey, row.key))
+          .sort((a, b) => Date.parse(b.created) - Date.parse(a.created) || a.name.localeCompare(b.name));
+        const keep = new Set([volume, ...volumes.filter(row => row.name !== volume).slice(0, KEEP_DEPENDENCY_VOLUMES - 1).map(row => row.name)]);
+        for (const row of volumes) if (!keep.has(row.name)) await command(["volume", "rm", row.name]).catch(() => {});
+      };
+      let state = await owner();
+      if (state === "ours" && await verify()) { await prune(); return volume; }
+      if (state === "ours") ok(await command(["volume", "rm", volume])); // Half-prepared or tampered: discard, never repair in place.
+      if (state === "foreign") throw new RemoteDependencyError();
+      try {
+        ok(await command(["volume", "create", "--label", `${DEPS_PROJECT}=${options.projectKey}`, "--label", `${DEPS_KEY}=${key}`, volume]));
+        if (await owner() !== "ours") throw new RemoteDependencyError();
+        // The one step with a network. Same hardening as a check apart from that, the volume writable and a cache inside the work tmpfs.
+        ok(await command(["run", "--rm", "--name", name, ...labels, "--pull", "never", "--network", "none", "--user", "0:0", "--read-only", "--cap-drop", "ALL", "--cap-add", "CHOWN", "--security-opt", "no-new-privileges", "--pids-limit", "16", "--memory", "256m", "--mount", `type=volume,src=${volume},dst=/deps`, remote.image, "chown", "65532:65532", "/deps"], { timeoutMs: 60_000 }));
+        await gone();
+        ok(await command(["run", "--detach", "--rm", "--name", name, ...labels, ...hardenedFor("bridge"), "--env", "BUN_INSTALL_CACHE_DIR=/work/.bun-cache", ...mount(volume, false), "--workdir", "/work", remote.image, "sleep", "600"], { timeoutMs: 120_000 }));
+        await copy(command, source, name, signal);
+        ok(await command(execArgs(name, ["bun", "install", "--frozen-lockfile"]), { timeoutMs: 300_000 }));
+        ok(await command(execArgs(name, ["bun", "-e", `await Bun.write(${JSON.stringify(readyFile)},${JSON.stringify(key)})`]), { timeoutMs: 60_000 }));
+        await gone();
+        if (!await verify()) throw new RemoteDependencyError();
+      } catch (error) {
+        // A failed preparation never leaves a candidate behind; the next run would discard it anyway, because only a verified marker admits a volume.
+        await cleanup(command, name).catch(() => false);
+        await command(["volume", "rm", volume]).catch(() => {});
+        throw error;
+      }
+      await prune();
+      return volume;
     },
   };
 }
-/** Same lifecycle, but no production checks capability until 793b proves prepared dependencies. */
+/** Same lifecycle; each run first proves or prepares its lockfile-keyed read-only dependency volume (#793b). */
 export class RemoteRunner extends ContainerRunner {
   constructor(options: RunnerOptions) {
     super(options, remoteRunnerTransport(options));
   }
-  override async available(signal?: AbortSignal): Promise<RunnerState> {
-    const transport = await super.available(signal);
-    return transport.available ? { ...transport, available: false, reason: "remote dependencies unprepared" } : transport;
-  }
 }

package/src/hub/ci-watch.ts

@@ -0,0 +1,140 @@
+import { parsePrEvidence, type SdlcGh } from "./sdlc.ts";
+
+/**
+ * #785 P1b: one bounded watcher per exact PR head. It starts when `hub_task_done` names a head whose CI was not green,
+ * ends on the first CI result or on this deadline, and is cancelled by a newer head or any task move. It is a timer in the
+ * hub, never a peer turn, and its gh reads (one `gh pr view` per poll) are the only periodic gh calls the hub makes.
+ * The longest hosted run is about 30 minutes (the job limits in `.github/workflows/check.yml` are 35 and 40 minutes).
+ */
+export const CI_WATCH_DEADLINE_MS = 45 * 60_000;
+export const CI_WATCH_POLL_MS = 60_000;
+/** Same default set as `readReviewReadiness`, which is the authoritative read the review admission makes. */
+const DEFAULT_CHECKS = ["check (ubuntu-latest)", "check (macos-latest)", "seeded guards"];
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/** How many finished heads are remembered, so one head never notifies twice. */
+const SETTLED_CAP = 256;
+
+/** What one poll found. `incomplete` is every required check finished with none failed and not all passed (skipped, neutral, duplicated). */
+export type CiPoll = "pending" | "passed" | "failed" | "incomplete" | "superseded" | "closed";
+export type CiOutcome = "passed" | "failed" | "incomplete" | "deadline";
+
+export interface CiWatch { id: number; head: string; repo: string; pr: number; deadlineAt: number }
+
+/** One read of the PR: the head, its state and the required checks of that head. A failed or unreadable read is `pending`; the deadline bounds the retries. */
+export async function pollCi(target: { repo: string; pr: number }, head: string, required: readonly string[], run: SdlcGh): Promise<CiPoll> {
+  if (!REPO.test(target.repo) || !Number.isSafeInteger(target.pr) || target.pr < 1) return "closed";
+  try {
+    const view = await run(["pr", "view", String(target.pr), "--repo", target.repo, "--json", "headRefOid,state,statusCheckRollup"], 10_000, undefined, 512 * 1024);
+    if (view.code !== 0) return "pending";
+    const body = JSON.parse(view.stdout);
+    if (body?.headRefOid !== head) return "superseded";
+    if (body.state !== "OPEN") return "closed";
+    // The same check-state mapping as every other PR read; files are not requested here.
+    const evidence = parsePrEvidence({ ...body, files: [], changedFiles: 0 });
+    const rows = (required.length ? required : DEFAULT_CHECKS).map(name => evidence.checks.filter(check => check.name === name));
+    if (rows.some(row => row.some(check => check.state === "failed"))) return "failed";
+    if (rows.some(row => row.length === 0 || row.some(check => check.state === "pending"))) return "pending";
+    return rows.every(row => row.length === 1 && row[0]!.state === "passed") ? "passed" : "incomplete";
+  } catch { return "pending"; }
+}
+
+export interface CiWatchersOptions {
+  deadlineMs?: number;
+  pollMs?: number;
+  now?: () => number;
+  poll: (watch: CiWatch) => Promise<CiPoll>;
+  /** False once the task moved or its head changed: the watcher ends without a notice. */
+  current: (watch: CiWatch) => boolean;
+  finish: (watch: CiWatch, outcome: CiOutcome) => void | Promise<void>;
+}
+
+/**
+ * At most one watcher per task, and one per exact head. Timers are chained `setTimeout`s (never an interval), unref'd, and cleared
+ * on every end, so nothing outlives its deadline, a newer head or `stopAll`. Watchers are not restored after a hub restart:
+ * the next `hub_task_done` starts one (ponytail: persist them only if restarts during CI turn out to be common).
+ */
+export class CiWatchers {
+  private readonly active = new Map<number, { watch: CiWatch; timer?: ReturnType<typeof setTimeout> }>();
+  private readonly settled = new Map<number, { head: string; outcome: CiOutcome }>();
+  private readonly deadlineMs: number;
+  private readonly pollMs: number;
+  private readonly now: () => number;
+
+  constructor(private readonly o: CiWatchersOptions) {
+    this.deadlineMs = o.deadlineMs ?? CI_WATCH_DEADLINE_MS;
+    this.pollMs = o.pollMs ?? CI_WATCH_POLL_MS;
+    this.now = o.now ?? Date.now;
+  }
+
+  get size(): number { return this.active.size; }
+
+  /** Starts a watcher for this exact head; false when this head is already watched or already reported. A different head replaces the old watcher. */
+  start(target: { id: number; head: string; repo: string; pr: number }): boolean {
+    const have = this.active.get(target.id);
+    if (have?.watch.head === target.head || this.settled.get(target.id)?.head === target.head) return false;
+    if (have) this.cancel(target.id);
+    const entry: { watch: CiWatch; timer?: ReturnType<typeof setTimeout> } = { watch: { ...target, deadlineAt: this.now() + this.deadlineMs } };
+    this.active.set(target.id, entry);
+    this.schedule(entry);
+    return true;
+  }
+
+  /** The result already reported for this exact head, if any. */
+  outcomeOf(id: number, head: string): CiOutcome | undefined {
+    const done = this.settled.get(id);
+    return done?.head === head ? done.outcome : undefined;
+  }
+
+  /** Ends the task's watcher (a given head only when `head` is named). No notice. */
+  cancel(id: number, head?: string): void {
+    const entry = this.active.get(id);
+    if (!entry || head !== undefined && entry.watch.head !== head) return;
+    clearTimeout(entry.timer);
+    this.active.delete(id);
+  }
+
+  stopAll(): void {
+    for (const entry of this.active.values()) clearTimeout(entry.timer);
+    this.active.clear();
+  }
+
+  private schedule(entry: { watch: CiWatch; timer?: ReturnType<typeof setTimeout> }): void {
+    const delay = Math.max(0, Math.min(this.pollMs, entry.watch.deadlineAt - this.now()));
+    entry.timer = setTimeout(() => { void this.tick(entry); }, delay);
+    entry.timer.unref?.();
+  }
+
+  private end(entry: { watch: CiWatch; timer?: ReturnType<typeof setTimeout> }): boolean {
+    if (this.active.get(entry.watch.id) !== entry) return false;
+    clearTimeout(entry.timer);
+    this.active.delete(entry.watch.id);
+    return true;
+  }
+
+  private report(entry: { watch: CiWatch }, outcome: CiOutcome): void {
+    if (outcome !== "deadline") {
+      this.settled.delete(entry.watch.id);
+      this.settled.set(entry.watch.id, { head: entry.watch.head, outcome });
+      while (this.settled.size > SETTLED_CAP) this.settled.delete(this.settled.keys().next().value as number);
+    }
+    void Promise.resolve().then(() => this.o.finish(entry.watch, outcome)).catch(() => { /* the finisher guards its own notices */ });
+  }
+
+  /** A watcher never throws out of its timer: a `current` or `finish` that fails (a closed board at shutdown) ends it. */
+  private async tick(entry: { watch: CiWatch; timer?: ReturnType<typeof setTimeout> }): Promise<void> {
+    try { await this.step(entry); } catch { this.end(entry); }
+  }
+
+  private async step(entry: { watch: CiWatch; timer?: ReturnType<typeof setTimeout> }): Promise<void> {
+    entry.timer = undefined;
+    if (this.active.get(entry.watch.id) !== entry) return;
+    if (!this.o.current(entry.watch)) { this.end(entry); return; }
+    if (this.now() >= entry.watch.deadlineAt) { if (this.end(entry)) this.report(entry, "deadline"); return; }
+    let result: CiPoll;
+    try { result = await this.o.poll(entry.watch); } catch { result = "pending"; }
+    if (this.active.get(entry.watch.id) !== entry) return; // cancelled or replaced during the read
+    if (!this.o.current(entry.watch) || result === "superseded" || result === "closed") { this.end(entry); return; }
+    if (result === "pending") { this.schedule(entry); return; }
+    if (this.end(entry)) this.report(entry, result);
+  }
+}

package/src/hub/claude-launch-proof.ts

@@ -1,8 +1,12 @@
 import { closeSync, fstatSync, openSync, readSync, constants } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { claudeStateFile } from "./claude-state.ts";
+import { readFileSync } from "node:fs";
+import { isWsPeer, type WsPeer } from "../adapters/channel-peer.ts";
+import { isFixedBuiltinDefinition, type AdapterDefinition } from "../adapters/registry.ts";
+import type { PeerAdapter } from "./peers.ts";
 
-export interface ClaudeLaunchProof {
+export interface ClaudeLaunchRecordProof {
   launchId: string;
   executionCwd?: string;
   privateRecord: boolean;
@@ -12,7 +16,7 @@ export interface ClaudeLaunchProof {
 }
 
 /** One bounded reader for current managed launch metadata; no native identity or payload escapes. */
-export function readClaudeLaunchProof(stateDir: string, peer: string, instanceId: string): ClaudeLaunchProof | undefined {
+export function readClaudeLaunchProof(stateDir: string, peer: string, instanceId: string): ClaudeLaunchRecordProof | undefined {
   let fd: number | undefined;
   try {
     fd = openSync(join(stateDir, claudeStateFile("claude-launch", peer)), constants.O_RDONLY | constants.O_NOFOLLOW);
@@ -31,3 +35,64 @@ export function readClaudeLaunchProof(stateDir: string, peer: string, instanceId
   } catch { return; }
   finally { if (fd !== undefined) closeSync(fd); }
 }
+
+/** Host-only launch and socket-generation evidence; adapter-reported generations cannot establish it. */
+export interface ClaudeLaunchProof {
+  permissionLaunch(peer: string): { launchId: string; unattended: boolean; hookPurpose?: string } | undefined;
+  helloLaunch(peer: string, launchId: unknown): "admit" | "refuse";
+  expectedLaunch(peer: string): string | undefined;
+  owner(peer: string): WsPeer | undefined;
+  bindGeneration(peer: string, generation: string): void;
+  verified(peer: string): boolean;
+}
+
+export function createClaudeLaunchProof(opts: {
+  stateDir: string;
+  cwd: string;
+  instanceId: string;
+  definitionOf(peer: string): AdapterDefinition | undefined;
+  peer(peer: string): PeerAdapter | undefined;
+}): ClaudeLaunchProof {
+  const generations = new Map<string, string>();
+  function channel(peer: string): boolean {
+    const definition = opts.definitionOf(peer);
+    return isFixedBuiltinDefinition(definition) && definition?.transport === "claude-channel";
+  }
+  function owner(peer: string): WsPeer | undefined {
+    if (!channel(peer)) return;
+    const current = opts.peer(peer);
+    return isWsPeer(current) ? current : undefined;
+  }
+  function permissionLaunch(peer: string): ReturnType<ClaudeLaunchProof["permissionLaunch"]> {
+    if (!channel(peer)) return;
+    const row = readClaudeLaunchProof(opts.stateDir, peer, opts.instanceId);
+    return row?.permissionHook ? row : undefined;
+  }
+  function helloLaunch(peer: string, launchId: unknown): "admit" | "refuse" {
+    if (!channel(peer) || launchId === undefined) return "admit";
+    let currentLaunch: unknown;
+    try {
+      const launch = readClaudeLaunchProof(opts.stateDir, peer, opts.instanceId);
+      if (launch) currentLaunch = launch.launchId;
+    } catch { /* No current launch evidence: retain plain/pre-daemon attachment compatibility. */ }
+    return currentLaunch !== undefined && launchId !== currentLaunch ? "refuse" : "admit";
+  }
+  function expectedLaunch(peer: string): string | undefined {
+    if (!channel(peer)) return;
+    let expectedLaunch: string | undefined;
+    try {
+      const rows = JSON.parse(readFileSync(join(opts.stateDir, "terminal-recovery.json"), "utf8"));
+      expectedLaunch = Array.isArray(rows) ? rows.find(row => row?.peer === peer && opts.definitionOf(row.peer)?.transport === "claude-channel" && row?.projectRoot === opts.cwd && row?.instanceId === opts.instanceId)?.launchId : undefined;
+    } catch { /* an ordinary terminal has no Orca recovery identity */ }
+    try {
+      const launch = readClaudeLaunchProof(opts.stateDir, peer, opts.instanceId);
+      if (launch) expectedLaunch = launch.launchId;
+    } catch { /* older/manual launches do not have a launcher marker */ }
+    return expectedLaunch;
+  }
+  return {
+    permissionLaunch, helloLaunch, expectedLaunch, owner,
+    bindGeneration(peer, generation) { if (owner(peer)) generations.set(peer, generation); },
+    verified(peer) { const current = owner(peer); return !!current && generations.get(peer) === current.sessionGeneration; },
+  };
+}