@staix/agent-hub 0.25.0 → 0.26.0

package/src/hub/project-runtime-state.ts

@@ -0,0 +1,139 @@
+import { closeSync, constants, existsSync, fstatSync, mkdirSync, openSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, isAbsolute, join, normalize, relative, sep } from "node:path";
+import type { Project } from "./registry.ts";
+import { configRepositoryPresent } from "./config-trust.ts";
+import { childEnv } from "./child-process.ts";
+import { hubGitSync } from "./git.ts";
+
+export type RuntimeProject = Pick<Project, "id" | "root" | "stateDir">;
+export interface ProjectRuntimeSelection { version: string; root: string; digest: string; kind: "restart" | "upgrade" }
+export interface ProjectRuntimeIdentity extends ProjectRuntimeSelection {
+  schema: 1; projectId: string; projectRoot: string; stateDir: string; instanceId: string | null;
+}
+export const PROJECT_RUNTIME_FILE = "runtime.json";
+const LIMIT = 16 * 1024;
+const version = (v: unknown): v is string => typeof v === "string" && v.length <= 64 && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.exec(v)?.[0] === v;
+const pathText = (v: unknown): v is string => typeof v === "string" && v.length <= 4096 && isAbsolute(v) && normalize(v) === v && !/[\x00-\x1f\x7f]/.test(v);
+export const projectRuntimeFile = (project: RuntimeProject): string => join(project.stateDir, PROJECT_RUNTIME_FILE);
+const invalid = (): Error => new Error("project runtime record is invalid; inspect runtime.json before starting");
+
+export function parseProjectRuntime(project: RuntimeProject, input: unknown): ProjectRuntimeIdentity {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw invalid();
+  const row = input as Record<string, unknown>;
+  if (Object.keys(row).sort().join(",") !== "digest,instanceId,kind,projectId,projectRoot,root,schema,stateDir,version"
+    || row.schema !== 1 || row.projectId !== project.id || row.projectRoot !== project.root || row.stateDir !== project.stateDir
+    || !version(row.version) || !pathText(row.root) || typeof row.digest !== "string" || row.digest.length !== 64 || !/^[a-f0-9]{64}$/.test(row.digest)
+    || row.kind !== "restart" && row.kind !== "upgrade"
+    || row.instanceId !== null && (typeof row.instanceId !== "string" || /^[a-zA-Z0-9-]{1,128}$/.exec(row.instanceId)?.[0] !== row.instanceId)) throw invalid();
+  return { schema: 1, projectId: project.id, projectRoot: project.root, stateDir: project.stateDir,
+    version: row.version, root: row.root, digest: row.digest, kind: row.kind, instanceId: row.instanceId as string | null };
+}
+
+const ACCESS = Symbol("project runtime access");
+export interface ProjectRuntimeAccess {
+  readonly [ACCESS]: true;
+  readonly projectId: string; readonly projectRoot: string; readonly stateDir: string;
+  read(): ProjectRuntimeIdentity | undefined;
+  write(runtime: ProjectRuntimeSelection, instanceId: string | null): ProjectRuntimeIdentity;
+}
+const TRUST_GIT_MS = 2000;
+const exactGlob = (value: string) => value.replace(/([*?[\]\\])/g, "\\$1");
+const trustRefusal = (why: string): never => { throw new Error(`project runtime selection is machine-local: ${why}`); };
+
+/** Plain folders remain supported. A repository must affirm this file is untracked using only its parent/ancestor paths. */
+function requireRuntimeTrust(project: RuntimeProject): void {
+  const file = projectRuntimeFile(project), checked = new Set<string>(), deadline = performance.now() + TRUST_GIT_MS;
+  const git = (args: string[]) => {
+    const remaining = deadline - performance.now();
+    if (remaining <= 0) trustRefusal("git could not confirm runtime.json is untracked");
+    return hubGitSync(args, { encoding: "utf8", env: childEnv(process.env), timeout: Math.max(1, Math.ceil(remaining)), maxBuffer: 256 * 1024 });
+  };
+  for (const cwd of new Set([project.root, dirname(file)])) {
+    if (!configRepositoryPresent(cwd)) continue;
+    let at = cwd;
+    while (!existsSync(at) && dirname(at) !== at) at = dirname(at);
+    const top = git(["-C", at, "rev-parse", "--show-toplevel"]);
+    if (top.status !== 0 || !isAbsolute(top.stdout.trim())) trustRefusal("git could not confirm runtime.json is untracked");
+    const root = top.stdout.trim(), selected = relative(root, file).split(sep).join("/");
+    if (checked.has(root) || selected === ".." || selected.startsWith("../") || isAbsolute(selected)) continue;
+    checked.add(root);
+    const parts = selected.split("/"), parent = parts.slice(0, -1).join("/");
+    // ponytail: explicit custom stateDir ancestor listings can exceed 256 KiB (default unaffected); use an untracked dedicated state directory, then upgrade to exact ancestor index lookup.
+    const specs = [`:(icase,literal)${parent || selected}`];
+    for (let i = 1; i < parts.length - 1; i++) specs.push(`:(icase,glob)${exactGlob(parts.slice(0, i).join("/"))}`);
+    const tracked = git(["-C", root, "ls-files", "-s", "-z", "--", ...specs]);
+    if (tracked.status !== 0) trustRefusal("git could not confirm runtime.json is untracked");
+    let opened: { dev: number; ino: number } | undefined;
+    try { opened = statSync(file); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") trustRefusal("runtime.json identity is unavailable"); }
+    for (const row of tracked.stdout.split("\0").filter(Boolean)) {
+      const name = row.slice(row.indexOf("\t") + 1);
+      if (name === selected || selected.startsWith(`${name}/`)) trustRefusal("runtime.json or its parent is committed to git");
+      if (opened) {
+        let info; try { info = statSync(join(root, name)); } catch { continue; }
+        if (info.dev === opened.dev && info.ino === opened.ino) trustRefusal("runtime.json is committed to git");
+      }
+    }
+  }
+}
+
+/** This reserved sibling namespace is exclusively for captures withdrawn for pruning. */
+export function assertExecutableRuntimeRoot(root: string): void {
+  for (let at = root; ; at = dirname(at)) {
+    if (basename(at).startsWith(".runtime-prune-")) throw new Error("runtime root is quarantined for pruning");
+    if (dirname(at) === at) return;
+  }
+}
+
+/** Host-only, project-bound admission for one call; callers create it before acquiring the registry lock. */
+export function createProjectRuntimeAccess(project: RuntimeProject): ProjectRuntimeAccess {
+  requireRuntimeTrust(project);
+  const bound = { id: project.id, root: project.root, stateDir: project.stateDir };
+  return Object.freeze({ [ACCESS]: true as const, projectId: bound.id, projectRoot: bound.root, stateDir: bound.stateDir,
+    read: () => readProjectRuntimeReference(bound), write: (runtime: ProjectRuntimeSelection, instanceId: string | null) => writeRuntimeState(bound, runtime, instanceId) });
+}
+function accessFor(project: RuntimeProject, access?: ProjectRuntimeAccess): ProjectRuntimeAccess {
+  if (!access) return createProjectRuntimeAccess(project);
+  if (access[ACCESS] !== true || access.projectId !== project.id || access.projectRoot !== project.root || access.stateDir !== project.stateDir)
+    throw new Error("project runtime access belongs to another project");
+  return access;
+}
+
+export function readProjectRuntime(project: RuntimeProject, access?: ProjectRuntimeAccess): ProjectRuntimeIdentity | undefined {
+  return accessFor(project, access).read();
+}
+
+/** Metadata-only retention reference: bounded binding/JSON checks confer no Git trust or execution authority. */
+export function readProjectRuntimeReference(project: RuntimeProject): ProjectRuntimeIdentity | undefined {
+  let fd: number;
+  try { fd = openSync(projectRuntimeFile(project), constants.O_RDONLY | constants.O_NOFOLLOW); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw invalid(); }
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.nlink !== 1 || before.size > LIMIT) throw invalid();
+    const bytes = Buffer.alloc(LIMIT + 1);
+    const count = readSync(fd, bytes, 0, bytes.length, 0), after = fstatSync(fd);
+    if (count > LIMIT || count !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) throw invalid();
+    return parseProjectRuntime(project, JSON.parse(bytes.subarray(0, count).toString("utf8")));
+  } catch { throw invalid(); }
+  finally { closeSync(fd); }
+}
+
+/** Caller holds the shared runtime-capture lock until publication and its launch/reference effects finish. */
+function writeRuntimeState(project: RuntimeProject, runtime: ProjectRuntimeSelection, instanceId: string | null): ProjectRuntimeIdentity {
+  const record = parseProjectRuntime(project, { schema: 1, projectId: project.id, projectRoot: project.root, stateDir: project.stateDir,
+    version: runtime.version, root: runtime.root, digest: runtime.digest, kind: runtime.kind, instanceId });
+  assertExecutableRuntimeRoot(record.root);
+  readProjectRuntimeReference(project); // refuse to overwrite an unknown binding or an unsafe file
+  const body = JSON.stringify(record);
+  if (Buffer.byteLength(body) > LIMIT) throw invalid();
+  mkdirSync(project.stateDir, { recursive: true });
+  const file = projectRuntimeFile(project), temporary = `${file}.${randomUUID()}.tmp`;
+  try { writeFileSync(temporary, body, { mode: 0o600, flag: "wx" }); renameSync(temporary, file); }
+  finally { rmSync(temporary, { force: true }); }
+  return record;
+}
+
+export function writeProjectRuntimeState(project: RuntimeProject, runtime: ProjectRuntimeSelection, instanceId: string | null, access?: ProjectRuntimeAccess): ProjectRuntimeIdentity {
+  return accessFor(project, access).write(runtime, instanceId);
+}

