@staix/agent-hub 0.12.23 → 0.12.24

package/src/hub/sdlc.ts

@@ -0,0 +1,250 @@
+import { phaseReceipt, type PhaseReceipt, type PhaseView } from "./workflow.ts";
+import { constants, openSync, fstatSync, readSync, closeSync } from "node:fs";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { childEnv, stopOwnedProcess } from "./child-process.ts";
+
+export const SDLC_STAGES = ["spec", "plan", "implement", "review", "verify", "merge", "release"] as const;
+export type SdlcBaseStage = typeof SDLC_STAGES[number];
+export type SdlcStage = string;
+export type StageGate = "issue" | "pr" | "local" | "review" | "checks" | "phase";
+export interface StageDefinition { base: SdlcBaseStage; actor: string; entry_gates: StageGate[]; exit_gates: StageGate[]; after: string[]; }
+export type SdlcMode = "off" | "advise" | "enforce";
+export interface SdlcConfig { workflow?: "gsd-lite"; mode: SdlcMode; requiredChecks: string[]; stages: SdlcStage[]; definitions?: Record<string, StageDefinition>; }
+export interface SdlcReceipt {
+  stage: SdlcStage;
+  phase?: PhaseReceipt;
+  repo?: string;
+  issue?: number;
+  pr?: number;
+  head?: string;
+  reviewedHead?: string;
+  localHead?: string;
+  localResult?: "passed" | "failed" | "unknown";
+  observed?: number;
+}
+export interface PrEvidence {
+  head: string;
+  state: "OPEN" | "MERGED" | "CLOSED";
+  checks: { name: string; state: "passed" | "failed" | "pending" | "unknown" }[];
+  review: "approved" | "changes_requested" | "unknown";
+  unresolved: number | null;
+  pendingReviews: number | null;
+  paths: string[];
+  pathsComplete?: boolean;
+  draft?: boolean;
+  base?: string;
+  baseHead?: string;
+  mergeCommit?: string;
+}
+const sha = (value: unknown): value is string => typeof value === "string" && /^[0-9a-f]{40}$/.test(value);
+const repo = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value) && !value.startsWith("-");
+const id = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+
+const STAGE_ID = /^[a-z][a-z0-9_-]{0,47}$/;
+const STAGE_GATES: StageGate[] = ["issue", "pr", "local", "review", "checks", "phase"];
+const baseActor = (base: SdlcBaseStage) => base === "review" || base === "verify" ? "reviewer" : base === "merge" || base === "release" ? "person" : "owner/planner";
+export function stageDefinition(config: SdlcConfig, stage: string): StageDefinition | undefined {
+  if (!config.stages.includes(stage)) return undefined;
+  if (config.definitions && Object.hasOwn(config.definitions, stage)) return config.definitions[stage];
+  if (!(SDLC_STAGES as readonly string[]).includes(stage)) return undefined;
+  const base = stage as SdlcBaseStage;
+  return { base, actor: baseActor(base), entry_gates: [], exit_gates: [], after: [] };
+}
+export function lifecycleStage(config: SdlcConfig, base: SdlcBaseStage): string {
+  return config.stages.find(stage => stageDefinition(config, stage)?.base === base) ?? base;
+}
+function definitions(raw: unknown, stages: unknown): { stages: string[]; definitions: Record<string, StageDefinition> } {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw) || Object.keys(raw).length > 32) throw new Error("sdlc.definitions: expected at most 32 stage definitions");
+  if (!Array.isArray(stages) || !stages.length || stages.length > 32 || stages.some(s => typeof s !== "string" || !STAGE_ID.test(s)) || new Set(stages).size !== stages.length) throw new Error("sdlc.stages: expected 1..32 distinct bounded stage ids");
+  const result: Record<string, StageDefinition> = Object.create(null);
+  for (const [id, value] of Object.entries(raw)) {
+    if (!STAGE_ID.test(id) || !stages.includes(id) || !value || typeof value !== "object" || Array.isArray(value)) throw new Error("sdlc.definitions: invalid or unlisted stage");
+    const def = value as Record<string, unknown>;
+    if (Object.keys(def).some(k => !["base", "actor", "entry_gates", "exit_gates", "after"].includes(k)) || !(SDLC_STAGES as readonly unknown[]).includes(def.base)) throw new Error("sdlc.definitions: unknown field or base");
+    const base = def.base as SdlcBaseStage;
+    if ((SDLC_STAGES as readonly string[]).includes(id) && id !== base) throw new Error("sdlc.definitions: built-in stage base cannot change");
+    const actor = def.actor ?? baseActor(base);
+    if (typeof actor !== "string" || actor !== baseActor(base) && !["owner", "reviewer", "person", "planner"].includes(actor)) throw new Error("sdlc.definitions.actor: unknown actor");
+    const gates = (key: string): StageGate[] => {
+      const list = def[key] ?? [];
+      if (!Array.isArray(list) || list.length > 6 || list.some(g => !STAGE_GATES.includes(g)) || new Set(list).size !== list.length) throw new Error(`sdlc.definitions.${key}: unknown or duplicate gate`);
+      return [...list] as StageGate[];
+    };
+    const after = def.after ?? [];
+    if (!Array.isArray(after) || after.length > 8 || after.some(a => typeof a !== "string" || !stages.includes(a) || stages.indexOf(a) >= stages.indexOf(id)) || new Set(after).size !== after.length) throw new Error("sdlc.definitions.after: dependencies must be distinct earlier stages (no missing, self, forward or cyclic edge)");
+    result[id] = { base, actor: actor as string, entry_gates: gates("entry_gates"), exit_gates: gates("exit_gates"), after: [...after] as string[] };
+  }
+  const config = { stages, definitions: result } as SdlcConfig;
+  if (stages.some(s => !stageDefinition(config, s)) || !["review", "merge"].every(base => stages.some(s => stageDefinition(config, s)?.base === base))) throw new Error("sdlc.stages: define every custom id and include review and merge base destinations");
+  return { stages: [...stages], definitions: result };
+}
+
+export function sdlcConfig(value: unknown): SdlcConfig {
+  if (value === undefined) return { mode: "off", requiredChecks: [], stages: [...SDLC_STAGES] };
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("sdlc: expected a table");
+  const raw = value as Record<string, unknown>;
+  for (const key of Object.keys(raw)) if (!["mode", "required_checks", "stages", "workflow", "definitions"].includes(key)) throw new Error(`sdlc.${key}: unknown field`);
+  const mode = raw.mode ?? "off";
+  if (mode !== "off" && mode !== "advise" && mode !== "enforce") throw new Error("sdlc.mode: expected off, advise or enforce");
+  const workflow = raw.workflow ?? "none";
+  if (workflow !== "none" && workflow !== "gsd-lite") throw new Error("sdlc.workflow: expected none or gsd-lite");
+  const checks = raw.required_checks ?? [];
+  if (!Array.isArray(checks) || checks.length > 32 || checks.some(c => typeof c !== "string" || !c.trim() || c.length > 120 || /[\r\n\x00-\x1f]/.test(c)) || new Set(checks).size !== checks.length) throw new Error("sdlc.required_checks: expected at most 32 unique nonempty names");
+  if (raw.definitions !== undefined) {
+    const custom = definitions(raw.definitions, raw.stages);
+    if (workflow !== "gsd-lite" && Object.values(custom.definitions).some(d => [...d.entry_gates, ...d.exit_gates].includes("phase"))) throw new Error("sdlc.definitions: phase gates require workflow = gsd-lite");
+    return { mode, requiredChecks: [...checks] as string[], ...custom, ...(workflow === "gsd-lite" ? { workflow } : {}) };
+  }
+  const stages = raw.stages ?? [...SDLC_STAGES];
+  if (!Array.isArray(stages) || stages.length !== SDLC_STAGES.length || stages.some((stage, i) => stage !== SDLC_STAGES[i])) throw new Error("sdlc.stages: use spec, plan, implement, review, verify, merge, release in that order; custom stages are not supported yet");
+  return { mode, requiredChecks: [...checks] as string[], stages: [...stages] as SdlcStage[], ...(workflow === "gsd-lite" ? { workflow } : {}) };
+}
+
+export function loadSdlc(cwd: string): SdlcConfig {
+  try {
+    const fd = openSync(join(cwd, ".agenthub", "sdlc.toml"), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+      const before = fstatSync(fd), cap = 64 * 1024;
+      if (!before.isFile() || before.nlink !== 1 || before.size > cap) throw new Error("sdlc.toml must be a regular single-link file within 64 KiB");
+      const bytes = Buffer.alloc(cap + 1); let length = 0, n = 0;
+      while ((n = readSync(fd, bytes, length, bytes.length - length, null)) > 0) { length += n; if (length > cap) throw new Error("sdlc.toml exceeds 64 KiB"); }
+      const after = fstatSync(fd);
+      if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || length !== after.size) throw new Error("sdlc.toml changed during read");
+      return sdlcConfig(Bun.TOML.parse(bytes.subarray(0, length).toString("utf8")));
+    } finally { closeSync(fd); }
+  }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return sdlcConfig(undefined); throw error; }
+}
+
+/** Identities and claimed local receipts only. External facts are read, never accepted as input. */
+export function sdlcReceipt(value: unknown, previous: SdlcReceipt | undefined = undefined, config: SdlcConfig = sdlcConfig(undefined)): SdlcReceipt {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("sdlc receipt: expected an object");
+  const raw = value as Record<string, unknown>;
+  for (const key of Object.keys(raw)) if (!["stage", "repo", "issue", "pr", "reviewedHead", "localHead", "localResult", "phase"].includes(key)) throw new Error(`sdlc receipt.${key}: unsupported or externally observed field`);
+  previous ??= { stage: config.stages[0] ?? "spec" };
+  const next = { ...previous };
+  if (raw.phase !== undefined) next.phase = phaseReceipt(raw.phase);
+  if (raw.stage !== undefined) {
+    if (typeof raw.stage !== "string" || !stageDefinition(config, raw.stage)) throw new Error("sdlc receipt.stage: unknown stage");
+    next.stage = raw.stage as SdlcStage;
+  }
+  if (raw.repo !== undefined) { if (!repo(raw.repo)) throw new Error("sdlc receipt.repo: expected owner/repository"); next.repo = raw.repo; }
+  for (const key of ["issue", "pr"] as const) if (raw[key] !== undefined) { if (!id(raw[key])) throw new Error(`sdlc receipt.${key}: expected a positive integer`); next[key] = raw[key]; }
+  for (const key of ["reviewedHead", "localHead"] as const) if (raw[key] !== undefined) { if (!sha(raw[key])) throw new Error(`sdlc receipt.${key}: expected a full lowercase SHA`); next[key] = raw[key]; }
+  if (raw.localResult !== undefined) {
+    if (!["passed", "failed", "unknown"].includes(String(raw.localResult))) throw new Error("sdlc receipt.localResult: expected passed, failed or unknown");
+    next.localResult = raw.localResult as SdlcReceipt["localResult"];
+  }
+  // A new artifact cannot inherit another PR's review or local gate.
+  if (next.repo !== previous.repo || next.pr !== previous.pr) {
+    delete next.head; delete next.observed;
+    if (raw.phase === undefined) delete next.phase;
+    if (raw.reviewedHead === undefined) delete next.reviewedHead;
+    if (raw.localHead === undefined) delete next.localHead;
+    if (raw.localResult === undefined) delete next.localResult;
+  }
+  return next;
+}
+
+export function parsePrEvidence(value: unknown): PrEvidence {
+  const p = value as Record<string, any>;
+  if (!p || !sha(p.headRefOid) || !["OPEN", "CLOSED", "MERGED"].includes(p.state) || !Array.isArray(p.statusCheckRollup) || !Array.isArray(p.files) || p.files.length > 1000) throw new Error("PR readback: invalid or incomplete structured evidence");
+  const checks = p.statusCheckRollup.map((c: Record<string, unknown>) => {
+    const name = c.name ?? c.context;
+    if (typeof name !== "string" || !name || name.length > 120) throw new Error("PR readback: invalid check identity");
+    const native = c.conclusion ?? c.state;
+    const state = native === "SUCCESS" ? "passed" : ["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED"].includes(String(native)) ? "failed" : ["PENDING", "QUEUED", "IN_PROGRESS"].includes(String(c.status ?? native)) ? "pending" : "unknown";
+    return { name, state } as PrEvidence["checks"][number];
+  });
+  const paths = p.files.map((f: Record<string, unknown>) => { if (typeof f.path !== "string" || !f.path || f.path.length > 1000) throw new Error("PR readback: invalid file identity"); return f.path; });
+  return { head: p.headRefOid, state: p.state, checks, paths, pathsComplete: Number.isSafeInteger(p.changedFiles) && p.changedFiles >= 0 && p.changedFiles === paths.length, ...(typeof p.isDraft === "boolean" ? { draft: p.isDraft } : {}), ...(typeof p.baseRefName === "string" && p.baseRefName && p.baseRefName.length <= 200 && !/[\x00-\x1f\x7f]/.test(p.baseRefName) ? { base: p.baseRefName } : {}), ...(sha(p.baseRefOid) ? { baseHead: p.baseRefOid } : {}),
+    review: p.reviewDecision === "APPROVED" ? "approved" : p.reviewDecision === "CHANGES_REQUESTED" ? "changes_requested" : "unknown",
+    pendingReviews: Array.isArray(p.reviewRequests) && p.reviewRequests.length <= 100 && p.reviewRequests.every((r: unknown) => !!r && typeof r === "object") ? p.reviewRequests.length : null,
+    unresolved: Number.isSafeInteger(p.unresolvedThreads) && p.unresolvedThreads >= 0 ? p.unresolvedThreads : null,
+    ...(sha(p.mergeCommit?.oid) ? { mergeCommit: p.mergeCommit.oid } : {}) };
+}
+
+export interface SdlcStatus { workflow?: "gsd-lite"; phase?: PhaseView; mode: SdlcMode; stage: SdlcStage; definition?: StageDefinition; entry?: string[]; exit?: string[]; blockers: string[]; ready: boolean; actor: string; next: string; }
+export function sdlcStatus(config: SdlcConfig, receipt: SdlcReceipt | undefined, evidence?: PrEvidence, phase?: PhaseView): SdlcStatus {
+  const stage = receipt?.stage ?? config.stages[0] ?? "spec", blockers: string[] = [];
+  const definition = stageDefinition(config, stage);
+  if (!definition) blockers.push("lifecycle stage definition unknown");
+  if (!receipt?.repo || !receipt.issue) blockers.push("issue identity missing");
+  if (!receipt?.pr) blockers.push("PR identity missing");
+  if (!evidence) blockers.push("current PR evidence unknown");
+  else {
+    if (evidence.state !== "OPEN") blockers.push("PR is not open");
+    if (receipt?.reviewedHead !== evidence.head) blockers.push("current head has not been reviewed");
+    if (receipt?.localHead !== evidence.head || receipt.localResult !== "passed") blockers.push("local gate on current head missing or failed");
+    if (!config.requiredChecks.length) blockers.push("required check set unknown");
+    for (const name of config.requiredChecks) {
+      const matches = evidence.checks.filter(c => c.name === name);
+      if (!matches.length || matches.some(c => c.state !== "passed")) blockers.push(`required check ${name}: not successful on current head`);
+    }
+    if (evidence.review !== "approved") blockers.push("GitHub review approval missing or changes requested");
+    if (evidence.pendingReviews !== 0) blockers.push("review requests pending or unknown");
+    if (evidence.unresolved !== 0) blockers.push("review threads unresolved or unknown");
+  }
+  if (config.workflow === "gsd-lite") {
+    blockers.unshift(...(phase?.blockers ?? ["phase board evidence unknown"]));
+    if (!evidence || receipt?.phase?.head !== evidence.head) blockers.push("phase checklist head missing or stale");
+  }
+  const custom = config.definitions && definition ? stageGates(definition, blockers, receipt, evidence, phase) : undefined;
+  if (custom) for (const blocker of [...custom.entry, ...custom.exit]) if (!blockers.includes(blocker)) blockers.push(blocker);
+  return { ...(config.workflow ? { workflow: config.workflow, ...(phase ? { phase } : {}) } : {}), ...(custom ? { definition, ...custom } : {}), mode: config.mode, stage, blockers, ready: blockers.length === 0,
+    actor: !definition ? "person" : phase?.blockers.length ? "reviewer/person" : config.definitions && definition ? definition.actor : stage === "review" || stage === "verify" ? "reviewer" : stage === "merge" || stage === "release" ? "person" : "owner/planner",
+    next: blockers[0] ?? "person may inspect merge readiness; no automatic merge" };
+}
+
+function stageGates(def: StageDefinition, blockers: string[], receipt: SdlcReceipt | undefined, evidence: PrEvidence | undefined, phase: PhaseView | undefined): { entry: string[]; exit: string[] } {
+  const select = (gates: StageGate[]) => [...new Set(gates.flatMap(gate => {
+    if (gate === "phase") return [...(phase?.blockers ?? ["phase board evidence unknown"]), ...(!evidence || receipt?.phase?.head !== evidence.head ? ["phase checklist head missing or stale"] : [])];
+    const matching = (text: string) => gate === "issue" ? text === "issue identity missing" : gate === "pr" ? ["PR identity missing", "current PR evidence unknown", "PR is not open"].includes(text) : gate === "local" ? ["current PR evidence unknown", "local gate on current head missing or failed"].includes(text) : gate === "checks" ? text === "current PR evidence unknown" || text === "required check set unknown" || text.startsWith("required check ") : ["current PR evidence unknown", "current head has not been reviewed", "GitHub review approval missing or changes requested", "review requests pending or unknown", "review threads unresolved or unknown"].includes(text);
+    return blockers.filter(matching);
+  }))];
+  return { entry: select(def.entry_gates), exit: select(def.exit_gates) };
+}
+
+export function touchingPrs(prs: { pr: number; paths: string[] }[]): { before: number; after: number; paths: string[] }[] {
+  const conflicts: ReturnType<typeof touchingPrs> = [];
+  for (let i = 0; i < prs.length; i++) for (const right of prs.slice(i + 1)) {
+    const left = prs[i]!, paths = [...new Set(left.paths.filter(path => right.paths.includes(path)))].sort();
+    if (paths.length) conflicts.push({ before: left.pr, after: right.pr, paths });
+  }
+  return conflicts;
+}
+
+export type SdlcGh = (args: string[], timeoutMs?: number, cwd?: string, maxOutputBytes?: number) => Promise<{ code: number; stdout: string }>;
+/** Read-only, fixed argv. Output and time are bounded; diagnostics never expose credentials or remote text. */
+export const sdlcGh: SdlcGh = (args, timeoutMs = 10_000, cwd, maxOutputBytes = 256 * 1024) => new Promise((resolve) => {
+  const outputLimit = Number.isSafeInteger(maxOutputBytes) ? Math.min(2 * 1024 * 1024, Math.max(1, maxOutputBytes)) : 256 * 1024;
+  const child = spawn("gh", args, { ...(cwd ? { cwd } : {}), env: childEnv(), detached: true, stdio: ["ignore", "pipe", "ignore"] });
+  let stdout = "", failed = false;
+  const stop = () => { failed = true; void stopOwnedProcess(child, { group: true }).catch(() => {}); };
+  const timer = setTimeout(stop, Math.max(1, Math.min(10_000, timeoutMs)));
+  child.stdout?.setEncoding("utf8");
+  child.stdout?.on("data", chunk => { if (failed) return; stdout += chunk.toString(); if (Buffer.byteLength(stdout) > outputLimit) { stdout = ""; stop(); } });
+  child.once("error", () => { failed = true; clearTimeout(timer); resolve({ code: 1, stdout: "" }); });
+  child.once("close", code => { clearTimeout(timer); resolve({ code: failed ? 1 : code ?? 1, stdout: failed ? "" : stdout }); });
+});
+
+export async function readSdlcPr(receipt: SdlcReceipt, run: SdlcGh = sdlcGh): Promise<PrEvidence | undefined> {
+  if (!repo(receipt.repo) || !id(receipt.pr)) return undefined;
+  try {
+    const view = await run(["pr", "view", String(receipt.pr), "--repo", receipt.repo, "--json", "headRefOid,state,statusCheckRollup,reviewDecision,reviewRequests,files,changedFiles,mergeCommit,isDraft,baseRefName,baseRefOid"]);
+    if (view.code !== 0) return undefined;
+    const [owner, name] = receipt.repo.split("/");
+    const threads = await run(["api", "graphql", "-f", "query=query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){headRefOid reviewThreads(first:100){nodes{isResolved} pageInfo{hasNextPage}}}}}", "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${receipt.pr}`]);
+    const p = JSON.parse(view.stdout);
+    delete p.unresolvedThreads; // only the complete thread query can establish this fact
+    if (threads.code === 0) {
+      const current = JSON.parse(threads.stdout)?.data?.repository?.pullRequest;
+      const nodes = current?.reviewThreads?.nodes;
+      // Paginated or malformed thread data is unknown, never a clean review.
+      if (current?.headRefOid === p.headRefOid && current?.reviewThreads?.pageInfo?.hasNextPage === false && Array.isArray(nodes) && nodes.every(n => typeof n?.isResolved === "boolean")) p.unresolvedThreads = nodes.filter(n => !n.isResolved).length;
+      else if (current?.headRefOid && current.headRefOid !== p.headRefOid) return undefined;
+    }
+    return parsePrEvidence(p);
+  } catch { return undefined; }
+}

package/src/hub/settings.ts

@@ -1,3 +1,4 @@
+import { SUPPORTED_PEERS } from "./peer-catalog.ts";
 import { createHash } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -13,14 +14,15 @@ import { OVERLAY_FILE, overlayToml, parseOverlay, parseRouting, routingText, typ
  * written by either. Writes go only to the machine-local files (`.agenthub/config.local.json`,
  * `.agenthub/routing.local.toml`), never to a tracked one.
  */
-export const SETTING_PEERS = ["claude", "codex", "kimi", "pi", "local"] as const;
+export const SETTING_PEERS = SUPPORTED_PEERS;
 /** `null` removes the machine-local value, so the shared file's or the default applies again. */
-export type SettingValue = string | boolean | string[] | null;
+export type SettingValue = string | boolean | number | string[] | null;
 export interface SettingDef {
   key: string;
-  group: "Permissions" | "Start" | "Routing" | "Switches";
+  group: "Permissions" | "Start" | "Routing" | "Switches" | "Roster" | "Roles";
   label: string;
-  type: "enum" | "boolean" | "peers";
+  type: "enum" | "boolean" | "peers" | "roles" | "integer";
+  min?: number; max?: number;
   /** The closed values of an enum; a route setting takes the project's own route ids instead. */
   values?: readonly string[];
   /** `runtime` lives in the running hub only; the others are the machine-local file that holds the value. */
@@ -29,7 +31,7 @@ export interface SettingDef {
   applies: "live" | "peer start" | "hub start";
   /** `raises`: only a settings session or a person's terminal may set it, except to `floor`. */
   risk: "safe" | "raises";
-  floor?: string | boolean;
+  floor?: string | boolean | number;
   /** Where the value sits inside its file (or, for `runtime`, the peer). */
   path: readonly string[];
 }
@@ -43,8 +45,12 @@ const perClass = (name: TaskClass): SettingDef[] => [
   { key: `routing.classes.${name}.pi_backend`, group: "Routing", label: `${name}: Pi backend`, type: "enum", values: ["dgx", "mlx"], store: "routing", applies: "live", risk: "raises", path: ["classes", name, "pi_backend"] },
 ];
 export const SETTINGS: readonly SettingDef[] = [
-  ...SETTING_PEERS.map((peer): SettingDef => ({ key: `permission.${peer}`, group: "Permissions", label: `${peer}: mode now`, type: "enum", values: PERMISSION_MODES, store: "runtime", applies: "live", risk: "raises", floor: "ask", path: [peer] })),
-  ...SETTING_PEERS.map((peer): SettingDef => ({ key: `permission_modes.${peer}`, group: "Permissions", label: `${peer}: mode at hub start`, type: "enum", values: PERMISSION_MODES, store: "config", applies: "hub start", risk: "raises", floor: "ask", path: ["permission_modes", peer] })),
+  ...SETTING_PEERS.map((peer): SettingDef => ({ key: `tasks.wip_limits.${peer}`, group: "Routing", label: `${peer}: planner WIP limit`, type: "integer", min: 0, max: 32, store: "config", applies: "hub start", risk: "raises", floor: 0, path: ["tasks", "wip_limits", peer] })),
+  ...SETTING_PEERS.map((peer): SettingDef => ({ key: `catalog_roles.${peer}`, group: "Roles", label: `${peer}: catalog guidance`, type: "roles", store: "config", applies: "peer start", risk: "safe", path: ["catalog_roles", peer] })),
+  { key: "scoped_grants.protect_instructions", group: "Permissions", label: "Ask before writing instruction files", type: "boolean", store: "config", applies: "live", risk: "raises", floor: true, path: ["protect_instruction_files"] },
+  ...SETTING_PEERS.map((peer): SettingDef => ({ key: `roster.${peer}`, group: "Roster", label: `${peer}: participates`, type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["roster", peer] })),
+  ...SETTING_PEERS.filter(peer => peer !== "jcode").map((peer): SettingDef => ({ key: `permission.${peer}`, group: "Permissions", label: `${peer}: mode now`, type: "enum", values: PERMISSION_MODES, store: "runtime", applies: "live", risk: "raises", floor: "ask", path: [peer] })),
+  ...SETTING_PEERS.filter(peer => peer !== "jcode").map((peer): SettingDef => ({ key: `permission_modes.${peer}`, group: "Permissions", label: `${peer}: mode at hub start`, type: "enum", values: PERMISSION_MODES, store: "config", applies: "hub start", risk: "raises", floor: "ask", path: ["permission_modes", peer] })),
   ...START_MODE_PEERS.map((peer): SettingDef => ({ key: `peers.${peer}.start_mode`, group: "Start", label: `${peer}: start mode (tui unless set)`, type: "enum", values: START_MODES, store: "config", applies: "peer start", risk: "raises", floor: "tui", path: ["peers", peer, "start_mode"] })),
   { key: "pi.auto_start", group: "Start", label: "Start Pi with the hub", type: "boolean", store: "config", applies: "hub start", risk: "raises", floor: false, path: ["pi", "auto_start"] },
   { key: "routing.stay_switch", group: "Routing", label: "Stay or switch (hub/auto and stage routes)", type: "enum", values: ["off", "shadow", "enforce"], store: "routing", applies: "live", risk: "raises", path: ["stay_switch"] },
@@ -59,7 +65,7 @@ export const SETTINGS: readonly SettingDef[] = [
  * Never editable from settings, whatever the session: these choose what the hub executes or where secrets and task
  * text go. A key equal to an entry, or below it, is refused by name.
  */
-export const NEVER_EDITABLE = ["kimi_cmd", "codex_bin", "pi.cmd", "checks", "mlx", "omniroute", "memory.worker_url", "local.read_allow", "local.bash_network", "local.network_allow", "bench.enabled", "terminal"] as const;
+export const NEVER_EDITABLE = ["kimi_cmd", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "codex_bin", "pi.cmd", "checks", "mlx", "omniroute", "memory.worker_url", "local.read_allow", "local.bash_network", "local.network_allow", "bench.enabled", "terminal"] as const;
 
 /** The definition of a key, or why there is none. */
 export function settingDef(key: unknown): SettingDef | string {
@@ -76,10 +82,19 @@ export function checkSettingValue(def: SettingDef, raw: unknown, routes: readonl
     if (def.store === "runtime") throw new Error(`${def.key} has no stored value to remove`);
     return null;
   }
+  if (def.type === "integer") {
+    if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw < (def.min ?? 0) || raw > (def.max ?? Number.MAX_SAFE_INTEGER)) throw new Error(`${def.key} takes an integer from ${def.min ?? 0} to ${def.max ?? Number.MAX_SAFE_INTEGER}`);
+    return raw;
+  }
   if (def.type === "boolean") {
     if (typeof raw !== "boolean") throw new Error(`${def.key} takes true or false`);
     return raw;
   }
+  if (def.type === "roles") {
+    const allowed = def.values ?? routes;
+    if (!Array.isArray(raw) || raw.length > 2 || new Set(raw).size !== raw.length || raw.some(id => typeof id !== "string" || !allowed.includes(id))) throw new Error(`${def.key} takes at most two distinct compatible catalog ids; allowed: ${allowed.join(", ") || "(none)"}`);
+    return [...raw] as string[];
+  }
   if (def.type === "peers") {
     if (!Array.isArray(raw) || raw.length > PEERS_MAX || raw.some((p) => typeof p !== "string" || !PEER.test(p)) || new Set(raw).size !== raw.length) throw new Error(`${def.key} takes up to ${PEERS_MAX} distinct peer ids`);
     return [...(raw as string[])];
@@ -92,8 +107,9 @@ export function checkSettingValue(def: SettingDef, raw: unknown, routes: readonl
 /** A terminal's text for a value: `inherit` removes the machine-local value, a peers setting takes a comma list. */
 export function parseSettingText(def: SettingDef, text: string): unknown {
   if (text === "inherit") return null;
+  if (def.type === "integer") return /^(0|[1-9]\d*)$/.test(text) ? Number(text) : text;
   if (def.type === "boolean") return text === "true" ? true : text === "false" ? false : text;
-  if (def.type === "peers") return text.split(",").map((p) => p.trim()).filter(Boolean);
+  if (def.type === "peers" || def.type === "roles") return text.split(",").map((p) => p.trim()).filter(Boolean);
   return text;
 }
 export const settingText = (value: unknown): string => value === null || value === undefined ? "(not set)" : Array.isArray(value) ? value.join(",") || "(none)" : String(value);
@@ -101,7 +117,8 @@ export const settingText = (value: unknown): string => value === null || value =
 /** `ordinary`: a dashboard session from `ahub ui`. `settings`: one from `ahub ui --settings`. `terminal`: `ahub settings`. */
 export type SettingAuthority = "ordinary" | "settings" | "terminal";
 /** Why this authority may not set this value, or undefined. Removing a stored value can raise, so it counts as one. */
-export function settingRefusal(def: SettingDef, value: SettingValue, authority: SettingAuthority): string | undefined {
+export function settingRefusal(def: SettingDef | string, value: SettingValue, authority: SettingAuthority): string | undefined {
+  if (typeof def === "string") return def || "invalid setting definition";
   if (def.risk === "safe" || authority !== "ordinary") return undefined;
   if (value !== null && value === def.floor) return undefined;
   return `${def.key} can widen what agents do without asking: open a settings session with ahub ui --settings, or use ahub settings in a terminal`;
@@ -334,10 +351,10 @@ export function ignoredLine(ignored: readonly string[] | undefined, def: Setting
   });
 }
 export interface SettingRow {
-  key: string; group: SettingDef["group"]; label: string; type: SettingDef["type"]; values?: readonly string[];
+  key: string; group: SettingDef["group"]; label: string; type: SettingDef["type"]; values?: readonly string[]; min?: number; max?: number;
   /** The file a write goes to, or "this hub run". */
   file: string;
-  applies: SettingDef["applies"]; risk: SettingDef["risk"]; floor?: string | boolean;
+  applies: SettingDef["applies"]; risk: SettingDef["risk"]; floor?: string | boolean | number;
   /** What is in force now; null when nothing sets it. */
   value: SettingValue;
   /** Which file the value in force comes from. */
@@ -364,15 +381,16 @@ export function settingRows(input: {
   routingProblem?: string;
   /** The loader's own lines about machine-local fields it ignored (`HubConfig.ignored`). */
   ignored?: string[];
+  roles?: (peer: string) => { value: SettingValue; pending?: SettingValue; values: string[]; note?: string };
 }): SettingRow[] {
   const raw = (name: string): unknown => { try { return JSON.parse(readFileSync(join(input.cwd, ".agenthub", name), "utf8")); } catch { return undefined; } };
   const local = raw(CONFIG_LOCAL), shared = raw("config.json");
   const projectRouting = existsSync(join(input.cwd, ".agenthub", "routing.toml"));
   const routes = [...Object.keys(input.routing.routes), ...Object.keys(input.routing.hub_routes ?? {})];
-  const scalar = (value: unknown): SettingValue => typeof value === "string" || typeof value === "boolean" ? value : Array.isArray(value) ? value.map(String) : null;
+  const scalar = (value: unknown): SettingValue => typeof value === "string" || typeof value === "boolean" || typeof value === "number" ? value : Array.isArray(value) ? value.map(String) : null;
   return SETTINGS.map((def): SettingRow => {
-    const base = { key: def.key, group: def.group, label: def.label, type: def.type, applies: def.applies, risk: def.risk, ...(def.floor === undefined ? {} : { floor: def.floor }),
-      ...(def.group === "Permissions" ? { hint: permissionBoundary(def.path.at(-1)!) } : {}) };
+    const base = { key: def.key, group: def.group, label: def.label, type: def.type, ...(def.type === "integer" ? { min: def.min, max: def.max } : {}), applies: def.applies, risk: def.risk, ...(def.floor === undefined ? {} : { floor: def.floor }),
+      ...(def.key === "scoped_grants.protect_instructions" ? { hint: "AGENTS.md, CLAUDE.md and QWEN.md remain grantable by default; enabling this asks before scoped writes and edits" } : def.group === "Permissions" ? { hint: permissionBoundary(def.path.at(-1)!) } : {}) };
     if (def.store === "runtime") {
       const mode = input.mode(def.path[0]!);
       return { ...base, values: def.values!, file: "this hub run", value: mode.value ?? null, source: "this hub run", ...(mode.note ? { note: mode.note } : {}) };
@@ -382,6 +400,7 @@ export function settingRows(input: {
       return { ...base, ...(def.type === "enum" ? { values: def.values ?? routes } : {}), file: OVERLAY_FILE, value, source: input.routing.sources?.[def.key.slice("routing.".length)] ?? (value === null ? "default" : projectRouting ? "routing.toml" : "default"),
         ...(input.routingProblem ? { note: `the routing files do not load, so the last policy that did stays in force: ${input.routingProblem}` } : {}) };
     }
+    if (def.type === "roles" && input.roles) return { ...base, ...input.roles(def.path[1]!), file: CONFIG_LOCAL, source: valueAt(local, def.path) !== undefined ? CONFIG_LOCAL : valueAt(shared, def.path) !== undefined ? "config.json" : "profile/default", hint: "Guidance only; grants no tool or permission. At most two roles, applied at the next peer start." };
     const value = scalar(input.running(def.path));
     const stored = input.next ? scalar(input.next(def.path)) : value;
     const source = valueAt(local, def.path) !== undefined ? CONFIG_LOCAL : valueAt(shared, def.path) !== undefined ? "config.json" : "default";

package/src/hub/shipped-roles.ts

@@ -0,0 +1,25 @@
+import role0 from "../../templates/roles/dev/software-architect.md" with { type: "text" };
+import role1 from "../../templates/roles/dev/backend-engineer.md" with { type: "text" };
+import role2 from "../../templates/roles/dev/frontend-engineer.md" with { type: "text" };
+import role3 from "../../templates/roles/dev/test-engineer.md" with { type: "text" };
+import role4 from "../../templates/roles/dev/code-reviewer.md" with { type: "text" };
+import role5 from "../../templates/roles/dev/security-reviewer.md" with { type: "text" };
+import role6 from "../../templates/roles/research/research-lead.md" with { type: "text" };
+import role7 from "../../templates/roles/research/researcher.md" with { type: "text" };
+import role8 from "../../templates/roles/research/analyst.md" with { type: "text" };
+import role9 from "../../templates/roles/research/statistician.md" with { type: "text" };
+import role10 from "../../templates/roles/research/fact-checker.md" with { type: "text" };
+
+export const SHIPPED_ROLES: Readonly<Record<string, string>> = {
+  "software-architect": role0,
+  "backend-engineer": role1,
+  "frontend-engineer": role2,
+  "test-engineer": role3,
+  "code-reviewer": role4,
+  "security-reviewer": role5,
+  "research-lead": role6,
+  "researcher": role7,
+  "analyst": role8,
+  "statistician": role9,
+  "fact-checker": role10,
+};

package/src/hub/snapshots.ts

@@ -1,10 +1,11 @@
 import { Database } from "bun:sqlite";
-import { copyFileSync, existsSync, mkdtempSync, rmSync, statSync, utimesSync } from "node:fs";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { childEnv } from "./child-process.ts";
 import type { Touch } from "./conflicts.ts";
 import { hubGitSync } from "./git.ts";
+import { realPath } from "./project.ts";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 
 /**
@@ -15,10 +16,10 @@ import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
  * ponytail: the trees are unreferenced, so `git gc` may prune them after gc.pruneExpire (two weeks by default); undo
  * of an older turn says so. Refs under refs/agenthub/ would keep them, at the cost of showing up in the user's repo.
  */
-const git = (top: string, args: string[], env: Record<string, string> = {}) =>
-  hubGitSync(["-C", top, ...args], {
+const git = (top: string | Repo, args: string[], env: Record<string, string> = {}) =>
+  hubGitSync(repoGitArgs(top, args), {
     encoding: "utf8",
-    env: { ...childEnv(process.env), ...env },
+    env: { ...repoGitEnv(top), ...env },
     // These run inside the bus's state change: a hung git (a huge new directory, a stuck filter) must not freeze the hub.
     timeout: SNAPSHOT_TIMEOUT_MS,
   });
@@ -29,14 +30,73 @@ export interface Repo {
   top: string;
   dir: string;
   prefix: string;
+  shadow?: true;
+}
+
+/** Refuse links throughout metadata, including loose-object fan-outs and packed-object files. */
+function shadowStorageSafe(dir: string): boolean {
+  let entries = 0;
+  const visit = (path: string, depth: number): boolean => {
+    if (++entries > 20000 || depth > 32) return false;
+    const st = lstatSync(path);
+    if (st.isSymbolicLink()) return false;
+    if (st.isFile()) return st.nlink === 1;
+    if (!st.isDirectory()) return false;
+    return readdirSync(path).every(name => visit(join(path, name), depth + 1));
+  };
+  try {
+    if (lstatSync(join(dir, "commondir"), { throwIfNoEntry: false }) || lstatSync(join(dir, "objects/info/alternates"), { throwIfNoEntry: false })) return false;
+    return visit(dir, 0);
+  } catch { return false; }
+}
+/** Explicit flags keep the shadow work tree at its verified project root. */
+export function repoGitArgs(repo: string | Repo, args: string[]): string[] {
+  const top = typeof repo === "string" ? repo : repo.top;
+  if (typeof repo !== "string" && repo.shadow) {
+    const parent = lstatSync(join(repo.top, ".agenthub"), { throwIfNoEntry: false });
+    const ignore = parent?.isDirectory() && !parent.isSymbolicLink() ? lstatSync(join(repo.top, ".agenthub/ignore"), { throwIfNoEntry: false }) : undefined;
+    if (!parent?.isDirectory() || parent.isSymbolicLink() || ignore && (!ignore.isFile() || ignore.isSymbolicLink() || ignore.nlink !== 1) || repo.dir !== join(repo.top, ".agenthub/shadow.git") || !shadowStorageSafe(repo.dir)) throw new Error("shadow repository metadata is invalid or linked; operation refused");
+  }
+  return ["-C", top, ...(typeof repo !== "string" && repo.shadow ? ["--git-dir=" + repo.dir, "--work-tree=" + repo.top, "-c", "core.excludesFile=" + join(repo.top, ".agenthub", "ignore")] : []), ...args];
+}
+export function repoGitEnv(repo: string | Repo, env = process.env): NodeJS.ProcessEnv {
+  return { ...childEnv(env), ...(typeof repo !== "string" && repo.shadow ? { GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_SYSTEM: "/dev/null", GIT_ATTR_NOSYSTEM: "1" } : {}) };
 }
 
 /** The repository holding `root`, or undefined when it is not inside a work tree. */
 export function repoOf(root: string): Repo | undefined {
   const r = git(root, ["rev-parse", "--show-toplevel", "--absolute-git-dir", "--show-prefix"]);
-  if (r.status !== 0) return undefined;
-  const [top, dir, prefix = ""] = r.stdout.replace(/\n$/, "").split("\n");
-  return top && dir ? { top, dir, prefix } : undefined;
+  if (r.status === 0) {
+    const [top, dir, prefix = ""] = r.stdout.replace(/\n$/, "").split("\n");
+    if (top && dir) return { top, dir, prefix };
+  }
+  const top = realPath(root), hub = join(top, ".agenthub"), dir = join(hub, "shadow.git");
+  const parent = lstatSync(hub, { throwIfNoEntry: false });
+  if (!parent?.isDirectory() || parent.isSymbolicLink()) return undefined;
+  const own = lstatSync(dir, { throwIfNoEntry: false });
+  if (!own?.isDirectory() || own.isSymbolicLink()) return undefined;
+  for (const name of ["objects", "refs", "hooks", "info"]) { const st = lstatSync(join(dir, name), { throwIfNoEntry: false }); if (!st?.isDirectory() || st.isSymbolicLink()) return undefined; }
+  for (const file of ["config", "HEAD"]) { const st = lstatSync(join(dir, file), { throwIfNoEntry: false }); if (!st?.isFile() || st.isSymbolicLink() || st.nlink !== 1) return undefined; }
+  if (existsSync(join(dir, "commondir")) || existsSync(join(dir, "objects/info/alternates"))) return undefined;
+  const ignore = lstatSync(join(hub, "ignore"), { throwIfNoEntry: false });
+  if (ignore && (!ignore.isFile() || ignore.isSymbolicLink() || ignore.nlink !== 1)) return undefined;
+  if (!shadowStorageSafe(dir)) return undefined;
+  const repo: Repo = { top, dir: realPath(dir), prefix: "", shadow: true };
+  const probe = git(repo, ["rev-parse", "--absolute-git-dir"]);
+  return probe.status === 0 && realPath(probe.stdout.trim()) === repo.dir ? repo : undefined;
+}
+/** Opt-in creation only; a real repository is never replaced or modified. */
+export function initShadow(root: string): boolean {
+  const top = realPath(root), hub = join(top, ".agenthub"), dir = join(hub, "shadow.git"), existing = repoOf(top);
+  if (existing) { if (!existing.shadow) throw new Error("project already has a Git work tree; shadow mode is for non-git folders"); return false; }
+  const parent = lstatSync(hub, { throwIfNoEntry: false });
+  if (parent && (!parent.isDirectory() || parent.isSymbolicLink())) throw new Error(".agenthub must be a project directory, not a link");
+  if (lstatSync(dir, { throwIfNoEntry: false })) throw new Error("existing shadow metadata is invalid; nothing was replaced");
+  mkdirSync(hub, { recursive: true });
+  const result = hubGitSync(["init", "--bare", "--quiet", dir], { cwd: top, encoding: "utf8", timeout: SNAPSHOT_TIMEOUT_MS, env: { ...childEnv(process.env), GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_SYSTEM: "/dev/null" } });
+  if (result.status !== 0) throw new Error("could not initialize shadow repository");
+  writeFileSync(join(dir, "info/exclude"), ".agenthub/shadow.git/\n.agenthub/state/\n.agenthub/archive/\n.agenthub/config.local.json\n.agenthub/routing.local.toml\n", { mode: 0o600 });
+  return true;
 }
 
 /**
@@ -62,12 +122,12 @@ export function snapshot(repo: Repo): string | undefined {
       utimesSync(env.GIT_INDEX_FILE, atime, mtime);
     }
     // `ahub reset --all` archives hub.db (task text, PII included) under .agenthub/archive: never copy it either.
-    if (git(repo.top, ["add", "-A", "--", scope(repo), ":(exclude,glob)**/.agenthub/state/**", ":(exclude,glob)**/.agenthub/archive/**"], env).status !== 0) return undefined;
+    if (git(repo, ["add", "-A", "--", scope(repo), ":(exclude,glob)**/.agenthub/state/**", ":(exclude,glob)**/.agenthub/archive/**", ...(repo.shadow ? [":(exclude,glob)**/.agenthub/shadow.git/**"] : [])], env).status !== 0) return undefined;
     // The copy starts from the user's index: hub state somebody tracked or staged is still in it, and the exclude above
     // only keeps `add` from touching it. Take it out explicitly; -f because staged state the hub has rewritten since
     // matches neither HEAD nor the file, which `rm --cached` otherwise refuses. Only the copy changes.
-    if (git(repo.top, ["rm", "-r", "-f", "--cached", "--quiet", "--ignore-unmatch", "--", ":(glob)**/.agenthub/state/**", ":(glob)**/.agenthub/archive/**"], env).status !== 0) return undefined;
-    const r = git(repo.top, ["write-tree"], env);
+    if (git(repo, ["rm", "-r", "-f", "--cached", "--quiet", "--ignore-unmatch", "--", ":(glob)**/.agenthub/state/**", ":(glob)**/.agenthub/archive/**", ...(repo.shadow ? [":(glob)**/.agenthub/shadow.git/**"] : [])], env).status !== 0) return undefined;
+    const r = git(repo, ["write-tree"], env);
     return r.status === 0 ? r.stdout.trim() : undefined;
   } finally {
     rmSync(tmp, { recursive: true, force: true });
@@ -76,14 +136,14 @@ export function snapshot(repo: Repo): string | undefined {
 
 /** Project paths (relative to the top level) that differ between two trees. */
 export function changedPaths(repo: Repo, from: string, to: string): string[] {
-  const r = git(repo.top, ["diff-tree", "-r", "--no-renames", "--name-only", "-z", from, to, "--", scope(repo)]);
+  const r = git(repo, ["diff-tree", "-r", "--no-renames", "--name-only", "-z", from, to, "--", scope(repo)]);
   return r.status === 0 ? r.stdout.split("\0").filter(Boolean) : [];
 }
 
-const inTree = (top: string, tree: string, path: string) => git(top, ["rev-parse", "--verify", "--quiet", `${tree}:${path}`]).status === 0;
+const inTree = (top: string | Repo, tree: string, path: string) => git(top, ["rev-parse", "--verify", "--quiet", `${tree}:${path}`]).status === 0;
 
 /** Whether a snapshot's tree is still in the object store (`git gc` prunes unreferenced ones eventually). */
-export const hasTree = (top: string, tree: string): boolean => git(top, ["cat-file", "-e", `${tree}^{tree}`]).status === 0;
+export const hasTree = (top: string | Repo, tree: string): boolean => git(top, ["cat-file", "-e", `${tree}^{tree}`]).status === 0;
 
 export interface UndoPlan {
   restore: string[];
@@ -122,10 +182,10 @@ export function planUndo(repo: Repo, turn: { start_tree: string; end_tree: strin
 export function restore(repo: Repo, startTree: string, paths: string[]): void {
   // Removals first: after a case-only rename on a case-insensitive disk, `Foo.ts` and `foo.ts` are one file, and
   // removing the created spelling after restoring the old one would delete it.
-  const back = paths.filter((p) => inTree(repo.top, startTree, p));
+  const back = paths.filter((p) => inTree(repo, startTree, p));
   for (const path of paths.filter((p) => !back.includes(p))) rmSync(join(repo.top, path), { force: true });
   for (const path of back) {
-    if (git(repo.top, ["restore", `--source=${startTree}`, "--worktree", "--", literal(path)]).status !== 0) throw new Error(`could not restore ${path}`);
+    if (git(repo, ["restore", `--source=${startTree}`, "--worktree", "--", literal(path)]).status !== 0) throw new Error(`could not restore ${path}`);
   }
 }
 
@@ -156,6 +216,20 @@ export class Turns {
     // ponytail: rows of finished tasks stay (a few per file per task); prune by task state if hub.db ever grows.
     this.db.run("CREATE TABLE IF NOT EXISTS touches (task INTEGER NOT NULL, peer TEXT NOT NULL, path TEXT NOT NULL, at INTEGER NOT NULL, PRIMARY KEY (task, peer, path))");
     this.db.run("CREATE INDEX IF NOT EXISTS touches_path ON touches (path)"); // the PreToolUse hook looks up one path
+    this.db.run("CREATE TABLE IF NOT EXISTS task_snapshots (task INTEGER NOT NULL, proposed_at INTEGER NOT NULL, start_tree TEXT, PRIMARY KEY (task, proposed_at))");
+  }
+  /** A proposal's original project snapshot; task ids may be reused after reset. Never repair a missing baseline later. */
+  rememberTaskStart(task: number, proposedAt: number, tree: string | undefined): void {
+    this.db.query("INSERT OR IGNORE INTO task_snapshots (task, proposed_at, start_tree) VALUES (?, ?, ?)").run(task, proposedAt, tree ?? null);
+  }
+  taskStart(task: number, proposedAt: number): string | undefined {
+    try {
+      const row = this.db.query("SELECT start_tree FROM task_snapshots WHERE task = ? AND proposed_at = ?").get(task, proposedAt) as { start_tree: string | null } | null;
+      return row?.start_tree ?? undefined;
+    } catch (error) {
+      if (/no such table/.test((error as Error).message)) return undefined;
+      throw error;
+    }
   }
   begin(id: string, peer: string, startTree: string | undefined): void {
     this.db.query("INSERT OR REPLACE INTO turns (id, peer, started, start_tree) VALUES (?, ?, ?, ?)").run(id, peer, Date.now(), startTree ?? null);