@staix/agent-hub 0.12.34 → 0.12.35

package/src/cli/upgrade.ts

@@ -1,4 +1,5 @@
 import { definitionOf } from "../adapters/registry.ts";
+import { readInstanceConfig } from "../hub/instance-config.ts";
 import { LIVE_TEST_PERSON_REFUSAL } from "./identity.ts";
 import { checkedSessionPath } from "./recovery-session-file.ts";
 import { canChooseFresh, decodeRestoreReceipt, restoreReceiptStatus } from "./upgrade-restore-state.ts";
@@ -14,6 +15,13 @@ import { resolveAcceptedBinding, piArchiveExit, recordedPeerGuidance, type Recov
 import type { TerminalBinding } from "./terminal-recovery.ts";
 import { RecoveryPresentationError, type RecoveryPresentationCause, type RecoveryWaitTiming } from "./upgrade-presentation-data.ts";
 
+const projectDefinition = (peer: string, root?: string) => {
+  const builtin = definitionOf(peer);
+  if (builtin || !root) return builtin;
+  try { return definitionOf(peer, readInstanceConfig(root).instances); } catch { return undefined; }
+};
+
+
 export interface RecoveryPeer {
   id: string;
   state: string;
@@ -288,7 +296,8 @@ export function nextChoices(receipt: RecoveryOperation, runner?: number | "unkno
   const stuck = resumeBlocked(op, live);
   const selected = op.phase === "blocked" ? op.blockedReattachment : undefined;
   const repair = selected && op.projects.find(project => project.id === selected.projectId)?.reattachments?.[selected.peer];
-  const reattach = selected && repair && (repair.state === "ready" || repairWaiting(op, selected.projectId, selected.peer));
+  const reattach = selected && repair && projectDefinition(selected.peer, op.plan.projects.find(project => project.project.id === selected.projectId)?.project.root)?.session.launchRecord === true &&
+    (repair.state === "ready" || repairWaiting(op, selected.projectId, selected.peer));
   return [
     ...(stuck ? [] : [{ kind: "resume" as const, text: `${recoveryCommand(op, "resume")}${op.error ? " (after the next action in error)" : ""}${old ? ` (runs the coordinator that started this operation, which cannot re-prepare an expired hold: if it reports "source is no longer prepared", use ${abortable ? "abort or " : ""}stop-and-archive)` : ""}` }]),
     ...(abortable ? [{ kind: "abort" as const, text: recoveryCommand(op, "abort") }] : []),
@@ -323,12 +332,12 @@ export async function liveProjects(op: RecoveryOperation, inspect: (project: Pro
   return Object.fromEntries(await Promise.all(open.map(async (p) => [p.project.id, await inspect(p.project).catch(() => undefined)] as const)));
 }
 
-function missingRepair(op: RecoveryOperation, progress: ProjectProgress, peer: string): boolean {
+function missingRepair(op: RecoveryOperation, progress: ProjectProgress, peer: string, options: { authority?: "current" | "historical" } = {}): boolean {
   const evidence = op.missingRecordedSession;
   if (!evidence || evidence.projectId !== progress.id || evidence.peer !== peer || (!progress.repairedSessions?.[evidence.peer] && !Object.hasOwn(progress.reattachments ?? {}, peer))) return false;
   const planned = op.plan.projects.find(project => project.project.id === progress.id);
   if (!planned) return false;
-  try { return resolveAcceptedBinding(planned, progress, evidence.peer)?.sessionId === evidence.sessionId; } catch { return false; }
+  try { return resolveAcceptedBinding(planned, progress, evidence.peer, options)?.sessionId === evidence.sessionId; } catch { return false; }
 }
 /**
  * Peers of a project whose restoration failed and for which a fresh session is a real choice: not Pi (a restored hub
@@ -337,8 +346,8 @@ function missingRepair(op: RecoveryOperation, progress: ProjectProgress, peer: s
  */
 function failedPeers(op: RecoveryOperation, progress: ProjectProgress, live: Record<string, Inspection | undefined> = {}): string[] {
   const planned = op.plan.projects.find((p) => p.project.id === progress.id);
-  return Object.entries(progress.terminals).filter(([key, value]) => key.startsWith("restored:") && canChooseFresh(value)).map(([key]) => key.slice("restored:".length))
-    .filter((peer) => definitionOf(peer)?.session.personFresh === true && ((!Object.hasOwn(progress.reattachments ?? {}, peer) && !Object.hasOwn(progress.repairedSessions ?? {}, peer)) || missingRepair(op, progress, peer)) && !progress.fresh?.[peer] && (!planned?.freshStart?.includes(peer) || missingRepair(op, progress, peer)) && !plannedAttached(op, progress, peer, live));
+  return Object.entries(progress.terminals).filter(([key, value]) => key.startsWith("restored:") && (() => { try { return canChooseFresh(value); } catch { return false; } })()).map(([key]) => key.slice("restored:".length))
+    .filter((peer) => projectDefinition(peer, planned?.project.root)?.session.personFresh === true && ((!Object.hasOwn(progress.reattachments ?? {}, peer) && !Object.hasOwn(progress.repairedSessions ?? {}, peer)) || missingRepair(op, progress, peer)) && !progress.fresh?.[peer] && (!planned?.freshStart?.includes(peer) || missingRepair(op, progress, peer)) && !plannedAttached(op, progress, peer, live));
 }
 
 /** Read-only scope classification; it confers no delegation authority. */
@@ -364,7 +373,7 @@ function plannedAttached(op: RecoveryOperation, progress: ProjectProgress, peer:
     ? resolveAcceptedBinding(planned, progress, peer as RecoveryNativePeer)
     : (planned?.terminals as { peer: string; sessionId: string }[] | undefined)?.find((t) => t.peer === peer);
   const current = state?.state === "running" ? state.peers.find((p) => p.id === peer && p.state !== "offline") : undefined;
-  return !!binding && current?.[definitionOf(peer)?.session.idField ?? "sessionId"] === binding.sessionId;
+  return !!binding && current?.[projectDefinition(peer, planned?.project.root)?.session.idField ?? "sessionId"] === binding.sessionId;
 }
 
 /** Registry reads for planning must not create a registry or run migrations. */
@@ -414,7 +423,10 @@ function abandoned(op: RecoveryOperation): boolean {
   return true;
 }
 
-function validateReceipt(id: string, op: RecoveryOperation): void {
+function validateReceipt(id: string, op: RecoveryOperation, historical = false): void {
+  // Cleanup validates owned historical facts; this mode never authorizes restore, fresh or reattach.
+  const options = historical ? { authority: "historical" as const } : {};
+  const decode = (value: unknown) => decodeRestoreReceipt(value, options);
   if (!(op.schema === 1 || (op.schema === 2 && op.disposition)) || op.id !== id) throw new Error("unsupported operation receipt");
   if (op.targetFeatures !== undefined && (!Array.isArray(op.targetFeatures) || !op.targetFeatures.every(feature => typeof feature === "string" && feature.length > 0) || !op.targetRoot || !op.targetDigest)) throw new Error("invalid target features");
   const { fingerprint, ...reviewed } = op.plan;
@@ -425,13 +437,13 @@ function validateReceipt(id: string, op: RecoveryOperation): void {
     if (progress.repairedSessions !== undefined) {
       if (!object(progress.repairedSessions)) throw new Error("invalid repaired session provenance");
       for (const [peer, protectedSession] of Object.entries(progress.repairedSessions)) {
-        const restored = decodeRestoreReceipt(progress.terminals[`restored:${peer}`]);
+        const restored = decode(progress.terminals[`restored:${peer}`]);
         const bindings = [progress.reattachments?.[peer as RecoveryNativePeer]?.binding,
           restored?.state === "done" || restored?.state === "waiting" ? restored.binding : undefined,
           progress.terminals[`retired:${peer}`]];
         if (protectedSession !== true || !bindings.some(binding => {
           if (binding === undefined) return false;
-          const receipt = decodeRestoreReceipt({ state: "done", binding });
+          const receipt = decode({ state: "done", binding });
           return receipt?.state === "done" && receipt.binding.peer === peer && receipt.binding.projectRoot === op.plan.projects[index]?.project.root;
         })) throw new Error("repaired session provenance does not match its retained peer and project");
       }
@@ -440,14 +452,14 @@ function validateReceipt(id: string, op: RecoveryOperation): void {
       if (choice.repaired === undefined) continue;
       const planned = op.plan.projects[index]!;
       if (choice.repaired !== true || !progress.repairedSessions?.[peer as RecoveryNativePeer] ||
-          resolveAcceptedBinding(planned, progress, peer as RecoveryNativePeer)?.sessionId !== choice.lost) throw new Error("invalid one-use repaired-session choice");
+          resolveAcceptedBinding(planned, progress, peer as RecoveryNativePeer, options)?.sessionId !== choice.lost) throw new Error("invalid one-use repaired-session choice");
     }
     if (progress.reattachments === undefined) continue;
     if (!object(progress.reattachments)) throw new Error("invalid reattachment markers");
     for (const [peer, marker] of Object.entries(progress.reattachments)) {
-      if (definitionOf(peer)?.session.launchRecord !== true || !object(marker) || Object.keys(marker).some(key => !["state", "at", "cause", "binding"].includes(key)) ||
+      if ((!historical && projectDefinition(peer, op.plan.projects[index]?.project.root)?.session.launchRecord !== true) || !object(marker) || Object.keys(marker).some(key => !["state", "at", "cause", "binding"].includes(key)) ||
           !["ready", "attempted"].includes(String(marker.state)) || marker.cause !== "detached after restore" || typeof marker.at !== "number" || !Number.isFinite(marker.at) || marker.at < 0) throw new Error("invalid reattachment marker");
-      const receipt = decodeRestoreReceipt({ state: "done", binding: marker.binding });
+      const receipt = decode({ state: "done", binding: marker.binding });
       if (receipt?.state !== "done" || receipt.binding.peer !== peer || receipt.binding.projectRoot !== op.plan.projects[index]?.project.root) throw new Error("reattachment binding does not match its peer and project");
     }
   }
@@ -456,7 +468,7 @@ function validateReceipt(id: string, op: RecoveryOperation): void {
     if (!object(evidence) || Object.keys(evidence).some(key => !["projectId", "peer", "sessionId", "kind", "checkedPath"].includes(key)) ||
         typeof evidence.projectId !== "string" || typeof evidence.peer !== "string" || typeof evidence.sessionId !== "string" ||
         evidence.checkedPath !== undefined && (typeof evidence.checkedPath !== "string" || !evidence.checkedPath) ||
-        !["rollout", "transcript"].includes(evidence.kind) || !op.projects.some(progress => missingRepair(op, progress, evidence.peer))) throw new Error("invalid recorded-session missing evidence");
+        !["rollout", "transcript"].includes(evidence.kind) || !op.projects.some(progress => missingRepair(op, progress, evidence.peer, options))) throw new Error("invalid recorded-session missing evidence");
   }
   if (op.freshOverride !== undefined) {
     const override = op.freshOverride, evidence = override.evidence;
@@ -467,14 +479,14 @@ function validateReceipt(id: string, op: RecoveryOperation): void {
   }
   if (op.blockedReattachment !== undefined) {
     const selected = op.blockedReattachment;
-    if (!object(selected) || Object.keys(selected).some(key => !["projectId", "peer"].includes(key)) || typeof selected.projectId !== "string" || definitionOf(String(selected.peer))?.session.launchRecord !== true ||
+    if (!object(selected) || Object.keys(selected).some(key => !["projectId", "peer"].includes(key)) || typeof selected.projectId !== "string" || typeof selected.peer !== "string" || (!historical && projectDefinition(selected.peer, op.plan.projects.find(project => project.project.id === selected.projectId)?.project.root)?.session.launchRecord !== true) ||
         !op.projects.some(project => project.id === selected.projectId && Object.hasOwn(project.reattachments ?? {}, selected.peer))) throw new Error("invalid blocked reattachment selector");
   }
 }
 
 export interface RecoveryDriver {
   stage(op: RecoveryOperation): Promise<{ root: string; digest: string; targetFeatures?: readonly string[] }>;
-  inspect(project: Project, targetFeatures?: readonly string[]): Promise<Inspection>;
+  inspect(project: Project, targetFeatures?: readonly string[], purpose?: "cleanup"): Promise<Inspection>;
   prepare(project: Project, operation: string, instance: string, targetFeatures?: readonly string[]): Promise<void>;
   abort(project: Project, operation: string, instance: string): Promise<void>;
   commit(project: Project, operation: string, instance: string, targetFeatures?: readonly string[]): Promise<void>;
@@ -766,7 +778,11 @@ export async function runRecovery(id: string, driver: RecoveryDriver, home = hub
 
 /** Receipts and runner state only (#215): ids, phases and effects, never task or message text. */
 export function publicOperation(op: RecoveryOperation, runnerPid?: number | "unknown", live: Record<string, Inspection | undefined> = {}) {
-  const effect = (key: string, value: unknown) => key.startsWith("restored:") ? restoreReceiptStatus(value) : value === "pending" || value === "failed" ? value : "done";
+  const effect = (key: string, value: unknown) => {
+    if (!key.startsWith("restored:")) return value === "pending" || value === "failed" ? value : "done";
+    const receipt = decodeRestoreReceipt(value, { authority: "historical" });
+    return !receipt ? "unstarted" : receipt.state === "waiting" ? `waiting:${receipt.origin}` : receipt.state;
+  };
   const choices = nextChoices(op, runnerPid, live), next = choices.map(choice => choice.text);
   return { id: op.id, phase: op.phase, step: op.step, version: op.plan.version, updatedAt: op.updatedAt,
     runner: runnerPid === "unknown" ? { state: "unknown" } : runnerPid ? { state: "running", pid: runnerPid } : { state: "none" },
@@ -795,7 +811,7 @@ export async function reattachRecovery(id: string, peer: string, driver: Recover
   let op = readOperation<RecoveryOperation>(id, home);
   validateReceipt(id, op);
   const selection = () => {
-    if (definitionOf(peer)?.session.launchRecord !== true || op.phase !== "blocked" || op.disposition || op.final || op.blockedReattachment?.peer !== peer) throw new Error("reattach is available only for the peer named by a blocked reattachment receipt");
+    if (projectDefinition(peer, op.plan.projects.find(project => project.project.id === op.blockedReattachment?.projectId)?.project.root)?.session.launchRecord !== true || op.phase !== "blocked" || op.disposition || op.final || op.blockedReattachment?.peer !== peer) throw new Error("reattach is available only for the peer named by a blocked reattachment receipt");
     const progress = op.projects.find(project => project.id === op.blockedReattachment!.projectId);
     const planned = op.plan.projects.find(project => project.project.id === progress?.id);
     const native = peer as RecoveryNativePeer;
@@ -820,7 +836,7 @@ export async function reattachRecovery(id: string, peer: string, driver: Recover
     };
     await target();
     attempted = true;
-    await driver.restore(planned, progress, op, definitionOf(native)?.transport === "claude-channel" ? "claude" : "native", save, native);
+    await driver.restore(planned, progress, op, projectDefinition(native, planned.project.root)?.transport === "claude-channel" ? "claude" : "native", save, native);
     // A done receipt is written by the runtime only after authenticated attachment and exact settlement.
     // Inspection peers may be unavailable; do not invent an attachment from a test or a stale status projection.
     const restored = decodeRestoreReceipt(progress.terminals[`restored:${native}`]);
@@ -853,14 +869,14 @@ export async function reattachRecovery(id: string, peer: string, driver: Recover
 /** Escape a blocked preflight without abandoning a stopped runtime or an uncertain terminal mutation. */
 export async function abortRecovery(id: string, driver: RecoveryDriver, home = hubHome()): Promise<void> {
   let op = readOperation<RecoveryOperation>(id, home);
-  validateReceipt(id, op);
+  validateReceipt(id, op, true);
   acquireRecoveryLock(id, home);
   const releaseRunner = claimRunner(id, home);
   try {
     // Re-read after the exclusive runner claim so cancellation cannot act on a
     // stale pending/prepared receipt after another runner advanced it.
     op = readOperation<RecoveryOperation>(id, home);
-    validateReceipt(id, op);
+    validateReceipt(id, op, true);
     if (op.phase === "completed" || op.phase === "cancelled") {
       if (recoveryLock(home) === id) releaseRecoveryLock(id, home);
       return;
@@ -868,7 +884,7 @@ export async function abortRecovery(id: string, driver: RecoveryDriver, home = h
     if (abandoned(op)) writeOperation(id, op, home);
     const { fingerprint, ...body } = op.plan;
     if (fingerprint !== planFingerprint(body)) throw new Error("operation plan changed");
-    const live = await liveProjects(op, driver.inspect);
+    const live = await liveProjects(op, project => driver.inspect(project, undefined, "cleanup"));
     const refusal = abortRefusal(op, live);
     if (refusal) throw new Error(`abort refused: ${refusal}; ${nextActionsText(op, live)}`);
     // Only this operation's own uncommitted holds are aborted; a lapsed hold, a replacement daemon or another
@@ -893,7 +909,7 @@ export async function abortRecovery(id: string, driver: RecoveryDriver, home = h
  */
 export async function disposeRecovery(id: string, choice: { fresh: string } | { stop: true }, reason: string, driver: RecoveryDriver, home = hubHome()): Promise<RecoveryOperation> {
   let op: RecoveryOperation;
-  try { op = readOperation<RecoveryOperation>(id, home); validateReceipt(id, op); }
+  try { op = readOperation<RecoveryOperation>(id, home); validateReceipt(id, op, "stop" in choice); }
   catch (error) { if (driver.liveTestPeer && "fresh" in choice) throw new Error(LIVE_TEST_PERSON_REFUSAL); throw error; }
   if (driver.liveTestPeer && "fresh" in choice && repairedFreshSession(op, choice.fresh) !== false) throw new Error(LIVE_TEST_PERSON_REFUSAL);
   // A finished operation owns no lock: never take one only to refuse.
@@ -901,7 +917,7 @@ export async function disposeRecovery(id: string, choice: { fresh: string } | {
   acquireRecoveryLock(id, home);
   const releaseRunner = claimRunner(id, home);
   try {
-    try { op = readOperation<RecoveryOperation>(id, home); validateReceipt(id, op); }
+    try { op = readOperation<RecoveryOperation>(id, home); validateReceipt(id, op, "stop" in choice); }
     catch (error) { if (driver.liveTestPeer && "fresh" in choice) throw new Error(LIVE_TEST_PERSON_REFUSAL); throw error; }
     if (driver.liveTestPeer && "fresh" in choice && repairedFreshSession(op, choice.fresh) !== false) throw new Error(LIVE_TEST_PERSON_REFUSAL);
     if (op.phase === "completed" || op.phase === "cancelled") {
@@ -912,11 +928,11 @@ export async function disposeRecovery(id: string, choice: { fresh: string } | {
     if (abandoned(op)) writeOperation(id, op, home);
     const at = driver.now();
     // Read once, as status and the runner do: every choice and refusal below is decided on it.
-    const live = await liveProjects(op, driver.inspect);
+    const live = await liveProjects(op, project => driver.inspect(project, undefined, "stop" in choice ? "cleanup" : undefined));
     const next = nextActionsText(op, live);
     if ("fresh" in choice) {
       // `ahub pi` sends no fresh flag, and a restored hub refills a Pi start from its recorded resume (daemon startPeer).
-      if (definitionOf(choice.fresh)?.session.personFresh === false) throw new Error(`pi: --fresh-session is not supported: a restored hub resumes Pi's recorded session, so a fresh one cannot be guaranteed; ${op.plan.projects.map(planned => piArchiveExit(planned, recoveryCommand(op, "dispose", STOP))).join("; ")}; ${next}`);
+      if (op.plan.projects.some(planned => projectDefinition(choice.fresh, planned.project.root)?.session.personFresh === false)) throw new Error(`pi: --fresh-session is not supported: a restored hub resumes Pi's recorded session, so a fresh one cannot be guaranteed; ${op.plan.projects.filter(planned => projectDefinition(choice.fresh, planned.project.root)?.session.personFresh === false).map(planned => piArchiveExit(planned, recoveryCommand(op, "dispose", STOP), choice.fresh)).join("; ")}; ${next}`);
       if (op.disposition) throw new Error(`a stop-and-archive of this operation is partway; ${next}`);
       if (!targetReadsWaivers(op)) throw new Error(`--fresh-session is not available: target ${op.plan.version} cannot read recovery waivers, so it could not release a new session; ${next}`);
       // The new session is launched by resume, so it helps only where resume can get past what is live.
@@ -997,7 +1013,7 @@ export async function disposeRecovery(id: string, choice: { fresh: string } | {
         else if (act === "stopped" || act === "target stopped") {
           const outcome = await driver.stopAndArchive(planned.project, op, act === "target stopped" ? live!.instanceId : undefined);
           if (outcome && outcome.continuity) (disposition.continuity ??= {})[planned.project.id] = outcome.continuity;
-          if ((await driver.inspect(planned.project)).state !== "stopped") throw new Error(`${planned.project.id}: shutdown of instance ${live!.instanceId ?? "unknown"} is not verified`);
+          if ((await driver.inspect(planned.project, undefined, "cleanup")).state !== "stopped") throw new Error(`${planned.project.id}: shutdown of instance ${live!.instanceId ?? "unknown"} is not verified`);
         }
         disposition.projects[planned.project.id] ??= act;
         op.updatedAt = driver.now(); writeOperation(id, op, home);
@@ -1005,7 +1021,7 @@ export async function disposeRecovery(id: string, choice: { fresh: string } | {
     } catch (error) {
       if (isDatabaseBusy(error)) { op.failure = { code: "database_busy", retryable: true, site: databaseBusySite(error) }; error = new RecoveryDatabaseBusy(); }
       op.phase = "blocked"; op.updatedAt = driver.now();
-      op.error = `stop-and-archive stopped partway and keeps the lock: ${error instanceof Error ? error.message : "disposition failed"} (a committed source stops by itself); ${nextActionsText(op, await liveProjects(op, driver.inspect))}`;
+      op.error = `stop-and-archive stopped partway and keeps the lock: ${error instanceof Error ? error.message : "disposition failed"} (a committed source stops by itself); ${nextActionsText(op, await liveProjects(op, project => driver.inspect(project, undefined, "cleanup")))}`;
       writeOperation(id, op, home);
       throw error;
     }

package/src/hub/budget.ts

@@ -46,6 +46,8 @@ export interface BudgetConfig {
 export const DEFAULT_BUDGET: BudgetConfig = { gate: 0.9, stale_min: 30, poll_min: 10, checkpoint_timeout_s: 90, kimi_tokens_5h: 0, wait_max_min: 0 };
 
 export interface BudgetHooks {
+  /** Stable/idempotent for this Budget lifetime. All lifecycle hooks receive this canonical account id. */
+  account?(peer: PeerId): PeerId;
   pause(peer: PeerId): void;
   /** Must leave a manual `ahub pause` in place. */
   resume(peer: PeerId): void;
@@ -101,6 +103,43 @@ export class Budget {
     this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
     this.db.run(`CREATE TABLE IF NOT EXISTS budget_pauses (peer TEXT PRIMARY KEY, since INTEGER NOT NULL, resets_at INTEGER NOT NULL,
       reason TEXT NOT NULL, summary TEXT, handed_off INTEGER NOT NULL DEFAULT 0, moved TEXT NOT NULL DEFAULT '[]')`);
+    try { this.normalizeStoredPauses(); } catch (error) { this.db.close(); throw error; }
+  }
+
+  private account(peer: PeerId): PeerId {
+    if (!this.hooks.account) return peer;
+    const account = this.hooks.account(peer);
+    if (typeof account !== "string" || !account.trim() || this.hooks.account(account) !== account) throw new Error("budget account resolver must return a canonical idempotent id");
+    return account;
+  }
+
+  /** A newly declared alias must not erase an older custom peer's persisted pause. */
+  private normalizeStoredPauses(): void {
+    if (!this.hooks.account) return; // identity/default startup leaves existing storage byte-for-byte alone
+    this.db.transaction(() => {
+      const rows = (this.db.query("SELECT peer FROM budget_pauses ORDER BY peer").all() as { peer: string }[]).map(row => this.readRecord(row.peer)!);
+      const groups = new Map<PeerId, PauseRecord[]>();
+      for (const row of rows) {
+        const account = this.account(row.peer), group = groups.get(account) ?? [];
+        group.push(row); groups.set(account, group);
+      }
+      for (const [peer, group] of groups) {
+        if (group.length === 1 && group[0]!.peer === peer) continue;
+        // Conservative collision reduction: retain the longest pause, earliest start and every distinct move.
+        // Any unfinished handoff stays unfinished so the daemon's account fanout retries remaining open work.
+        const summaries = group.filter(row => row.summary !== null).map(row => `[${row.peer}]\n${row.summary}`);
+        const moved = [...new Map(group.flatMap(row => row.moved).map(move => [JSON.stringify(move), move])).values()];
+        const first = group[0]!;
+        const record = group.length === 1 ? { ...first, peer } : {
+          peer, since: Math.min(...group.map(row => row.since)), resetsAt: Math.max(...group.map(row => row.resetsAt)),
+          reason: [...new Set(group.map(row => row.reason))].join(" | "), summary: summaries.length ? summaries.join("\n\n") : null,
+          handedOff: group.every(row => row.handedOff), moved,
+        };
+        for (const row of group) this.db.query("DELETE FROM budget_pauses WHERE peer = ?").run(row.peer);
+        this.db.query("INSERT INTO budget_pauses (peer, since, resets_at, reason, summary, handed_off, moved) VALUES (?, ?, ?, ?, ?, ?, ?)")
+          .run(record.peer, record.since, record.resetsAt, record.reason, record.summary, record.handedOff ? 1 : 0, JSON.stringify(record.moved));
+      }
+    }).immediate();
   }
 
   /** Freeze pause/resume and handoff transitions while a controlled restart is fenced. Readings continue to update. */
@@ -121,6 +160,10 @@ export class Budget {
   }
 
   record(peer: PeerId): PauseRecord | undefined {
+    return this.readRecord(this.account(peer));
+  }
+
+  private readRecord(peer: PeerId): PauseRecord | undefined {
     const r = this.db.query("SELECT * FROM budget_pauses WHERE peer = ?").get(peer) as Record<string, any> | null;
     return r ? { peer: r.peer, since: r.since, resetsAt: r.resets_at, reason: r.reason, summary: r.summary, handedOff: !!r.handed_off, moved: JSON.parse(r.moved) } : undefined;
   }
@@ -157,13 +200,15 @@ export class Budget {
   report(peer: PeerId, windows: UsageWindow[], hard = false, at = this.now()): void {
     // Execution-budget instrumentation is independent of native quota accounting.
     // Explicit quota exemption or absent budget metadata exempts registered kinds; external ids keep accounting.
-    const adapter = definitionOf(peer);
-    if (peer === "user" || peer === "hub" || adapter && (!adapter.budget || adapter.budget.quotaExempt === true) || this.closed) return;
+    const reporter = peer;
+    peer = this.account(peer);
+    const adapter = definitionOf(reporter) ?? definitionOf(peer);
+    if (reporter === "user" || reporter === "hub" || peer === "user" || peer === "hub" || adapter && (!adapter.budget || adapter.budget.quotaExempt === true) || this.closed) return;
     // An override ignores soft readings, not a provider that has actually refused another turn.
     if (hard && this.ignoreUntil.delete(peer)) {
       try { this.hooks.notify(`budget: ${peer} provider refused again; budget override ended`); } catch { /* a notice cannot prevent the hard pause */ }
     }
-    try { this.hooks.reading?.(peer, windows, hard, at); } catch { /* telemetry never costs a reading */ }
+    try { this.hooks.reading?.(reporter, windows, hard, at); } catch { /* telemetry never costs a reading */ }
     const mine = this.readings.get(peer) ?? new Map<string, Reading>();
     this.readings.set(peer, mine);
     for (const w of windows) mine.set(w.id, { ...w, used: Math.max(0, Math.min(1, w.used)), at });
@@ -173,12 +218,14 @@ export class Budget {
 
   /** Readings that still say something: not stale, and not about a window that has reset since they were taken. */
   private fresh(peer: PeerId): Reading[] {
+    peer = this.account(peer);
     const staleMs = this.cfg.stale_min * 60_000;
     return [...(this.readings.get(peer)?.values() ?? [])].filter((r) => this.now() - r.at <= staleMs && !(r.resetsAt && r.resetsAt <= this.now()));
   }
 
   /** The owner's override: lift the pause now and leave the peer alone until the window that caused it has reset. */
   override(peer: PeerId): boolean {
+    peer = this.account(peer);
     const open = this.record(peer);
     if (!open) return false;
     this.ignoreUntil.set(peer, open.resetsAt);
@@ -190,6 +237,7 @@ export class Budget {
   }
 
   private async evaluate(peer: PeerId, hard: boolean): Promise<void> {
+    peer = this.account(peer);
     if (this.recoveryHeld) { this.deferred = true; if (hard) this.deferredHard.add(peer); return; }
     const fresh = this.fresh(peer);
     const over = fresh.filter((r) => r.used >= this.cfg.gate);
@@ -252,6 +300,7 @@ export class Budget {
   }
 
   private async finishHandoff(peer: PeerId, summary: string | undefined): Promise<void> {
+    peer = this.account(peer);
     if (this.closed || this.recoveryHeld) { this.deferred = true; return; }
     if (this.handingOff.has(peer) || !this.hooks.canHandOff(peer)) return; // retried by the next tick
     this.handingOff.add(peer);
@@ -264,6 +313,7 @@ export class Budget {
   }
 
   private async handOff(peer: PeerId, summary: string | undefined): Promise<void> {
+    peer = this.account(peer);
     const context = summary ?? (await this.hooks.platformContext(peer).catch(() => undefined));
     // Wait or hand off (issue #36): a handoff costs the next peer the whole context, so a short wait can be cheaper.
     const resetsAt = this.record(peer)?.resetsAt;
@@ -298,6 +348,7 @@ export class Budget {
 
   /** `hub_checkpoint` arrived from a peer. Resolved by the daemon's requestCheckpoint wait; kept on the record for a restart. */
   checkpointed(peer: PeerId, summary: string): void {
+    peer = this.account(peer);
     if (this.closed) return; // a hub_checkpoint that lands during shutdown
     this.db.query("UPDATE budget_pauses SET summary = ? WHERE peer = ?").run(summary, peer);
   }
@@ -314,6 +365,7 @@ export class Budget {
   }
 
   private resume(peer: PeerId, why: string): void {
+    peer = this.account(peer);
     const record = this.record(peer);
     if (!record) return;
     this.db.query("DELETE FROM budget_pauses WHERE peer = ?").run(peer);

package/src/hub/bus.ts

@@ -974,7 +974,7 @@ export class Bus {
   }
 
   /**
-   * What one push delivery would take (the preface, then `take`'s batch), handed to a pull-only peer and recorded as
+   * What one push delivery would take (the preface, then `take`'s batch), explicitly pulled by its attached session and recorded as
    * completed: the tool result that returns it is the readback, so nothing waits for settlement and nothing is ever
    * `accepted` (issue #205). It is checkpointed like a push, so queued rows of the same envelopes (an operator retry)
    * are grouped into it, and registered for `reply_to` like a push. Undefined while held. A failed journal write puts

package/src/hub/conductor.ts

@@ -1,4 +1,4 @@
-import { definitionOf, SUPPORTED_PEERS } from "../adapters/registry.ts";
+import { definitionOf, type KindMap } from "../adapters/registry.ts";
 import { Database } from "bun:sqlite";
 import type { Task } from "./board.ts";
 import { CONDUCTOR_TOOL_NAMES } from "./hub-tools.ts";
@@ -104,19 +104,21 @@ export class ConductorHolds {
   close(): void { this.db.close(); }
 }
 
-type StartablePeer = typeof SUPPORTED_PEERS[number];
-
-export type ConductorStart = { peer: StartablePeer; mode: "headless" } | { peer: "claude" | "codex" | "pi"; mode: "tui"; command: string };
+export type ConductorStart = { peer: string; mode: "headless" } | { peer: "claude" | "codex" | "pi"; mode: "tui"; command: string };
 /**
  * What a conductor's start of `peer` is (#269): the peer's own start mode, which a person sets. A `mode` argument may
  * only repeat it. Preview commands come from the same launch planner the CLI uses, never caller-supplied shell text.
  */
-export function conductorStart(peer: unknown, mode: unknown, preview: (peer: "claude" | "codex" | "pi") => string, preEffect: boolean, startMode: (peer: StartablePeer) => StartMode): ConductorStart {
+export function conductorStart(peer: unknown, mode: unknown, preview: (peer: "claude" | "codex" | "pi") => string, preEffect: boolean, startMode: (peer: string) => StartMode, instances?: KindMap): ConductorStart {
   const refuse = (text: string) => new (preEffect ? PreEffectToolRefusal : Error)(text);
   if (mode !== undefined && mode !== "headless" && mode !== "tui") throw refuse("mode must be headless or tui");
-  if (!(typeof peer === "string" && definitionOf(peer)?.start.conductorStartable)) throw refuse("only claude, codex, kimi, pi and local, plus opt-in qwen/jcode, may be started by the conductor");
-  const selected = peer as StartablePeer;
+  const adapter = typeof peer === "string" ? definitionOf(peer, instances) : undefined;
+  if (typeof peer !== "string" || !adapter?.start.conductorStartable) throw refuse("only claude, codex, kimi, pi and local, plus opt-in qwen/jcode, may be started by the conductor");
+  const selected = peer;
+  const extra = adapter.kind !== selected;
+  if (extra && (!adapter.start.create || !adapter.start.forms.includes("headless") || !["env", "acp-session"].includes(adapter.identity.mcp))) throw refuse(`${peer}: this native transport does not support extra headless instances`);
   const own = startMode(selected);
+  if (extra && own !== "headless") throw refuse(`${peer}: extra instances require headless mode in I2`);
   if (mode !== undefined && mode !== own) throw refuse(`${peer} starts ${own} here; a person sets a start mode (ahub settings), the conductor cannot choose one`);
   return own === "tui" ? { peer: peer as "claude" | "codex" | "pi", mode: "tui", command: preview(peer as "claude" | "codex" | "pi") } : { peer: selected, mode: "headless" };
 }
@@ -164,9 +166,11 @@ export interface ConductorHooks {
   escalate(actor: string, id: number): Promise<unknown>;
   preview(peer: "claude" | "codex" | "pi"): string;
   /** The mode a start of this peer takes: a person's setting. */
-  startMode(peer: StartablePeer): StartMode;
+  startMode(peer: string): StartMode;
   /** Starts the peer in that mode: headless at once, or its fixed command in a terminal; throws with the command to run by hand when no terminal can be opened. */
-  start(peer: StartablePeer): Promise<unknown>;
+  start(peer: string): Promise<unknown>;
+  /** Explicit project declarations only; an undeclared suffix never acquires a native kind. */
+  instances?(): KindMap;
   known(peer: string): boolean;
   pause(peer: string): void;
   validateRelease?(peer: string): Promise<void>;
@@ -231,7 +235,9 @@ export class Conductor {
       return updated ? publicConductorTask(updated, this.hooks.publicView) : { id: task.id };
     }
     if (tool === "hub_peer_start") {
-      const start = conductorStart(args.peer, args.mode, this.hooks.preview, true, this.hooks.startMode);
+      const instances = this.hooks.instances?.();
+      const start = conductorStart(args.peer, args.mode, this.hooks.preview, true, this.hooks.startMode, instances);
+      if (definitionOf(start.peer, instances)?.kind !== start.peer && !this.hooks.known(start.peer)) throw new PreEffectToolRefusal(`unknown peer: ${start.peer}`);
       const result = await this.hooks.start(start.peer);
       const opened = result && typeof result === "object" && typeof (result as { opened?: unknown }).opened === "string" ? { opened: (result as { opened: string }).opened } : {};
       emit({ peer: start.peer }); return { ...start, ...opened };

package/src/hub/config-apply.ts

@@ -8,6 +8,8 @@ import { catalogAssignments } from "./roles.ts";
 import { resolveProfile } from "./profiles.ts";
 import { taskSweepConfig } from "./task-sweep.ts";
 import { projectionConfig } from "./text-projection.ts";
+import { validateInstances, type InstancesConfig } from "./instances.ts";
+import { peerRosterConfig } from "./roster.ts";
 
 export type ApplyClass = "live" | "next use" | "restart";
 export interface ApplyRule { applies: ApplyClass; reason?: string }
@@ -108,6 +110,7 @@ const schema: Record<string, Check> = {
   ...Object.assign({}, ...ADAPTERS.map(adapter => adapter.configuration?.schema?.(nativeValidators) ?? {})),
   watchdog_ms: number(1, 2_147_483_647), kimi_cmd: argv, qwen_cmd: argv, jcode_cmd: argv, codex_bin: text, jcode_home: text, jcode_provider_profile: text,
   permission_modes: v => { permissionDefaults(v); }, protect_instruction_files: bool,
+  instances: v => { validateInstances(v); },
   batch_max: number(1, 100_000, true), batch_ms: number(0, 2_147_483_647), queue_cap: number(1, 1_000_000, true),
   memory: block({ enabled: bool, worker_url: text, inject_tokens: number(0, 1_000_000, true), brief_items: number(0, 10_000, true), native: bool,
     short_ttl_days: number(1, 3650, true), sync_interval_min: number(0, 1440, true), suggest_edges: bool }),
@@ -138,7 +141,14 @@ const schema: Record<string, Check> = {
   review: block({ adaptive: bool, min_reviews: number(1, Number.MAX_SAFE_INTEGER, true) }), recovery: block({ auto_resume_after_crash: bool }),
   capabilities: map(strings), coordination: words(["advisory", "turn-free"]), experiments: block({ stale_notices: words(["drop", "deliver"]) }),
 };
-export function validateRawConfig(raw: unknown): asserts raw is Record<string, unknown> { block(schema)(raw, "config"); }
+export function validateRawConfig(raw: unknown, declarations?: InstancesConfig): asserts raw is Record<string, unknown> {
+  const value = object(raw, "config");
+  const instances = validateInstances(value.instances ?? declarations);
+  if (!Object.keys(instances).length) return block(schema)(raw, "config");
+  block({ ...schema, permission_modes: v => { permissionDefaults(v, instances); },
+    roster: v => { peerRosterConfig(v, instances); }, peers: v => { peerStartConfig(v, instances); },
+  })(raw, "config");
+}
 export function validateEffectiveConfig(value: unknown): asserts value is HubConfig {
   const raw = { ...object(value, "config") };
   delete raw.ignored; delete raw.retired; delete raw.permission_default_sources;
@@ -149,6 +159,7 @@ export function validateEffectiveConfig(value: unknown): asserts value is HubCon
 }
 
 const restart: Record<string, string> = {
+  instances: "Native instance identity, worktree, ports and account bindings are fixed at daemon startup",
   ...Object.assign({}, ...ADAPTERS.map(adapter => adapter.configuration?.restartReasons ?? {})),
   memory: "Open memory consumers, selected profile, client and sync timer must be quiesced together",
   omniroute: "Credentials and gateway clients are bound to relay ownership", mlx: "Model runtime ownership and device resources belong to this daemon",
@@ -174,7 +185,7 @@ export function configApply(key: string): ApplyRule {
       if (shape?.fields) { if (!Object.hasOwn(shape.fields, part)) return fail(key, "unknown configuration key"); check = shape.fields[part]; }
       else if (shape?.item) { if (shape.keys && !shape.keys.includes(part)) return fail(key, "unknown configuration key"); check = shape.item; }
       else if (index === 0 && (special[top]?.includes(part) || top === "checks" && /^[a-z][a-z0-9_]{0,47}$/.test(part))) break;
-      else if (["permission_modes", "catalog_roles", "profile_overrides", "text_projection", "peers"].includes(top)) break;
+      else if (["permission_modes", "catalog_roles", "profile_overrides", "text_projection", "peers", "instances"].includes(top)) break;
       else return fail(key, "unknown configuration key");
     }
   }

package/src/hub/config-reload.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { validateRawConfig, type ConfigLayer } from "./config-apply.ts";
 import { parseOverlay, parseRouting, type Routing } from "./routing.ts";
 import { CLASSES } from "./board.ts";
+import { validateInstances } from "./instances.ts";
 
 export const CONFIG_SOURCE_FILES = ["config.json", "config.local.json", "routing.toml", "routing.local.toml"] as const;
 export type ConfigSourceName = typeof CONFIG_SOURCE_FILES[number];
@@ -90,6 +91,15 @@ function validateRoutingRaw(value: unknown): void {
 /** Strict reloads never use routing's last-good fallback. Startup can retain its existing fallback explicitly. */
 export function parseConfigSources(texts: ConfigSourceTexts, fallbackRouting?: Routing): ConfigSources {
   const layers: ConfigLayer[] = [], trustLayers: ConfigSources["trustLayers"] = [];
+  let localRaw: Record<string, unknown> = {};
+  try { localRaw = JSON.parse(texts["config.local.json"] ?? "{}"); }
+  catch { if (!fallbackRouting) throw new Error(".agenthub/config.local.json: invalid JSON object"); }
+  let declared;
+  try { declared = validateInstances(localRaw?.instances); }
+  catch (error) {
+    if (!fallbackRouting) throw new Error(`.agenthub/config.local.json: ${(error as Error).message}`);
+    declared = validateInstances(undefined);
+  }
   for (const name of CONFIG_SOURCE_FILES) {
     const text = texts[name];
     if (text === null) continue;
@@ -104,7 +114,7 @@ export function parseConfigSources(texts: ConfigSourceTexts, fallbackRouting?: R
     }
     if (name === "config.json" || name === "config.local.json") {
       if (!fallbackRouting) {
-        try { validateRawConfig(raw); }
+        try { validateRawConfig(raw, declared); }
         catch (error) { throw new Error(`.agenthub/${name}: ${(error as Error).message}`); }
       }
       layers.push({ name, raw });

package/src/hub/config-trust.ts

@@ -29,7 +29,7 @@ export const MACHINE_LOCAL = [
   "terminal.open", // the command a hub-made TUI start runs to open a terminal (#269)
 ] as const;
 /** Legacy exported field list stays compatible; new policies use the complete list below. */
-export const ALL_MACHINE_LOCAL = [...MACHINE_LOCAL, "protect_instruction_files", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "text_projection"] as const;
+export const ALL_MACHINE_LOCAL = [...MACHINE_LOCAL, "protect_instruction_files", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "text_projection", "instances"] as const;
 
 /** A known repository, including an unreadable marker, must never be mistaken for a plain directory. */
 export function configRepositoryPresent(cwd: string): boolean {

package/src/hub/control-client.ts

@@ -8,7 +8,7 @@ export function stateDirFor(cwd: string): string {
 
 /** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). 14 = native context-window status and session-bound context checkpoint request ids (issue #185). 15 = conductor tools and permission deadlines/closed events (issues #190, #194). 16 = a Claude session without channel evidence: hello `channel: false` and `inbox` (issue #205). The plugin is installed apart from the daemon, so they can drift. */
 export const PROTOCOL = 16;
-export const DAEMON_FEATURES = ["task_cancel", "recovery_deferred_hub"] as const;
+export const DAEMON_FEATURES = ["task_cancel", "recovery_deferred_hub", "peer_instances"] as const;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
 export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, 15, PROTOCOL] as const;
 

package/src/hub/crash.ts

@@ -1,4 +1,4 @@
-import { definitionOf } from "../adapters/registry.ts";
+import { definitionOf, type KindMap } from "../adapters/registry.ts";
 import { chmodSync, existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { JournalDelivery } from "./delivery-journal.ts";
@@ -56,17 +56,26 @@ const str = (v: unknown) => (typeof v === "string" && v ? v : undefined);
  * What can come back after a crash. `resume` holds the start arguments for peers the hub launches itself (Kimi through
  * ACP `session/load`, Pi through its session file, the local worker afresh); the others say what the user has to do.
  */
-export function crashPlan(records: SessionRecord[]): { peer: string; resume?: Record<string, string>; how: string; fresh?: Record<string, string>; tui?: true }[] {
+export function crashPlan(records: SessionRecord[], instances?: KindMap): { peer: string; resume?: Record<string, string>; how: string; fresh?: Record<string, string>; tui?: true }[] {
   return records.map(({ peer, meta }) => {
     const launch = (meta.launch && typeof meta.launch === "object" ? meta.launch : {}) as Record<string, unknown>;
     const model = str(launch.model);
-    const adapter = definitionOf(peer);
+    const adapter = definitionOf(peer, instances);
+    const extra = adapter !== undefined && definitionOf(peer) === undefined;
+    const command = extra ? `ahub ${adapter.cli.command} --as ${peer}` : `ahub ${peer}`;
     if (adapter?.session.resumeById) {
       const sessionId = adapter.session.crashIdentity?.(meta).sessionId;
-      if (!sessionId) return { peer, how: `${peer}: saved ACP session identity unavailable; start it deliberately with ahub ${peer}` };
+      if (!sessionId) return { peer, how: `${peer}: saved ACP session identity unavailable; start it deliberately with ${command}` };
       return { peer, resume: { sessionId, ...(model ? { model } : {}) }, how: `${peer}: the recorded conversation can be loaded again (ACP session/load)` };
     }
-    return { peer, ...(adapter?.session.crashPlan?.(meta) ?? { how: `${peer}: reconnects by itself if its client is still running` }) };
+    const native = adapter?.session.crashPlan?.(meta);
+    if (!native) return { peer, how: `${peer}: reconnects by itself if its client is still running` };
+    if (!extra) return { peer, ...native };
+    const prefix = `${adapter.kind}:`;
+    let how = native.how.startsWith(prefix) ? `${peer}:${native.how.slice(prefix.length)}` : `${peer}: ${native.how}`;
+    // Manual launch guidance selects this instance. Recorded headless resume prose can contain an opaque id, never a command.
+    if (!native.resume || native.tui) how = how.replace(`ahub ${adapter.cli.command}`, command);
+    return { peer, ...native, how };
   });
 }