package/src/hub/project-runtime.ts

@@ -0,0 +1,62 @@
+import { resolve } from "node:path";
+import { stageCurrentRuntime, verifyRecoveryTarget, newerVersion, exactVersion } from "../cli/recovery-package.ts";
+import { hubHome, realPath } from "./project.ts";
+import { Registry, type Project } from "./registry.ts";
+import { processLiveness } from "../pi/process-signature.ts";
+import { assertExecutableRuntimeRoot, createProjectRuntimeAccess, readProjectRuntime, writeProjectRuntimeState, type ProjectRuntimeAccess, type ProjectRuntimeIdentity, type ProjectRuntimeSelection } from "./project-runtime-state.ts";
+export { readProjectRuntime } from "./project-runtime-state.ts";
+export type { ProjectRuntimeIdentity, ProjectRuntimeSelection } from "./project-runtime-state.ts";
+
+export const projectRuntimeRefusal = (version: string, detail?: string): Error => new Error(`this project runs ${version}; use ${version} or later / ahub upgrade${detail ? ` (${detail})` : ""}`);
+
+export function verifyProjectRuntime(runtime: ProjectRuntimeSelection): ProjectRuntimeSelection {
+  assertExecutableRuntimeRoot(runtime.root);
+  try {
+    if (realPath(runtime.root) !== runtime.root || verifyRecoveryTarget(runtime.kind, runtime.root, runtime.version) !== runtime.digest)
+      throw new Error("runtime changed");
+    return runtime;
+  } catch { throw projectRuntimeRefusal(runtime.version, "recorded runtime is missing or changed"); }
+}
+
+/** Read-only caller admission also covers an already-running daemon; no capture is staged or hashed here. */
+export function readProjectRuntimeForCaller(project: Project, invokingVersion: string, access?: ProjectRuntimeAccess): ProjectRuntimeIdentity | undefined {
+  exactVersion(invokingVersion);
+  const retained = readProjectRuntime(project, access);
+  // ponytail: only updated resolver code honors runtime.json; bootstrap shared CLI to 0.26.0+ before relying on this floor.
+  if (retained && newerVersion(retained.version, invokingVersion)) throw projectRuntimeRefusal(retained.version);
+  return retained;
+}
+
+/** Selectors first ship in 0.26.0; unmodified earlier published CLIs cannot honor this record. */
+export function resolveProjectRuntime(project: Project, invokingVersion: string, sourceRoot = resolve(import.meta.dir, "../.."), registry?: Registry, access?: ProjectRuntimeAccess): ProjectRuntimeSelection {
+  const retained = readProjectRuntimeForCaller(project, invokingVersion, access);
+  if (retained) return verifyProjectRuntime(retained);
+  const staged = stageCurrentRuntime(sourceRoot, invokingVersion, hubHome(), registry);
+  return { ...staged, kind: "restart" };
+}
+
+export function recordProjectRuntime(project: Project, runtime: ProjectRuntimeSelection, instanceId: string | null, registry: Registry, access?: ProjectRuntimeAccess): void {
+  const admitted = access ?? createProjectRuntimeAccess(project);
+  registry.runtimeCaptureLocked(() => {
+    const current = registry.get(project.id);
+    if (!current || current.root !== project.root || current.stateDir !== project.stateDir
+      || instanceId !== null && current.instanceId !== instanceId
+      || instanceId === null && current.instanceId && processLiveness(current.pid, current.pidSignature) !== "gone")
+      throw new Error("project runtime owner changed; refresh before starting");
+    verifyProjectRuntime(runtime);
+    writeProjectRuntimeState(project, runtime, instanceId, admitted);
+  });
+}
+
+/** A null instance is a pending selection, never consent to replace a later capture choice. */
+export function confirmProjectRuntime(project: Project, runtime: ProjectRuntimeSelection, observed: { version?: unknown; instanceId?: unknown }, registry: Registry, access?: ProjectRuntimeAccess): void {
+  const admitted = access ?? createProjectRuntimeAccess(project);
+  registry.runtimeCaptureLocked(() => {
+    const saved = readProjectRuntime(project, admitted);
+    if (!saved || saved.version !== runtime.version || saved.root !== runtime.root || saved.digest !== runtime.digest || saved.kind !== runtime.kind
+      || observed.version !== runtime.version || typeof observed.instanceId !== "string" || !observed.instanceId
+      || saved.instanceId !== null && saved.instanceId !== observed.instanceId)
+      throw projectRuntimeRefusal(saved?.version ?? runtime.version, "runtime selection changed before readiness");
+    recordProjectRuntime(project, runtime, observed.instanceId, registry, admitted);
+  });
+}

