@staix/agent-hub 0.24.0 → 0.26.0

package/src/hub/db-schema.ts

@@ -0,0 +1,143 @@
+import { constants, Database } from "bun:sqlite";
+export type { Database } from "bun:sqlite";
+import { closeSync, lstatSync, openSync, readSync, statSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { VERSION } from "../version.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
+
+/** Bump only for an incompatible hub.db format; compatible releases keep the introducing version. */
+export const HUB_DB_SCHEMA = 2;
+/** New/legacy databases keep format 1 until an incompatible record is committed. */
+export const HUB_DB_BASE_SCHEMA = 1;
+/** schema is the maximum supported format, never a request to migrate an existing compatible database. */
+export interface HubDbSchemaReader { schema: number; version: string }
+export interface HubDatabaseOptions {
+  readonly?: boolean;
+  create?: boolean;
+  reader?: HubDbSchemaReader;
+}
+export class HubDbSchemaError extends Error {
+  readonly code = "HUB_DB_SCHEMA";
+  constructor(message: string, readonly requiredVersion?: string) { super(message); this.name = "HubDbSchemaError"; }
+}
+interface HubDbSchema { schema: number; requiredVersion: string }
+const VERSION_TEXT = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?(?:\+[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/;
+const safeVersion = (value: unknown): value is string => typeof value === "string" && value.length <= 64 && VERSION_TEXT.exec(value)?.[0] === value;
+const defaultReader = (): HubDbSchemaReader => ({ schema: HUB_DB_SCHEMA, version: VERSION });
+const invalidSchema = () => new HubDbSchemaError("this project's hub.db schema metadata is invalid; inspect or restore the database before starting agent-hub");
+const busy = (error: unknown): boolean => {
+  const value = error as { code?: unknown; message?: unknown } | null;
+  return typeof value?.code === "string" && /^SQLITE_(BUSY|LOCKED)(?:_|$)/.test(value.code)
+    || typeof value?.message === "string" && /database (?:is )?(?:locked|busy)|database table is locked/i.test(value.message);
+};
+function readerValue(reader: HubDbSchemaReader): HubDbSchemaReader {
+  if (!reader || !Number.isSafeInteger(reader.schema) || reader.schema < 1 || !safeVersion(reader.version)) throw invalidSchema();
+  return { schema: reader.schema, version: reader.version };
+}
+
+/** No persistent PRAGMA or schema/data write runs while reading the marker. */
+function schemaOn(db: Database): HubDbSchema | undefined {
+  try {
+    const entries = db.query("SELECT type FROM sqlite_master WHERE name='hub_schema' COLLATE NOCASE LIMIT 2").all() as { type: string }[];
+    if (!entries.length) return undefined;
+    if (entries.length !== 1 || entries[0]!.type !== "table") throw invalidSchema();
+    const rows = db.query("SELECT id,schema,CASE WHEN typeof(required_version)='text' AND length(CAST(required_version AS BLOB))<=64 THEN required_version END AS required_version FROM hub_schema LIMIT 2")
+      .all() as { id: number; schema: number; required_version: string | null }[];
+    const row = rows[0];
+    if (rows.length !== 1 || !row || row.id !== 1 || !Number.isSafeInteger(row.schema) || row.schema < 1 || !safeVersion(row.required_version)) throw invalidSchema();
+    return { schema: row.schema, requiredVersion: row.required_version };
+  } catch (error) {
+    // Native corruption is unreadable storage, not a parsed schema claim; reset may archive it intact.
+    const code = (error as { code?: unknown } | null)?.code;
+    if (error instanceof HubDbSchemaError || busy(error) || typeof code === "string" && /^(?:SQLITE_NOTADB|SQLITE_CORRUPT)(?:_|$)/.test(code)) throw error;
+    throw invalidSchema();
+  }
+}
+function checkOn(db: Database, reader: HubDbSchemaReader): HubDbSchema | undefined {
+  const stored = schemaOn(db);
+  if (stored && stored.schema > reader.schema) throw new HubDbSchemaError(`this project was opened by agent-hub ${stored.requiredVersion}; use ${stored.requiredVersion} or later`, stored.requiredVersion);
+  return stored;
+}
+function existingFile(file: string): boolean {
+  if (file === ":memory:") return false;
+  let info;
+  try { info = lstatSync(file); }
+  catch (error) { if ((error as { code?: string }).code === "ENOENT") return false; throw error; }
+  // A dangling link or non-file is unknown storage, never a missing legacy database.
+  if (info.isSymbolicLink()) { try { info = statSync(file); } catch { throw invalidSchema(); } }
+  if (!info.isFile()) throw invalidSchema();
+  return true;
+}
+
+/** Closed, checkpointed WAL files need a quiet metadata probe on macOS; unknown file/mode state never qualifies. */
+function checkpointedWal(file: string): boolean {
+  let fd: number | undefined;
+  try {
+    fd = openSync(file, "r");
+    const header = Buffer.alloc(20);
+    return readSync(fd, header, 0, header.length, 0) === header.length && header.toString("ascii", 0, 15) === "SQLite format 3"
+      && header[15] === 0 && header[18] === 2 && header[19] === 2;
+  } catch { return false; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+function noSidecars(file: string): boolean {
+  for (const suffix of ["-wal", "-shm", "-journal"]) {
+    try { lstatSync(`${file}${suffix}`); return false; }
+    catch (error) { if ((error as { code?: string }).code !== "ENOENT") return false; }
+  }
+  return true;
+}
+function probeCompatible(file: string, reader: HubDbSchemaReader, quiet: boolean): void {
+  const uri = pathToFileURL(file); uri.searchParams.set("immutable", "1");
+  const db = quiet ? new Database(uri.href, constants.SQLITE_OPEN_READONLY | constants.SQLITE_OPEN_URI) : new Database(file, { readonly: true, create: false });
+  try {
+    db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`); // connection-local, not persisted
+    checkOn(db, reader);
+  } finally { db.close(); }
+}
+
+/** Live WAL reads may take SHM read locks. Refusal performs no SQL/schema/data or DB/WAL write; SHM locks are SQLite's ceiling. */
+export function assertHubDbCompatible(file: string, reader: HubDbSchemaReader = defaultReader()): void {
+  const supported = readerValue(reader);
+  if (!existingFile(file)) return;
+  if (checkpointedWal(file) && noSidecars(file)) {
+    // This handle is short-lived and never escapes. A live returned handle must continue observing later WAL commits.
+    let failure: unknown, failed = false;
+    try { probeCompatible(file, supported, true); } catch (error) { failure = error; failed = true; }
+    if (!noSidecars(file)) { probeCompatible(file, supported, false); return; }
+    if (failed) throw failure;
+    return;
+  }
+  probeCompatible(file, supported, false);
+}
+
+/** Every hub.db writer enters here before its own persistent PRAGMAs, migrations or maintenance writes. */
+export function openHubDatabase(file: string, options: HubDatabaseOptions = {}): Database {
+  const reader = readerValue(options.reader ?? defaultReader());
+  // Refuse a future file without opening a writable connection, which can perform SQLite recovery work itself.
+  assertHubDbCompatible(file, reader);
+  const db = new Database(file, options.readonly ? { readonly: true, create: false } : { readwrite: true, create: options.create ?? true });
+  try {
+    db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    if (options.readonly) { checkOn(db, reader); return db; }
+    // The second read and legacy baseline stamp share the writer lock, without filesystem work in SQL.
+    // Existing compatible markers never advance here; an incompatible migration must advance its marker with its actual DDL/data transaction.
+    db.transaction(() => {
+      const stored = checkOn(db, reader);
+      if (!stored) {
+        db.run("CREATE TABLE hub_schema (id INTEGER PRIMARY KEY CHECK(id=1),schema INTEGER NOT NULL,required_version TEXT NOT NULL)");
+        db.query("INSERT INTO hub_schema(id,schema,required_version) VALUES(1,?,?)").run(HUB_DB_BASE_SCHEMA, VERSION);
+      }
+    }).immediate();
+    return db;
+  } catch (error) { db.close(); throw error; }
+}
+
+/** The format marker advances only in the same transaction as the incompatible data it protects. */
+export function advanceHubDbSchema(db: Database, schema: number, requiredVersion: string): void {
+  if (!db.inTransaction || !Number.isSafeInteger(schema) || schema < HUB_DB_BASE_SCHEMA || schema > HUB_DB_SCHEMA || !safeVersion(requiredVersion))
+    throw new HubDbSchemaError("hub.db schema advance requires an active data transaction and a supported format");
+  const stored = checkOn(db, defaultReader());
+  if (!stored) throw invalidSchema();
+  if (stored.schema < schema) db.query("UPDATE hub_schema SET schema=?,required_version=? WHERE id=1").run(schema, requiredVersion);
+}

package/src/hub/delivery-journal.ts

@@ -1,12 +1,12 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { Database } from "bun:sqlite";
+import type { Database } from "./db-schema.ts";
+import { openHubDatabase } from "./db-schema.ts";
 import type { BusSnapshot } from "./bus.ts";
 import type { QueuePressure } from "./queue-backpressure.ts";
 import { HUB, KINDS, USER, type Envelope, type Kind } from "./envelope.ts";
 import { heldDeliveryHints } from "./delivery-hints.ts";
 import { processLiveness } from "../pi/process-signature.ts";
-import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import { parseRemotePeerId } from "../rooms/application.ts";
 import { validateDeferredHub } from "./deferred-hub.ts";
 
@@ -282,8 +282,7 @@ export class DeliveryJournal {
     this.operationId = options.operationId;
     this.terminalHistoryLimit = options.terminalHistoryLimit;
     mkdirSync(dirname(options.file), { recursive: true, mode: 0o700 });
-    this.db = new Database(options.file, { create: true });
-    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    this.db = openHubDatabase(options.file, { create: true });
     this.harden();
     this.db.run("PRAGMA journal_mode = WAL");
     this.db.run("PRAGMA synchronous = FULL");

package/src/hub/envelope.ts

@@ -19,6 +19,8 @@ export interface Envelope {
   refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; reviewRevision?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; planReview?: number; planReviewFlow?: number; planAuthor?: string; backlog?: number[]; supervision?: boolean; supervisionKey?: string; completedFor?: number; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[]; invocation?: string; invocationRemote?: true };
   /** The body must not be shown outside its recipients: console tail and log print a stub instead (PII tasks). */
   private?: boolean;
+  /** Sent by a distinct session (`<peer>~<origin>`, agent-hub#1036): a connection that named a peer id but is not that peer's current session. It grants nothing; it marks the sender for the log. */
+  session?: true;
   ts: number;
 }
 

package/src/hub/events.ts

@@ -22,7 +22,10 @@ export type HubEvent =
   | { type: "config_edit"; file: "config.local.json" | "sdlc.toml"; paths: { path: string; before: string | null; after: string | null }[]; fileBefore: string; fileAfter: string; tier: 2 | 3; by: "person"; source: "dashboard" | "terminal"; backup?: string; reason?: string }
   /** #445 C2: an invocation's ids, class and outcome. Never an argument, a result or a description. */
   | { type: "invocation"; id: string; caller: string; target: string; capability: string; class: string; outcome: string; task?: number; bytes?: number }
-  | { type: "envelope"; id: string; from: string; to?: string[]; priority: string; hop: number; kind?: string; task?: string; bytes?: number; private?: boolean; dropped?: string }
+  /** `origin` (#604 PR B): the sending connection's role, peer and launch or instance id. Never a path or text; absent for an envelope the hub itself wrote. */
+  | { type: "envelope"; id: string; from: string; to?: string[]; priority: string; hop: number; kind?: string; task?: string; bytes?: number; private?: boolean; dropped?: string; origin?: import("./provenance.ts").Origin }
+  /** #604 PR B: one per peer-role or tools-role hello, with the same fields an envelope's `origin` carries. No cwd, root or token. */
+  | ({ type: "attach" } & import("./provenance.ts").Origin)
   | { type: "overflow" | "undeliverable"; id: string; from: string; peer: string }
   | { type: "stale"; id: string; from: string; peer: string; task?: string }
   | { type: "quiet"; id: string; from: string; peers: string[] }

package/src/hub/execution-budget.ts

@@ -1,6 +1,6 @@
 import { definitionOf, type KindMap } from "../adapters/registry.ts";
-import { Database } from "bun:sqlite";
-import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
+import type { Database } from "./db-schema.ts";
+import { openHubDatabase } from "./db-schema.ts";
 
 export type ExecutionUnit = "model_calls" | "tool_calls" | "elapsed_ms" | "tokens";
 export type ExecutionBudgetLimits = Partial<Record<ExecutionUnit, number>>;
@@ -43,8 +43,7 @@ const validLimits = (raw: ExecutionBudgetLimits): ExecutionBudgetLimits => {
 export class ExecutionBudget {
   private readonly db: Database;
   constructor(path: string, private readonly instances?: KindMap) {
-    this.db = new Database(path, { create: true });
-    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    this.db = openHubDatabase(path, { create: true });
     this.db.run("PRAGMA journal_mode = WAL");
     this.db.run(`CREATE TABLE IF NOT EXISTS execution_budgets (
       id TEXT PRIMARY KEY, kind TEXT NOT NULL, task_id INTEGER, peers TEXT NOT NULL,
@@ -91,6 +90,18 @@ export class ExecutionBudget {
     return this.scopes(taskIds, peer).length > 0;
   }
 
+  /** Capability comes from the resolved instance definition, never the peer's spelling. */
+  instrumented(peer: string): boolean { return definitionOf(peer, this.instances)?.budget?.instrumented === true; }
+
+  /** The named budget must cover this task and owner; another applicable budget proves nothing. */
+  covers(id: string, taskId: number, peer: string, resources: readonly ExecutionUnit[]): boolean {
+    if (!this.instrumented(peer) || !resources.every(unit => UNITS.has(unit) && unit !== "tokens")) return false;
+    const row = this.scopes([taskId], peer).find(row => row.id === id);
+    if (!row) return false;
+    const limits = fromRow(row).limits;
+    return resources.every(unit => limits[unit] !== undefined && !(unit === "model_calls" && limits.tokens !== undefined));
+  }
+
   private scopes(taskIds: number[], peer: string): BudgetRow[] {
     const ids = [...new Set(taskIds.filter((id) => Number.isSafeInteger(id) && id > 0))];
     const taskRows = ids.length

package/src/hub/folder-trigger.ts

@@ -1,10 +1,10 @@
-import { Database } from "bun:sqlite";
+import type { Database } from "./db-schema.ts";
+import { openHubDatabase } from "./db-schema.ts";
 import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync, realpathSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
 import { createHash } from "node:crypto";
 import { isDenied } from "../local/deny.ts";
 import { checkCorpusRoot } from "./corpus.ts";
-import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import { realPath } from "./project.ts";
 import { folderGlobMatches, MAX_NEW_PER_POLL, type FolderEntry, type FolderRunResult, type FolderScan, type ScannedFile } from "./schedules.ts";
 import { MAX_SOURCE_BYTES, screenRegistration, type SourceRegistry } from "./sources.ts";
@@ -169,8 +169,7 @@ export interface FolderSeenRow { trigger: string; real_path: string; size: numbe
 export class FolderStore {
   private readonly db: Database;
   constructor(dbPath: string) {
-    this.db = new Database(dbPath, { create: true });
-    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    this.db = openHubDatabase(dbPath, { create: true });
     this.db.run("CREATE TABLE IF NOT EXISTS folder_seen (trigger TEXT NOT NULL, real_path TEXT NOT NULL, size INTEGER NOT NULL, mtime INTEGER NOT NULL, sha256 TEXT NOT NULL, task INTEGER, at INTEGER NOT NULL, PRIMARY KEY (trigger, real_path, sha256))");
     this.db.run("CREATE INDEX IF NOT EXISTS folder_seen_hash ON folder_seen (trigger, sha256)");
     this.db.run("CREATE TABLE IF NOT EXISTS folder_poll (trigger TEXT PRIMARY KEY, started INTEGER NOT NULL, baselined INTEGER NOT NULL DEFAULT 0, last_poll INTEGER, last_error TEXT)");

package/src/hub/handoff.ts

@@ -0,0 +1,126 @@
+// Cross-project task handoff (#604, agent-hub#1030). Pure: values in, values out, no clock, no file system, no socket. The daemon, the registry and the control client are
+// passed in as data or as small ports, so every refusal here is testable without a second daemon and the policy cannot drift from what the daemon enforces.
+import { CLASSES, type TaskClass } from "./board.ts";
+
+/**
+ * What crosses projects, and nothing else: no memory, evidence, turn content or task history (#1030 design 5). The per-field limits alone allow about 13 KB, so `bodyBytes` is the real
+ * ceiling on the whole request: a body that fills several fields is refused whole, and no partial task is built from it.
+ */
+export const HANDOFF_LIMITS = Object.freeze({ title: 300, detail: 4000, paths: 16, path: 512, issue: 2_000_000_000, bodyBytes: 8 * 1024 });
+export const HANDOFF_FIELDS = Object.freeze(["project", "title", "class", "detail", "paths", "issue", "task"] as const);
+
+export type HandoffRefusalCode =
+  | "invalid" | "too_large" | "unregistered" | "same_project" | "not_running" | "older_target" | "pii_turn" | "pii_task" | "no_authority";
+
+/** A refusal always names its reason, and for the person-fixable ones the action. The code is for tests and logs, the message for the caller. */
+export class HandoffRefusal extends Error {
+  constructor(readonly code: HandoffRefusalCode, message: string) { super(message); this.name = "HandoffRefusal"; }
+}
+
+/** `task` is the caller's OWN task this handoff comes from, so a `[pii]` one is refused and the target can name it in the follow-back. It never crosses as text. */
+export interface HandoffRequest { title: string; class: TaskClass; detail: string; paths: string[]; issue?: number; task?: number }
+
+const hasControl = (text: string): boolean => /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(text);
+
+/**
+ * Callers are models, and MCP schemas are not enforced on the way in: parse closed. An unknown field, an accessor or a non-plain object is refused, never dropped,
+ * because a dropped field is a request the caller thinks it made. The result is sized, so an oversized body is refused whole and no partial task is built from it.
+ */
+export function parseHandoff(input: unknown): HandoffRequest & { project: string } {
+  if (!input || typeof input !== "object" || Array.isArray(input) || ![Object.prototype, null].includes(Object.getPrototypeOf(input)) || Object.getOwnPropertySymbols(input).length)
+    throw new HandoffRefusal("invalid", "handoff must be a plain data object");
+  const descriptors = Object.getOwnPropertyDescriptors(input);
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (!(HANDOFF_FIELDS as readonly string[]).includes(key)) throw new HandoffRefusal("invalid", `handoff has an unknown field: ${key.slice(0, 40)}`);
+    if (!Object.hasOwn(descriptor, "value")) throw new HandoffRefusal("invalid", `handoff field ${key} is an accessor`);
+  }
+  const field = (name: (typeof HANDOFF_FIELDS)[number]): unknown => descriptors[name]?.value;
+  const text = (value: unknown, name: string, max: number, required: boolean): string => {
+    if (value === undefined || value === null || value === "") { if (required) throw new HandoffRefusal("invalid", `handoff ${name} is required`); return ""; }
+    if (typeof value !== "string") throw new HandoffRefusal("invalid", `handoff ${name} must be text`);
+    if (hasControl(value)) throw new HandoffRefusal("invalid", `handoff ${name} has control characters`);
+    if (Buffer.byteLength(value, "utf8") > max * 4) throw new HandoffRefusal("too_large", `handoff ${name} is over ${max} characters`);
+    if ([...value].length > max) throw new HandoffRefusal("too_large", `handoff ${name} is over ${max} characters`);
+    return value;
+  };
+  const project = text(field("project"), "project", HANDOFF_LIMITS.path, true).trim();
+  if (!project) throw new HandoffRefusal("invalid", "handoff project is required");
+  const title = text(field("title"), "title", HANDOFF_LIMITS.title, true).replace(/\s+/g, " ").trim();
+  if (!title) throw new HandoffRefusal("invalid", "handoff title is required");
+  const detail = text(field("detail"), "detail", HANDOFF_LIMITS.detail, false);
+  const cls = field("class") === undefined || field("class") === null || field("class") === "" ? "implement" : field("class");
+  if (typeof cls !== "string" || !(CLASSES as readonly string[]).includes(cls)) throw new HandoffRefusal("invalid", `handoff class must be one of ${CLASSES.join(", ")}`);
+  const rawPaths = field("paths");
+  if (rawPaths !== undefined && rawPaths !== null && (!Array.isArray(rawPaths) || Object.keys(rawPaths).length !== rawPaths.length)) throw new HandoffRefusal("invalid", "handoff paths must be a dense list of text");
+  if (Array.isArray(rawPaths) && rawPaths.length > HANDOFF_LIMITS.paths) throw new HandoffRefusal("too_large", `handoff has more than ${HANDOFF_LIMITS.paths} paths`);
+  const paths = (Array.isArray(rawPaths) ? rawPaths : []).map(path => {
+    const value = text(path, "path", HANDOFF_LIMITS.path, true).trim();
+    // Paths are the target's, repository-relative: an absolute path or a parent step names a place on this machine, not a file in the target's tree.
+    if (!value || value.startsWith("/") || value.startsWith("~") || /^[A-Za-z]:[\\/]/.test(value) || value.split(/[\\/]/).includes("..")) throw new HandoffRefusal("invalid", "handoff paths are repository-relative: no absolute path, ~ or ..");
+    return value;
+  });
+  const rawIssue = field("issue");
+  let issue: number | undefined;
+  if (rawIssue !== undefined && rawIssue !== null && rawIssue !== "") {
+    issue = typeof rawIssue === "string" && /^[1-9]\d{0,9}$/.test(rawIssue) ? Number(rawIssue) : rawIssue as number;
+    if (typeof issue !== "number" || !Number.isSafeInteger(issue) || issue < 1 || issue > HANDOFF_LIMITS.issue) throw new HandoffRefusal("invalid", "handoff issue must be a positive issue number in the target's repository");
+  }
+  const rawTask = field("task");
+  let task: number | undefined;
+  if (rawTask !== undefined && rawTask !== null && rawTask !== "") {
+    task = typeof rawTask === "string" && /^[1-9]\d{0,9}$/.test(rawTask) ? Number(rawTask) : rawTask as number;
+    if (typeof task !== "number" || !Number.isSafeInteger(task) || task < 1 || task > HANDOFF_LIMITS.issue) throw new HandoffRefusal("invalid", "handoff task must be a positive task id of this project");
+  }
+  const request = { project, title, class: cls as TaskClass, detail, paths, ...(issue === undefined ? {} : { issue }), ...(task === undefined ? {} : { task }) };
+  if (Buffer.byteLength(JSON.stringify(request), "utf8") > HANDOFF_LIMITS.bodyBytes) throw new HandoffRefusal("too_large", `handoff is over ${HANDOFF_LIMITS.bodyBytes} bytes`);
+  return request;
+}
+
+export interface RegisteredProject { id: string; root: string; stateDir: string }
+export interface TargetDescriptor { features?: readonly string[]; instanceId?: string; projectId?: string; cwd?: string }
+
+/**
+ * The target is named by canonical root or id and must be registered. The caller's own project and an unregistered name are refused here, before anything is read from a
+ * state directory. `canonical` resolves a typed path the way the registry does (`realPath`, never `realpathSync`), so a symlinked temporary root matches its registration.
+ */
+export function resolveTarget(name: string, projects: readonly RegisteredProject[], self: { id: string; root: string }, canonical: (path: string) => string): RegisteredProject {
+  const typed = name.trim();
+  let resolved: string | undefined;
+  try { resolved = typed.startsWith("/") || typed.startsWith("~") || typed.startsWith(".") ? canonical(typed) : undefined; } catch { resolved = undefined; }
+  const match = projects.find(project => project.id === typed || (resolved !== undefined && project.root === resolved));
+  if (!match) throw new HandoffRefusal("unregistered", "that project is not in this machine's agent-hub registry; run `ahub projects` to see the registered ones, or `ahub up` in that project once");
+  if (match.id === self.id || match.root === self.root) throw new HandoffRefusal("same_project", "that is this project: a task for this project goes through hub_task_propose");
+  return match;
+}
+
+/** What the target's own status descriptor says. A daemon that is not running, or does not know the handoff, is refused with the person's action. */
+export function checkTarget(project: RegisteredProject, descriptor: TargetDescriptor | undefined): void {
+  if (!descriptor) throw new HandoffRefusal("not_running", `the hub of ${project.id} is not running; run \`ahub up\` in ${project.root}, then hand the task off again (handoffs are not queued)`);
+  if (descriptor.projectId !== undefined && descriptor.projectId !== project.id) throw new HandoffRefusal("not_running", `the hub answering for ${project.root} belongs to another project; run \`ahub up\` in ${project.root}`);
+  if (!descriptor.features?.includes("task_handoff")) throw new HandoffRefusal("older_target", `the hub of ${project.id} is too old to take a handoff (no task_handoff feature): upgrade the target hub with \`ahub upgrade\` in ${project.root}`);
+}
+
+/** The states a target reports back, in the order a task can reach them. `declined` is the owner passing; the task then returns to the target's routing, so it is information, not an end. */
+export const HANDOFF_EVENTS = Object.freeze(["accepted", "in_review", "approved", "declined", "cancelled"] as const);
+export type HandoffEvent = (typeof HANDOFF_EVENTS)[number];
+
+/** Map a target's task history entry to the event the origin is told about, or undefined for every other entry. Reads only the event name and the task state, never a note. */
+export function handoffEventFor(entryEvent: string, state: string): HandoffEvent | undefined {
+  // The names are what `Tasks` writes (observed: accept writes "accepted", a done leaves the task in_review, the verdict writes "approved", a decline "declined", a cancel "cancelled").
+  if (entryEvent === "accepted" && state === "in_progress") return "accepted";
+  if (entryEvent === "declined") return "declined";
+  if (entryEvent === "cancelled" && state === "cancelled") return "cancelled";
+  if (entryEvent === "done" && state === "in_review") return "in_review";
+  if (entryEvent === "approved" && state === "approved") return "approved";
+  // A class with no reviewer: the done itself approves (`in_progress -> approved`), so the origin hears "approved" for that entry, not "in review".
+  if (entryEvent === "done" && state === "approved") return "approved";
+  return undefined;
+}
+
+const SHA = /^[0-9a-f]{40}$/;
+/** One line, no free text from the target beyond a PR number and a head: `agent-hub task 123 approved: PR #7 at <sha>`. */
+export function followBackLine(remoteTask: number, event: HandoffEvent, evidence: { pr?: unknown; head?: unknown } = {}): string {
+  const pr = typeof evidence.pr === "number" && Number.isSafeInteger(evidence.pr) && evidence.pr > 0 ? ` PR #${evidence.pr}` : "";
+  const head = typeof evidence.head === "string" && SHA.test(evidence.head) ? ` at ${evidence.head}` : "";
+  return `agent-hub task ${remoteTask} ${event.replace("_", " ")}${pr || head ? `:${pr}${head}` : ""}`;
+}

package/src/hub/hub-tools.ts

@@ -8,7 +8,7 @@ import { NOTE_KINDS } from "./envelope.ts";
 
 /** Restricted to the fixed current-child tools server, never an ordinary peer tool. */
 /** The fixed MCP surface of a current owned implementer child; independent of broader project roles. */
-export const IMPLEMENTER_HUB_TOOL_NAMES: readonly string[] = Object.freeze(["hub_task_accept", "hub_task_decline", "hub_task_done", "hub_checkpoint", "hub_send", "hub_task_show", "hub_task_propose", "hub_remember", "hub_inbox", "hub_permission_request"]);
+export const IMPLEMENTER_HUB_TOOL_NAMES: readonly string[] = Object.freeze(["hub_task_accept", "hub_task_decline", "hub_task_done", "hub_checkpoint", "hub_send", "hub_task_show", "hub_task_propose", "hub_remember", "hub_inbox", "hub_permission_request", "hub_study_show", "hub_study_handoff"]);
 
 export const IMPLEMENTER_PERMISSION_TOOL = {
   name: "hub_permission_request",
@@ -81,6 +81,10 @@ const tool = (name: string, description: string, properties: Record<string, unkn
   inputSchema: { type: "object", properties, required, additionalProperties: false },
 });
 
+/** #601: a campaign's contract and handoff are model-written text about its sources. The write tools' arguments and every study result stay out of memory capture. */
+export const STUDY_TOOLS = new Set(["hub_study_draft", "hub_study_revise", "hub_study_show", "hub_study_handoff"]);
+/** #604: a handoff's arguments cross to another project, so neither tool's arguments nor result are captured to memory. */
+export const HANDOFF_TOOLS = new Set(["hub_task_handoff", "hub_task_handoffs"]);
 export const BOUNDED_TASK_TOOLS = new Set(["hub_task_spec", "hub_check_start", "hub_check_result", "hub_check_cancel"]);
 /** #445 C1: what a peer lists and publishes. Their text is another agent's words, so neither call is captured to memory. */
 export const CAPABILITY_TOOLS = new Set(["hub_capabilities", "hub_capabilities_publish", "hub_invoke"]);
@@ -96,6 +100,12 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_backlog_pull", "Reserve a WIP slot and pull ready unpinned backlog work into To Do at its current revision. Preserves person order/reservations and frozen scope; pending unowned work can be undone with hub_backlog_undo.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, ["id", "revision", "reason"]),
   tool("hub_backlog_split", "Split unstarted backlog work into two to eight staged parts. The original card retains integration/acceptance and depends on the children. Use after for existing prerequisite ids and afterParts for earlier zero-based part indexes. Latest unused unchanged children can be undone with hub_backlog_undo.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", minLength: 1, maxLength: 1000 }, parts: { type: "array", minItems: 2, maxItems: 8, items: { type: "object", properties: { title: { type: "string", minLength: 1, maxLength: 300 }, detail: { type: "string", maxLength: 8000 }, class: str, refs, plan, after: { type: "array", maxItems: 64, uniqueItems: true, items: { type: "integer", minimum: 1 } }, afterParts: { type: "array", maxItems: 8, uniqueItems: true, items: { type: "integer", minimum: 0 } } }, required: ["title"], additionalProperties: false } } }, ["id", "revision", "reason", "parts"]),
   tool("hub_backlog_undo", "Undo your latest planning change at its current revision. Refuses intervening changes and another actor's edit.", { id, revision: { type: "integer", minimum: 1 } }, ["id", "revision"]),
+  tool("hub_study_draft", "Store a research campaign contract as a DRAFT revision 1 on an approved parent task. Configured planners only; it creates no task, dispatches nothing and never approves (only the person approves, with ahub study approve). The contract is data: question, scope, exclusions, sourceIds, units, deliverableSections, stopPolicy and an optional budget.", { parentTaskId: id, contract: { type: "object" } }, ["parentTaskId", "contract"]),
+  tool("hub_study_revise", "Store the next DRAFT revision of a research campaign with the revision you read. Configured planners only; a stale revision refuses, and a draft holds older bound work until the person approves it. Never approves.", { id: str, revision: { type: "integer", minimum: 1 }, contract: { type: "object" } }, ["id", "revision", "contract"]),
+  tool("hub_study_show", "Read a research campaign's coverage and stop projection: per unit round, state, handoff completeness and budget support, and why dispatch is held. Read-only. A private campaign, task or source shows ids, counts and states only, never its question, scope, path or excerpt. Give no id to list this project's campaigns, at most 50 per call: when the reply carries `next`, pass it as `after` for the following page.", { id: str, after: str }),
+  tool("hub_task_handoff", "Hand work that belongs to ANOTHER project that runs agent-hub to that project's board. Use it instead of implementing it from this session: a feature or behavior change first needs a spec issue in that project (pass its number as issue); a mechanical chore (an exact version pin, a regenerated file) goes straight to a task. The target is a registered project (its root or id) whose hub is running; it is not queued. Planner, conductor or person only. Never for a [pii] task or during a private turn. You learn the task's state changes as kind task messages.", { project: str, title: str, class: { type: "string", description: "task class, default implement" }, detail: str, paths: { type: "array", items: str, description: "repository-relative paths in the TARGET project" }, issue: { type: "integer", minimum: 1, description: "the target repository's issue number" }, task: { type: "integer", minimum: 1, description: "your own task in THIS project that this work comes from; a [pii] task is refused" } }, ["project", "title"]),
+  tool("hub_task_handoffs", "List what this project handed to other projects, with the last state each target reported. Read-only.", {}),
+  tool("hub_study_handoff", "Record the handoff for the research unit you currently own and have in progress: evidence per source, unresolved questions, contradictions and limitations, or insufficientEvidence. Only the bound owner; every required field must be present. Not a task completion.", { handoff: { type: "object" } }, ["handoff"]),
   tool("hub_release_new", "Create a future release planning row. Planner/person only; no activation, publish or release authorization.", { name: { type: "string", minLength: 1, maxLength: 64 }, goal: { type: "string", minLength: 1, maxLength: 1000 }, order: { type: "integer", minimum: 0 } }, ["name", "goal", "order"]),
   tool("hub_release_report", "Read a planned release's task readiness and recorded metrics. Planner/person only. A due date never waives unfinished scope.", { id }, ["id"]),
   tool("hub_release_assign", "Assign or move only a task's release, retaining its execution state and owner. Planner/person only; requires a reason and current planning revision. Frozen scope refuses.", { id, revision: { type: "integer", minimum: 0 }, release: { type: ["integer", "null"], minimum: 1 }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, ["id", "revision", "release", "reason"]),
@@ -184,7 +194,7 @@ export function configuredToolContext(status: unknown, peer: string): ProjectToo
   return { startPeers, readOnly: readOnlyPeers.includes(peer) };
 }
 
-const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_capabilities", "hub_send", "hub_inbox", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "hub_source_read", "hub_status"]);
+const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_capabilities", "hub_send", "hub_inbox", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_study_show", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "hub_source_read", "hub_status"]);
 /** Publication restricts exposure only; server-side authority remains mandatory for every call. */
 export function projectToolList<T extends { name: string }>(tools: T[], readOnly = false): T[] {
   return readOnly ? tools.filter(tool => READ_ONLY_PROJECT_TOOLS.includes(tool.name)) : tools;

package/src/hub/invocations.ts

@@ -1,9 +1,9 @@
 // #445 C2: read invocations. A peer asks the hub to have another peer run one capability the person shared; the target runs it in its own turn with its own
 // permissions, and the hub returns a bounded, sanitized, hub-headed result to the caller only. This file is the pure part (the gates, the argument check, the
 // two texts the hub writes) and the ledger (an ids-only `invocations` table in hub.db). It never reads a peer, a socket or the bus.
-import { Database } from "bun:sqlite";
+import type { Database } from "./db-schema.ts";
+import { openHubDatabase } from "./db-schema.ts";
 import { createHash } from "node:crypto";
-import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import { MAX_HOP, sanitize } from "./envelope.ts";
 import type { FlatSchema, ShareState, SideEffect } from "./capabilities.ts";
 
@@ -230,8 +230,7 @@ function validateRelay(row: InvocationRow, relay: Omit<InvocationRelay, "local"
 export class InvocationLedger {
   private readonly db: Database;
   constructor(path: string, private readonly now: () => number = Date.now) {
-    this.db = new Database(path, { create: true });
-    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    this.db = openHubDatabase(path, { create: true });
     this.db.run("PRAGMA journal_mode = WAL");
     this.db.run(`CREATE TABLE IF NOT EXISTS invocations (
       id TEXT PRIMARY KEY, trace TEXT NOT NULL, caller TEXT NOT NULL, target TEXT NOT NULL, capability TEXT NOT NULL, digest TEXT NOT NULL,