package/src/hub/protocol-window.ts

@@ -0,0 +1,19 @@
+/** Inclusive supported control-wire interval; v is its highest version. */
+export interface ProtocolWindow { v: number; vMin: number }
+
+/** Older peers without a minimum advertise only their one explicit version. */
+export function protocolWindow(v: unknown, vMin?: unknown): ProtocolWindow | undefined {
+  if (typeof v !== "number" || !Number.isSafeInteger(v) || v <= 0) return undefined;
+  const minimum = vMin === undefined ? v : vMin;
+  if (typeof minimum !== "number" || !Number.isSafeInteger(minimum) || minimum <= 0 || minimum > v) return undefined;
+  return { v, vMin: minimum };
+}
+
+/** Choose the highest common version. Invalid intervals and disjoint ranges negotiate nothing. */
+export function negotiateProtocol(local: ProtocolWindow, remote: ProtocolWindow): number | undefined {
+  if (!local || typeof local !== "object" || Array.isArray(local) || !remote || typeof remote !== "object" || Array.isArray(remote)) return undefined;
+  const a = protocolWindow(local.v, local.vMin), b = protocolWindow(remote.v, remote.vMin);
+  if (!a || !b) return undefined;
+  const highest = Math.min(a.v, b.v);
+  return highest >= Math.max(a.vMin, b.vMin) ? highest : undefined;
+}

package/src/hub/recovery-store.ts

@@ -1,14 +1,15 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { chmodSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { Database } from "bun:sqlite";
-import { hubHome } from "./project.ts";
+import { canonicalPath, hubHome } from "./project.ts";
+import { isDatabaseBusy } from "./recovery-error.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 
 const RUNNER_DB_BUSY_TIMEOUT_MS = 3000;
 export const operationIdPattern = /^[a-f0-9-]{36}$/;
 export function operationPath(id: string, home = hubHome()): string {
-  if (!operationIdPattern.test(id)) throw new Error("invalid recovery operation ID");
+  if (typeof id !== "string" || id.length !== 36 || !operationIdPattern.test(id)) throw new Error("invalid recovery operation ID");
   return join(home, "recovery", `${id}.json`);
 }
 
@@ -31,11 +32,11 @@ export function writeOperation(id: string, value: unknown, home = hubHome()): vo
   atomicPrivateJSON(operationPath(id, home), value);
 }
 
-export function recoveryLock(home = hubHome()): string | undefined {
+function legacyRecoveryLock(home: string): string | undefined {
   const file = join(home, "recovery.lock");
   try {
     const data = JSON.parse(readFileSync(file, "utf8"));
-    if (!operationIdPattern.test(data.operationId)) throw new Error("invalid recovery lock");
+    if (typeof data.operationId !== "string" || data.operationId.length !== 36 || !operationIdPattern.test(data.operationId)) throw new Error("invalid recovery lock");
     return data.operationId;
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
@@ -43,23 +44,112 @@ export function recoveryLock(home = hubHome()): string | undefined {
   }
 }
 
-export function acquireRecoveryLock(id: string, home = hubHome()): void {
+const projectLocksPath = (home: string) => join(home, "recovery", "project-locks.db");
+const projectLockError = () => new Error("project recovery coordination state is unreadable; inspect it before changing runtimes");
+function recoveryProjectKey(root: string): string {
+  if (typeof root !== "string" || !isAbsolute(root) || root.includes(String.fromCharCode(0))) throw new Error("recovery scope needs a canonical project root");
+  try { return canonicalPath(root); }
+  catch (error) {
+    // Receipts retain the already-canonical registration spelling so a removed project can still be disposed.
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return resolve(root);
+    throw error;
+  }
+}
+function projectLocksExist(file: string): boolean {
+  try {
+    const info = lstatSync(file);
+    if (!info.isFile() || info.isSymbolicLink()) throw projectLockError();
+    return true;
+  } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return false; throw error; }
+}
+function projectLocks(home: string, create = false): Database | undefined {
+  const file = projectLocksPath(home);
+  if (!projectLocksExist(file)) {
+    if (!create) return undefined;
+    mkdirSync(join(home, "recovery"), { recursive: true, mode: 0o700 });
+    // Publish a complete DELETE-journal database, never an empty coordination file another process could misread.
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+      const db = new Database(temporary, { create: true });
+      try {
+        db.run(`PRAGMA busy_timeout = ${RUNNER_DB_BUSY_TIMEOUT_MS}`);
+        db.run("CREATE TABLE project_locks (project_root TEXT PRIMARY KEY, operation_id TEXT NOT NULL)");
+      } finally { db.close(); }
+      chmodSync(temporary, 0o600);
+      try { linkSync(temporary, file); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+    } finally { rmSync(temporary, { force: true }); }
+  }
+  if (!projectLocksExist(file)) throw projectLockError();
+  let db: Database | undefined;
+  try {
+    db = new Database(file, create ? { readwrite: true, create: false } : { readonly: true, create: false });
+    db.run(`PRAGMA busy_timeout = ${RUNNER_DB_BUSY_TIMEOUT_MS}`);
+    if (!db.query("SELECT 1 FROM sqlite_master WHERE type='table' AND name='project_locks'").get()) throw projectLockError();
+    return db;
+  } catch (error) { db?.close(); if (isDatabaseBusy(error)) throw error; throw projectLockError(); }
+}
+function projectLockOn(db: Database, key: string): string | undefined {
+  const rows = db.query("SELECT CASE WHEN typeof(operation_id)='text' AND length(operation_id)=36 THEN operation_id END AS id FROM project_locks WHERE project_root=? LIMIT 2").all(key) as { id: string | null }[];
+  if (!rows.length) return undefined;
+  if (rows.length !== 1 || typeof rows[0]!.id !== "string" || !operationIdPattern.test(rows[0]!.id)) throw projectLockError();
+  return rows[0]!.id;
+}
+
+/** Legacy machine holds remain authoritative; new project holds affect only their canonical project. */
+export function recoveryLock(home = hubHome(), projectRoot?: string): string | undefined {
+  const legacy = legacyRecoveryLock(home);
+  if (legacy || projectRoot === undefined) return legacy;
+  const key = recoveryProjectKey(projectRoot), db = projectLocks(home);
+  if (!db) return undefined;
+  try { return projectLockOn(db, key); }
+  finally { db.close(); }
+}
+
+export function acquireRecoveryLock(id: string, home = hubHome(), projectRoot?: string): void {
   operationPath(id, home);
+  if (projectRoot !== undefined) {
+    const key = recoveryProjectKey(projectRoot), legacy = legacyRecoveryLock(home);
+    if (legacy && legacy !== id) throw new Error(`another recovery operation owns this machine: ${legacy}`);
+    const db = projectLocks(home, true)!;
+    try {
+      db.transaction(() => {
+        const existing = projectLockOn(db, key);
+        if (existing && existing !== id) throw new Error(`another recovery operation owns this project: ${existing}`);
+        if (!existing) db.query("INSERT INTO project_locks(project_root,operation_id) VALUES(?,?)").run(key, id);
+      }).immediate();
+    } finally { db.close(); }
+    return;
+  }
   mkdirSync(home, { recursive: true, mode: 0o700 });
   const existing = recoveryLock(home);
   if (existing === id) return;
-  try { writeFileSync(join(home, "recovery.lock"), JSON.stringify({ operationId: id }), { mode: 0o600, flag: "wx" }); }
-  catch { throw new Error(`another recovery operation owns this machine: ${recoveryLock(home) ?? "unknown"}`); }
+  const temporary = join(home, `.recovery-lock-${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporary, JSON.stringify({ operationId: id }), { mode: 0o600, flag: "wx" });
+    try { linkSync(temporary, join(home, "recovery.lock")); }
+    catch { throw new Error(`another recovery operation owns this machine: ${recoveryLock(home) ?? "unknown"}`); }
+  } finally { rmSync(temporary, { force: true }); }
 }
 
-export function releaseRecoveryLock(id: string, home = hubHome()): void {
+export function releaseRecoveryLock(id: string, home = hubHome(), projectRoot?: string): void {
+  operationPath(id, home);
+  if (projectRoot !== undefined) {
+    const key = recoveryProjectKey(projectRoot), db = projectLocks(home, true)!;
+    try {
+      if (db.query("DELETE FROM project_locks WHERE project_root=? AND operation_id=?").run(key, id).changes !== 1)
+        throw new Error("recovery lock ownership changed");
+    } finally { db.close(); }
+    return;
+  }
+  // Legacy release is called under the operation's exclusive runner claim. Project releases compare/delete atomically.
   if (recoveryLock(home) !== id) throw new Error("recovery lock ownership changed");
   rmSync(join(home, "recovery.lock"));
 }
 
 /** Used by CLI and manager lifecycle paths. A detached operation carries its own ID. */
-export function assertLifecycleAvailable(): void {
-  const owner = recoveryLock();
+export function assertLifecycleAvailable(projectRoot?: string): void {
+  const owner = recoveryLock(undefined, projectRoot);
   if (owner && process.env.AGENTHUB_RECOVERY_OPERATION !== owner) throw new Error(activeOperation(owner));
 }
 

package/src/hub/registry.ts

@@ -106,6 +106,11 @@ export class Registry {
     return (this.db.query(`SELECT ${PROJECT_COLUMNS}, pid_signature FROM projects ORDER BY root`).all() as Record<string, unknown>[]).map(projectFromRow);
   }
 
+  /** Serialize capture publication, durable project references and pruning with registry writers. */
+  runtimeCaptureLocked<T>(fn: () => T): T {
+    return this.db.inTransaction ? fn() : this.db.transaction(fn).immediate();
+  }
+
   allocate(root: string): number {
     return this.register(root).basePort;
   }

package/src/hub/research-experiments.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { types } from "node:util";
 import { looksSecret } from "@staix/agent-mem";
 import { canonicalJson } from "./packs.ts";
+import { parseAttemptReceipt, runnerSealing, type AttemptReceiptV1 } from "./research-runner.ts";
 import { parseDeliverableClaims, parseDeliverableRecords, deliverableId, DELIVERABLE_LIMITS, type DeliverableClaim, type DeliverableRecord } from "./deliverables.ts";
 
 export type ExperimentScalar = string | number | boolean | null;
@@ -46,6 +47,10 @@ export type DeclaredExperimentEventInput =
   | { kind: "note"; body: { text: string } };
 /** Host supplies ordering/time; this T1 parser never admits caller-written evidence elevation. */
 export type DeclaredExperimentEvent = DeclaredExperimentEventInput & { seq: number; at: number; provenance: "declared" };
+export interface RunnerAttestationEvent { kind: "attestation"; body: { receiptId: string }; seq: number; at: number; provenance: "runner-attested" }
+export type ExperimentEvent = DeclaredExperimentEvent | RunnerAttestationEvent;
+export const declaredExperimentEvents = (events: readonly ExperimentEvent[]): DeclaredExperimentEvent[] =>
+  events.filter((event): event is DeclaredExperimentEvent => event.provenance === "declared");
 export type ExperimentStatus = "declared" | "running" | "succeeded" | "failed" | "cancelled" | "unknown";
 
 const ID = /^[a-z0-9][a-z0-9_-]{0,63}$/, HASH = /^[0-9a-f]{64}$/, SOURCE = /^src:[0-9a-f]{16}$/;
@@ -302,12 +307,13 @@ export function deliverableObservation(record: DeliverableRecord): ExperimentHos
 }
 
 /** Keep conflicting declarations and measurements side by side; neither changes the attempt's declared terminal event. */
-export function projectExperimentWithObservations(protocol: ExperimentProtocolContract, events: readonly DeclaredExperimentEvent[], observations: readonly { eventSeq: number; observation: ExperimentHostEvidence }[]) {
-  const declared = projectExperimentEvidence(protocol, events), seqs = new Set(events.map(event => event.seq));
+export function projectExperimentWithObservations(protocol: ExperimentProtocolContract, events: readonly ExperimentEvent[], observations: readonly { eventSeq: number; observation: ExperimentHostEvidence }[]) {
+  const declaredEvents = declaredExperimentEvents(events);
+  const declared = projectExperimentEvidence(protocol, declaredEvents), seqs = new Set(declaredEvents.map(event => event.seq));
   return { declared, measured: observations.map(row => {
     integer(row.eventSeq, "observation.eventSeq", 1);
     if (!seqs.has(row.eventSeq)) fail("observation.eventSeq", "declared event is unavailable");
-    const observation = parseExperimentHostEvidence(row.observation), event = events.find(event => event.seq === row.eventSeq)!;
+    const observation = parseExperimentHostEvidence(row.observation), event = declaredEvents.find(event => event.seq === row.eventSeq)!;
     if (observation.source === "check" && (event.kind !== "end" || event.body.run !== observation.evidence)) fail("observation", "check evidence must name its declared end run");
     if (observation.source === "deliverable" && (event.kind !== "output" || !("path" in event.body) || deliverableId(event.body.path, event.body.format) !== observation.evidence)) fail("observation", "output evidence must match a host hash request");
     return { eventSeq: row.eventSeq, source: observation.source, evidence: observation.evidence,
@@ -315,6 +321,29 @@ export function projectExperimentWithObservations(protocol: ExperimentProtocolCo
   }) };
 }
 
+export interface RunnerReceiptProjection {
+  receiptId: string;
+  runner: string;
+  provenance: "runner-attested";
+  values: Record<string, ExperimentValue<unknown>>;
+  sealing: ExperimentValue<boolean>;
+  codeMatch: ExperimentValue<boolean>;
+}
+const RUNNER_RECEIPT_FIELDS = ["codeCommit", "imageDigest", "containers", "mounts", "network", "resourceLimits", "startedAt", "endedAt", "exitStatus", "outputs", "metricsFile"] as const;
+const runnerAttested = <T>(value: T | undefined, evidence: string): ExperimentValue<T> => value === undefined
+  ? { value: null, provenance: "unknown" } : { value, provenance: "runner-attested", evidence };
+
+/** Project stored signature-verified receipts only; this view authenticates nothing and changes no declared or host-observed evidence. */
+export function projectRunnerReceipt(protocol: ExperimentProtocolContract, receipt: AttemptReceiptV1): RunnerReceiptProjection {
+  const parsed = parseAttemptReceipt(receipt);
+  if ("commit" in protocol.code && parsed.codeCommit !== undefined && parsed.codeCommit !== protocol.code.commit)
+    fail("receipt.codeCommit", "protocol commit mismatch");
+  return { receiptId: parsed.receiptId, runner: parsed.runner, provenance: "runner-attested",
+    values: Object.fromEntries(RUNNER_RECEIPT_FIELDS.map(field => [field, runnerAttested(parsed[field], parsed.receiptId)])),
+    sealing: runnerSealing(parsed) ? runnerAttested(true, parsed.receiptId) : declared(protocol.sealed),
+    codeMatch: "commit" in protocol.code && parsed.codeCommit !== undefined ? runnerAttested(true, parsed.receiptId) : runnerAttested<boolean>(undefined, parsed.receiptId) };
+}
+
 /** Storage records carry host-issued identity separately from the immutable caller body. */
 export interface ExperimentProtocolRecord {
   hash: string;
@@ -337,7 +366,7 @@ export interface ExperimentAttemptRecord {
 export interface ExperimentEventRecord {
   attemptId: string;
   idempotencyKey: string;
-  event: DeclaredExperimentEvent;
+  event: ExperimentEvent;
   bodyHash: string;
   by: string;
   private: boolean;

package/src/hub/research-runner.ts

@@ -0,0 +1,172 @@
+import { createPublicKey, verify } from "node:crypto";
+import { types } from "node:util";
+import { canonicalJson } from "./packs.ts";
+
+export interface RegisteredRunnerV1 { publicKey: string; projects: string[]; revoked: boolean }
+export interface RunnerContainer { id: string; role: "candidate" | "evaluator" | "other" }
+export interface RunnerMount { container: string; path: string; readOnly: boolean; purpose: "evaluator-code" | "evaluator-data" | "candidate-output" | "other" }
+export interface RunnerOutput { name: string; sha256: string }
+export interface AttemptReceiptV1 {
+  receiptId: string; runner: string; projectId: string; attemptId: string; protocolHash: string;
+  codeCommit?: string; imageDigest?: string; containers?: RunnerContainer[]; mounts?: RunnerMount[];
+  network?: "none" | "restricted" | "open";
+  resourceLimits?: { name: string; value: number; unit: string }[];
+  startedAt?: number; endedAt?: number; exitStatus?: number; outputs?: RunnerOutput[]; metricsFile?: RunnerOutput;
+}
+export interface RunnerVerificationContext {
+  runners: unknown;
+  projectId: string;
+  attempt: { id: string; projectId: string; protocolHash: string; codeCommit?: string } | undefined;
+}
+
+const ID = /^[a-z0-9][a-z0-9_-]{0,63}$/, HASH = /^[0-9a-f]{64}$/, ATTEMPT = /^ra-[0-9a-f]{12}$/;
+const BODY = 64 * 1024, SHORT = 512;
+/** Exactly the receipt domain and its NUL separator; no executable runner protocol. */
+export const RUNNER_RECEIPT_DOMAIN = "agent-hub.runner-receipt/v1" + String.fromCharCode(0);
+function fail(field: string, reason: string): never { throw new Error(`${field}: ${reason}`); }
+function object(input: unknown, keys: readonly string[] | undefined, field: string): Record<string, unknown> {
+  if (!input || typeof input !== "object" || Array.isArray(input) || types.isProxy(input)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(input)) || Object.getOwnPropertySymbols(input).length)
+    fail(field, "expected a plain data object");
+  const descriptors = Object.getOwnPropertyDescriptors(input);
+  if (Object.values(descriptors).some(value => !Object.hasOwn(value, "value"))) fail(field, "accessors are unavailable");
+  if (keys && Object.keys(descriptors).some(key => !keys.includes(key))) fail(field, "unknown field");
+  if (Object.values(descriptors).some(value => value.value === undefined)) fail(field, "omit absent fields");
+  return Object.fromEntries(Object.entries(descriptors).map(([key, value]) => [key, value.value]));
+}
+function array(input: unknown, max: number, field: string): unknown[] {
+  if (!Array.isArray(input) || types.isProxy(input) || Object.getPrototypeOf(input) !== Array.prototype
+    || input.length > max || Object.getOwnPropertySymbols(input).length) fail(field, `expected a list of at most ${max} items`);
+  const descriptors = Object.getOwnPropertyDescriptors(input);
+  if (Object.keys(descriptors).some(key => key !== "length" && !/^(0|[1-9][0-9]*)$/.test(key))) fail(field, "unknown list fields");
+  return Array.from({ length: input.length }, (_, index) => {
+    const value = descriptors[String(index)];
+    if (!value || !Object.hasOwn(value, "value")) fail(field, "expected a dense data list");
+    return value.value;
+  });
+}
+function text(input: unknown, field: string): string {
+  if (typeof input !== "string" || !input.trim() || input.length > SHORT || Buffer.byteLength(input, "utf8") > SHORT
+    || Buffer.from(input, "utf8").toString("utf8") !== input) fail(field, "expected non-empty UTF-8 text of at most 512 bytes");
+  return input;
+}
+function pattern(input: unknown, rule: RegExp, field: string): string {
+  if (typeof input !== "string" || rule.exec(input)?.[0] !== input) fail(field, "invalid identifier or hash");
+  return input;
+}
+function integer(input: unknown, field: string, min = 0): number {
+  if (typeof input !== "number" || !Number.isSafeInteger(input) || input < min) fail(field, "expected a bounded integer");
+  return input;
+}
+function choice<T extends string>(input: unknown, values: readonly T[], field: string): T {
+  if (typeof input !== "string" || !values.includes(input as T)) fail(field, "unsupported value");
+  return input as T;
+}
+function bounded<T>(value: T, field: string): T {
+  if (Buffer.byteLength(canonicalJson(value), "utf8") > BODY) fail(field, "stored body exceeds 64 KiB");
+  return value;
+}
+function base64(input: unknown, bytes: number, field: string): Buffer {
+  if (typeof input !== "string" || input.length !== 4 * Math.ceil(bytes / 3) || !/^[A-Za-z0-9+/]+={0,2}$/.test(input))
+    fail(field, "invalid canonical base64");
+  const decoded = Buffer.from(input, "base64");
+  if (decoded.length !== bytes || decoded.toString("base64") !== input) fail(field, "invalid canonical base64");
+  return decoded;
+}
+function publicKey(input: unknown, field: string): string {
+  const bytes = base64(input, 44, field);
+  try {
+    const key = createPublicKey({ key: bytes, format: "der", type: "spki" });
+    if (key.asymmetricKeyType !== "ed25519" || !key.export({ format: "der", type: "spki" }).equals(bytes))
+      fail(field, "expected an Ed25519 SPKI public key");
+  } catch { fail(field, "expected an Ed25519 SPKI public key"); }
+  return input as string;
+}
+
+/** Data validation only. Person-only registration and machine-local placement belong to the host. */
+export function parseResearchRunners(input: unknown): Record<string, RegisteredRunnerV1> {
+  const raw = object(input, undefined, "research.runners"), entries = Object.entries(raw);
+  if (entries.length > 16) fail("research.runners", "at most 16 runners");
+  return bounded(Object.fromEntries(entries.map(([name, value]) => {
+    const field = `research.runners.${pattern(name, ID, "research.runners.name")}`, row = object(value, ["publicKey", "projects", "revoked"], field);
+    const projects = array(row.projects, 64, `${field}.projects`).map(value => text(value, `${field}.projects`));
+    if (new Set(projects).size !== projects.length) fail(`${field}.projects`, "duplicate projects");
+    if (typeof row.revoked !== "boolean") fail(`${field}.revoked`, "expected a boolean");
+    return [name, { publicKey: publicKey(row.publicKey, `${field}.publicKey`), projects, revoked: row.revoked }];
+  })), "research.runners");
+}
+
+function output(input: unknown, field: string): RunnerOutput {
+  const row = object(input, ["name", "sha256"], field);
+  return { name: text(row.name, `${field}.name`), sha256: pattern(row.sha256, HASH, `${field}.sha256`) };
+}
+
+/** Absent observations stay absent. Isolation inconsistencies are signed evidence, not schema failures. */
+export function parseAttemptReceipt(input: unknown): AttemptReceiptV1 {
+  const raw = object(input, ["receiptId", "runner", "projectId", "attemptId", "protocolHash", "codeCommit", "imageDigest", "containers", "mounts", "network", "resourceLimits", "startedAt", "endedAt", "exitStatus", "outputs", "metricsFile"], "receipt");
+  const receipt: AttemptReceiptV1 = { receiptId: pattern(raw.receiptId, ID, "receipt.receiptId"), runner: pattern(raw.runner, ID, "receipt.runner"),
+    projectId: text(raw.projectId, "receipt.projectId"), attemptId: pattern(raw.attemptId, ATTEMPT, "receipt.attemptId"), protocolHash: pattern(raw.protocolHash, HASH, "receipt.protocolHash") };
+  if (raw.codeCommit !== undefined) receipt.codeCommit = pattern(raw.codeCommit, /^[0-9a-f]{40}$/, "receipt.codeCommit");
+  if (raw.imageDigest !== undefined) receipt.imageDigest = pattern(raw.imageDigest, /^sha256:[0-9a-f]{64}$/, "receipt.imageDigest");
+  if (raw.containers !== undefined) receipt.containers = array(raw.containers, 64, "receipt.containers").map((value, index) => {
+    const field = `receipt.containers[${index}]`, row = object(value, ["id", "role"], field);
+    return { id: pattern(row.id, ID, `${field}.id`), role: choice(row.role, ["candidate", "evaluator", "other"], `${field}.role`) };
+  });
+  if (raw.mounts !== undefined) receipt.mounts = array(raw.mounts, 256, "receipt.mounts").map((value, index) => {
+    const field = `receipt.mounts[${index}]`, row = object(value, ["container", "path", "readOnly", "purpose"], field);
+    if (typeof row.readOnly !== "boolean") fail(`${field}.readOnly`, "expected a boolean");
+    return { container: pattern(row.container, ID, `${field}.container`), path: text(row.path, `${field}.path`), readOnly: row.readOnly,
+      purpose: choice(row.purpose, ["evaluator-code", "evaluator-data", "candidate-output", "other"], `${field}.purpose`) };
+  });
+  if (raw.network !== undefined) receipt.network = choice<NonNullable<AttemptReceiptV1["network"]>>(raw.network, ["none", "restricted", "open"], "receipt.network");
+  if (raw.resourceLimits !== undefined) receipt.resourceLimits = array(raw.resourceLimits, 16, "receipt.resourceLimits").map((value, index) => {
+    const field = `receipt.resourceLimits[${index}]`, row = object(value, ["name", "value", "unit"], field);
+    if (typeof row.value !== "number" || !Number.isFinite(row.value) || row.value < 0) fail(`${field}.value`, "expected a nonnegative finite number");
+    return { name: text(row.name, `${field}.name`), value: row.value, unit: text(row.unit, `${field}.unit`) };
+  });
+  if (raw.startedAt !== undefined) receipt.startedAt = integer(raw.startedAt, "receipt.startedAt");
+  if (raw.endedAt !== undefined) receipt.endedAt = integer(raw.endedAt, "receipt.endedAt");
+  if (receipt.startedAt !== undefined && receipt.endedAt !== undefined && receipt.endedAt < receipt.startedAt) fail("receipt.endedAt", "precedes startedAt");
+  if (raw.exitStatus !== undefined) receipt.exitStatus = integer(raw.exitStatus, "receipt.exitStatus", Number.MIN_SAFE_INTEGER);
+  if (raw.outputs !== undefined) receipt.outputs = array(raw.outputs, 64, "receipt.outputs").map((value, index) => output(value, `receipt.outputs[${index}]`));
+  if (raw.metricsFile !== undefined) receipt.metricsFile = output(raw.metricsFile, "receipt.metricsFile");
+  return bounded(receipt, "receipt");
+}
+
+/** Predicate on evidence only; callers must verify its signature before treating sealing as attested. */
+export function runnerSealing(receipt: AttemptReceiptV1): boolean {
+  const parsed = parseAttemptReceipt(receipt), containers = parsed.containers ?? [], mounts = parsed.mounts ?? [];
+  const roles = new Map(containers.map(container => [container.id, container.role]));
+  if (roles.size !== containers.length || !containers.some(container => container.role === "candidate")
+    || !containers.some(container => container.role === "evaluator") || !mounts.length) return false;
+  let evaluatorEvidence = false;
+  for (const mount of mounts) {
+    const role = roles.get(mount.container);
+    if (!role) return false;
+    if (mount.purpose === "evaluator-code" || mount.purpose === "evaluator-data") {
+      if (role !== "evaluator" || !mount.readOnly) return false;
+      evaluatorEvidence = true;
+    }
+  }
+  return evaluatorEvidence;
+}
+
+/** Pure verification against the current host-supplied registration and attempt identity. No host-observed or scientific claim. */
+export function verifyAttemptReceipt(input: unknown, signature: unknown, context: RunnerVerificationContext): {
+  receipt: AttemptReceiptV1; provenance: "runner-attested"; sealed: boolean;
+} {
+  const receipt = parseAttemptReceipt(input), runners = parseResearchRunners(context.runners);
+  if (!Object.hasOwn(runners, receipt.runner)) fail("receipt.runner", "unknown runner");
+  const runner = runners[receipt.runner]!;
+  if (runner.revoked) fail("receipt.runner", "revoked runner");
+  if (receipt.projectId !== context.projectId || !runner.projects.includes(receipt.projectId)) fail("receipt.projectId", "project is not allowed");
+  const attempt = context.attempt;
+  if (!attempt || attempt.id !== receipt.attemptId || attempt.projectId !== context.projectId || attempt.protocolHash !== receipt.protocolHash)
+    fail("receipt.attemptId", "attempt or protocol identity mismatch");
+  if (receipt.codeCommit !== undefined && attempt.codeCommit !== undefined && receipt.codeCommit !== attempt.codeCommit)
+    fail("receipt.codeCommit", "protocol commit mismatch");
+  const bytes = base64(signature, 64, "receipt.signature");
+  const key = createPublicKey({ key: Buffer.from(runner.publicKey, "base64"), format: "der", type: "spki" });
+  if (!verify(null, Buffer.from(RUNNER_RECEIPT_DOMAIN + canonicalJson(receipt), "utf8"), key, bytes)) fail("receipt.signature", "invalid signature");
+  return { receipt, provenance: "runner-attested", sealed: runnerSealing(receipt) };
+}