@staix/agent-hub 0.26.0 → 0.28.0

package/src/cli/study.ts

@@ -1,5 +1,5 @@
 // Argument parsing for `ahub study` (#601). Pure: argv in, one request description or a usage line out, so the I/O in main.ts stays a thin dispatcher and every form is testable without a daemon.
-export const STUDY_USAGE = "usage: ahub study draft <parent> <contract.json> | revise <id> <revision> <contract.json> | approve <id> <revision> | approve-protocol <hash> | close <id> <revision> --reason <text> | show [<id> | --after <id>] [--json] [--color=auto|always|never]";
+export const STUDY_USAGE = "usage: ahub study draft <parent> <contract.json> | revise <id> <revision> <contract.json> | approve <id> <revision> | approve-protocol <hash> | close <id> <revision> --reason <text> | show [<id> | --after <id>] | experiments (--campaign <id> [--after <n>] | --attempt <ra-id> [--events-after <n>] | --plan <hash> --baseline <ra-id> --variant <ra-id>) [--json] [--color=auto|always|never]";
 
 export type StudyRequest =
   | { op: "draft"; parentTaskId: number; file: string }
@@ -7,9 +7,10 @@ export type StudyRequest =
   | { op: "approve"; id: string; revision: number }
   | { op: "approve_protocol"; hash: string }
   | { op: "close"; id: string; revision: number; reason: string }
-  | { op: "show"; id?: string; after?: string };
+  | { op: "show"; id?: string; after?: string }
+  | { op: "experiments"; campaign?: string; attempt?: string; after?: number; eventsAfter?: number; plan?: string; baseline?: string; variant?: string };
 
-const ID = /^rc-[a-f0-9]{12}$/, INT = /^[1-9]\d{0,8}$/;
+const ID = /^rc-[a-f0-9]{12}$/, INT = /^[1-9]\d{0,8}$/, ATTEMPT = /^ra-[a-f0-9]{12}$/, HASH = /^[a-f0-9]{64}$/, CURSOR = /^(0|[1-9]\d{0,8})$/;
 
 /** `operands` is argv with the presentation flags (`--json`, `--color=`) already removed by `splitPresentation`. `--reason` takes the rest of the words, as `task cancel --reason` does. */
 export function parseStudyArgs(operands: readonly string[]): StudyRequest | { usage: string } {
@@ -22,6 +23,28 @@ export function parseStudyArgs(operands: readonly string[]): StudyRequest | { us
     const hash = rest[0];
     return hash?.length === 64 && /^[a-f0-9]{64}$/.test(hash) ? { op: "approve_protocol", hash } : usage("a protocol hash is 64 lowercase hexadecimal characters");
   }
+  if (sub === "experiments") {
+    // Three closed forms, the ones Tasks.experimentShow takes: a campaign page, one attempt, or one comparison. A flag with no value, a repeat, a stray word or a mix is a usage error before anything is sent.
+    const names = ["--campaign", "--attempt", "--after", "--events-after", "--plan", "--baseline", "--variant"], seen = new Map<string, string>();
+    for (let at = 0; at < rest.length; at += 2) {
+      const name = rest[at], value = rest[at + 1];
+      if (name === undefined || !names.includes(name) || value === undefined || value.startsWith("--") || seen.has(name)) return usage();
+      seen.set(name, value);
+    }
+    const campaign = seen.get("--campaign"), attempt = seen.get("--attempt"), after = seen.get("--after"), eventsAfter = seen.get("--events-after"), plan = seen.get("--plan"), baseline = seen.get("--baseline"), variant = seen.get("--variant");
+    if (campaign !== undefined && !id(campaign)) return usage("a campaign id looks like rc-0123456789ab");
+    for (const [name, value] of [["--attempt", attempt], ["--baseline", baseline], ["--variant", variant]] as const) if (value !== undefined && !ATTEMPT.test(value)) return usage(`${name} takes an attempt id like ra-0123456789ab`);
+    if (plan !== undefined && !HASH.test(plan)) return usage("a plan hash is 64 lowercase hexadecimal characters");
+    if (after !== undefined && !CURSOR.test(after)) return usage("--after takes the cursor a previous page printed");
+    if (eventsAfter !== undefined && !CURSOR.test(eventsAfter)) return usage("--events-after takes the event cursor a previous page printed");
+    const comparison = plan !== undefined || baseline !== undefined || variant !== undefined;
+    if (comparison) return plan !== undefined && baseline !== undefined && variant !== undefined && campaign === undefined && attempt === undefined && after === undefined && eventsAfter === undefined
+      ? { op: "experiments", plan, baseline, variant } : usage("a comparison needs --plan, --baseline and --variant and nothing else");
+    if ((campaign === undefined) === (attempt === undefined)) return usage("give --campaign or --attempt");
+    if (attempt !== undefined && after !== undefined) return usage("--after pages a campaign, not one attempt; --events-after pages the events of one attempt");
+    if (campaign !== undefined && eventsAfter !== undefined) return usage("--events-after pages the events of one attempt, not a campaign");
+    return attempt !== undefined ? { op: "experiments", attempt, ...(eventsAfter === undefined ? {} : { eventsAfter: Number(eventsAfter) }) } : { op: "experiments", campaign: campaign!, ...(after === undefined ? {} : { after: Number(after) }) };
+  }
   if (sub === "show") {
     // `--after <id>` continues a list from the cursor a previous page printed; it has no meaning with an id, which shows one campaign.
     if (rest[0] === "--after") {

package/src/cli/terminal-recovery.ts

@@ -225,7 +225,7 @@ function runnerFailure(argv: readonly string[], result: CommandResult): Recovery
 async function run(runner: CommandRunner, argv: readonly string[]): Promise<unknown> {
   const result = await runner(argv);
   if (commandStatus(result) !== 0) {
-    // Orca 1.4.223 answers a handle whose terminal was removed with `{"ok":false,"error":{"code":"terminal_handle_stale"}}`.
+    // Orca 1.4.223 and, rechecked read-only, 1.4.245 (docs/verification/2026-11-02-orca-1.4.245-cli-contract.md) answer a handle whose terminal was removed with `{"ok":false,"error":{"code":"terminal_handle_stale"}}`.
     if (errorCode(result) === "terminal_handle_stale") {
       const handle = argv.includes("--terminal") ? argv[argv.indexOf("--terminal") + 1] : undefined;
       throw new OrcaCommandError({ code: "terminal-gone", message: `the Orca terminal${handle ? ` ${handle}` : ""} no longer exists` });
@@ -300,17 +300,41 @@ function defaultRunner(executable: string): CommandRunner {
 export const orcaExecutable = (): string => resolveOrcaExecutable();
 
 /**
- * #269: the Orca worktree a terminal for this project can be opened in: the one this process runs in, or the one the
- * last recorded `ahub <peer>` launch of this project used. Undefined when there is none or the record does not read.
- * ponytail: the environment's worktree is taken as this project's; a hub started from another project's Orca terminal
- * (`ahub --project`, the dashboard manager's start, an upgrade or restart that brings several projects up from one
- * terminal) opens the terminal there and `ahub <peer>` then fails its root readback. Ask Orca for the worktree's path
- * and compare it if that case shows up.
+ * #269: whether Orca is in play for this project: this process runs in an Orca terminal, or an earlier `ahub <peer>`
+ * launch of this project recorded a worktree. It is only a hint for a synchronous "could a start open a terminal"
+ * answer. It is never the worktree a terminal is opened in: the environment names the worktree of whatever terminal
+ * this process was started from, which is another project's when `ahub --project`, the dashboard manager or an upgrade
+ * brought this project up (#1089). `resolveStartTerminalWorktree` names the worktree.
  */
-export function startTerminalWorktree(projectRoot: string, stateDir: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
-  if (env.ORCA_WORKTREE_ID) return env.ORCA_WORKTREE_ID;
+export function startTerminalCandidate(projectRoot: string, stateDir: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.ORCA_WORKTREE_ID) return true;
   const records = launchRecords(stateDir);
-  return records === "unreadable" ? undefined : records.rows.filter((row) => row.projectRoot === projectRoot).at(-1)?.worktreeId;
+  return records !== "unreadable" && records.rows.some((row) => row.projectRoot === projectRoot && typeof row.worktreeId === "string");
+}
+
+/** #1089: how many worktrees one `orca worktree list` asks for; a longer list is reported as truncated and never read as "none". */
+const WORKTREE_LIST_LIMIT = 500;
+
+/**
+ * #1089: the Orca worktree whose root is exactly this project's root, asked of Orca and never taken from the caller's
+ * environment. The match is exact because `ahub <peer>` compares the terminal's worktree root with the project root by
+ * equality and refuses on a difference: a terminal opened in any other worktree would only fail later. The refusal names
+ * the cause and the next step and carries no path; Orca's own words go in `detail` for the hub log.
+ */
+export async function resolveStartTerminalWorktree(projectRoot: string, options?: CommandRunner | TerminalRecoveryOptions): Promise<{ ok: true; worktreeId: string } | { ok: false; why: string; detail?: string }> {
+  const config = normalizeOptions(options);
+  let value: unknown;
+  try { value = await run(config.runner, ["worktree", "list", "--limit", String(WORKTREE_LIST_LIMIT), "--json"]); }
+  catch (error) {
+    return { ok: false, why: "Orca could not list its worktrees, so no terminal was opened. Check that Orca is running (orca worktree list), then start the peer again, or set terminal.open", detail: (error as Error).message };
+  }
+  const payload = responseResult(value);
+  const rows = Array.isArray(payload.worktrees) ? payload.worktrees.map(object) : [];
+  const matches = rows.filter((row) => row.isArchived !== true && rootMatches(row.path, projectRoot) && typeof row.id === "string" && row.id.length > 0);
+  if (matches.length === 1) return { ok: true, worktreeId: String(matches[0]!.id) };
+  if (matches.length > 1) return { ok: false, why: "more than one Orca worktree has this project's root, so no terminal was opened. Archive the extra entry in Orca, or set terminal.open" };
+  if (payload.truncated === true) return { ok: false, why: `Orca's worktree list was cut off at ${WORKTREE_LIST_LIMIT} rows before one with this project's root appeared, so no terminal was opened. Archive worktrees you no longer use in Orca, or set terminal.open` };
+  return { ok: false, why: "Orca has no worktree whose root is this project's root, so no terminal was opened. Open this project in Orca (add it as a repository or worktree), then start the peer again, or set terminal.open" };
 }
 
 /** #269: a new Orca terminal running `command` (a complete, already quoted command line); the terminal's handle. */
@@ -791,7 +815,7 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
 }
 
 /**
- * One bounded Orca wait. Orca 1.4.223 answers a wait that timed out with exit 1 and `{"ok":false,"error":{"code":"timeout"}}`:
+ * One bounded Orca wait. Orca 1.4.223 and, rechecked read-only, 1.4.245 (docs/verification/2026-11-02-orca-1.4.245-cli-contract.md) answer a wait that timed out with exit 1 and `{"ok":false,"error":{"code":"timeout"}}`:
  * that is "not satisfied", not a failure. Any other failure still throws.
  */
 async function waitSatisfied(runner: CommandRunner, handle: string, timeoutMs: number): Promise<boolean> {

package/src/hub/action-policy.ts

@@ -37,13 +37,15 @@ export function askedClasses(config: ActionPolicyConfig): ActionClass[] {
   return ACTION_CLASSES.filter(key => config.always_ask.includes(key) || config.floor === true && FLOOR_ASKED.includes(key));
 }
 
+const RELEASE_FLOOR_GUARD = "release only through ahub sdlc authorize-release and the OIDC tag workflow; consent is recorded by the person or the unique configured conductor, which acts only on the person's explicit release instruction in its own session (hub/task/review/file/peer relays never qualify)";
+
 /**
  * The structural guards the floor rests on where the hub cannot see a call first (Codex in never-ask, Kimi in auto, Jcode: #999 T3). The hub names
  * them and cannot verify them from here, so a status row says "not verified", never that they hold. A guard that is missing is the person's to report.
  */
 export const FLOOR_GUARDS: readonly { readonly asks: string; readonly guard: string }[] = Object.freeze([
   { asks: "force push, a push to the default branch or of tags", guard: "GitHub branch protection on the default branch" },
-  { asks: "gh release and a release tag", guard: "release only through ahub sdlc authorize-release and the OIDC tag workflow" },
+  { asks: "gh release and a release tag", guard: RELEASE_FLOOR_GUARD },
   { asks: "deletion outside the project, a write to another repository", guard: "the peer's native sandbox" },
 ]);
 export const floorGuardText = (): string => FLOOR_GUARDS.map(entry => `${entry.asks}: ${entry.guard}`).join("; ");
@@ -77,8 +79,8 @@ export function floorReads(calls: number, ms: number, now: () => number = Date.n
 export const FLOOR_CLASS_TABLE: Readonly<Record<string, { readonly action: ActionClass; readonly asks: string; readonly guard: string | null }>> = Object.freeze({
   "force-push": { action: "publish", asks: "a force or delete push", guard: "GitHub branch protection on the default branch" },
   "default-branch-push": { action: "publish", asks: "a push to the default branch", guard: "GitHub branch protection on the default branch" },
-  "tag-push": { action: "publish", asks: "a push of a tag", guard: "release only through ahub sdlc authorize-release and the OIDC tag workflow" },
-  "release-publish": { action: "publish", asks: "gh release", guard: "release only through ahub sdlc authorize-release and the OIDC tag workflow" },
+  "tag-push": { action: "publish", asks: "a push of a tag", guard: RELEASE_FLOOR_GUARD },
+  "release-publish": { action: "publish", asks: "gh release", guard: RELEASE_FLOOR_GUARD },
   "package-publish": { action: "publish", asks: "npm, bun, pnpm, yarn or cargo publish", guard: null },
   "destroy-outside-root": { action: "destroy", asks: "deletion outside the execution root", guard: "the peer's native sandbox" },
   "foreign-repo-write": { action: "external-write", asks: "a write to another repository", guard: "the peer's native sandbox" },

package/src/hub/board.ts

@@ -18,6 +18,8 @@ import type { SdlcReceipt } from "./sdlc.ts";
 import { parseReviewFindings, type ReviewFindingSet } from "./review-findings.ts";
 import { parseDeliverableRecords, type DeliverableRecord } from "./deliverables.ts";
 import type { CostPlan, ReviewCost } from "./cost-governance.ts";
+import type { SpecRef, SpecTaskReport } from "./specs-task.ts";
+export type { SpecAck, SpecRef, SpecTaskReport } from "./specs-task.ts";
 import { campaignHash, parseResearchCampaign, parseResearchHandoff, type ResearchCampaignContract, type ResearchCampaignStatus, type ResearchUnit, type ResearchHandoffV1, type ResearchHandoffRecord } from "./research-campaign.ts";
 
 export interface ResearchCampaignRecord {
@@ -133,7 +135,7 @@ export type TaskState = "backlog" | "proposed" | "in_progress" | "in_review" | "
 export const isClosedTaskState = (state: string): boolean => state === "approved" || state === "cancelled";
 export interface TaskOffer { envelopeId: string; owner: PeerId; assignmentFlowRevision: number; pullOnly?: boolean }
 export interface TaskCancellation { reason: string; supersededBy?: string; flowRevision: number; withheld?: true }
-export const TASK_STALL_CODES = ["tests", "spec", "roster", "pull-only", "not-attached", "excluded", "owner-admission", "offline", "paused", "failing", "pii", "policy", "cancelled", "unavailable", "no-writes", "queue-count", "queue-age", "queue-age-unknown"] as const;
+export const TASK_STALL_CODES = ["tests", "spec", "network", "worktree", "roster", "pull-only", "not-attached", "excluded", "owner-admission", "offline", "paused", "failing", "pii", "policy", "cancelled", "unavailable", "no-writes", "queue-count", "queue-age", "queue-age-unknown"] as const;
 export type TaskStallCode = (typeof TASK_STALL_CODES)[number];
 export interface TaskStall { task: number; signature: string; replanRevision: number; cause: { kind: "reservation" | "no-eligible-peer" | "cancelled-dependency" | "no-writes"; peer?: string; dependency?: number; code: TaskStallCode; turns?: number; acceptance?: number; refusals?: { peer: string; code: TaskStallCode }[] }; at: number }
 
@@ -201,6 +203,10 @@ export interface HistoryEntry {
   sweep?: SweepRecord;
   /** The PII screen did not clear this entry's note (#198): only the console reads it. */
   withheld?: true;
+  /** Public, head-bound design-spec status; acknowledgement text is screened before this is written. */
+  specReport?: SpecTaskReport;
+  /** Internal identity for incomplete reports without a full commit SHA; never projected publicly. */
+  specRefBinding?: string;
   /** Host evidence at done, never inferred from the owner's summary. */
   noWrites?: true;
   /** Host-recorded expected cost and exact review head, never narrative. */
@@ -277,6 +283,31 @@ function reviewerHistory(extra: ReviewerHistory): ReviewerHistory {
   if (failure && (!id(failure.peer) || !["start_failed", "quota", "no_verdict"].includes(failure.cause) || failure.head !== undefined && (typeof failure.head !== "string" || !failure.head.trim() || failure.head.length > 300 || Buffer.byteLength(failure.head) > 1200 || /\p{Cc}/u.test(failure.head)))) throw new Error("invalid reviewer failure metadata");
   return { ...(extra.reviewerFamily ? { reviewerFamily: extra.reviewerFamily } : {}), ...(extra.reviewerReason ? { reviewerReason: extra.reviewerReason } : {}), ...(extra.reviewBlocked ? { reviewBlocked: true } : {}), ...(extra.queueReviewHeld ? { queueReviewHeld: true, ...(extra.queueReviewBinding !== undefined ? { queueReviewBinding: extra.queueReviewBinding } : {}) } : {}), ...(failure ? { reviewerFailure: { peer: failure.peer, cause: failure.cause, ...(failure.head ? { head: failure.head } : {}) } } : {}) };
 }
+function specReportHistory(report: unknown, binding: unknown, event: string): Pick<HistoryEntry, "specReport" | "specRefBinding"> {
+  if (!report || typeof report !== "object" || Array.isArray(report) || !["done", "done (checking)"].includes(event)
+    || typeof binding !== "string" || !/^[a-f0-9]{64}$/.test(binding)) throw new Error("invalid task spec report metadata");
+  const value = report as Record<string, unknown>;
+  if (Object.keys(value).some(key => !["head", "complete", "errors", "unchanged", "changed", "truncated", "reason"].includes(key))
+    || typeof value.head !== "string" || value.head !== "" && !/^[a-f0-9]{40}$/.test(value.head)
+    || value.head === "" && value.complete !== false || typeof value.complete !== "boolean"
+    || !Number.isSafeInteger(value.errors) || (value.errors as number) < 0 || (value.errors as number) > 1_000_000
+    || value.truncated !== undefined && value.truncated !== true
+    || value.reason !== undefined && (typeof value.reason !== "string" || value.reason.length > 500 || /[\p{Cc}\p{Cf}]/u.test(value.reason))
+    || !Array.isArray(value.unchanged) || value.unchanged.length > 20 || !Array.isArray(value.changed) || value.changed.length > 20) throw new Error("invalid task spec report metadata");
+  const ref = (raw: unknown): SpecRef => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("invalid task spec report metadata");
+    const row = raw as Record<string, unknown>;
+    if (Object.keys(row).some(key => !["id", "path", "title", "reason"].includes(key))
+      || typeof row.id !== "string" || !row.id.trim() || row.id.length > 160 || /[\p{Cc}\p{Cf}]/u.test(row.id)
+      || typeof row.path !== "string" || !row.path.trim() || row.path.length > 1000 || /[\p{Cc}\p{Cf}]/u.test(row.path)
+      || typeof row.title !== "string" || !row.title.trim() || row.title.length > 1000 || /[\p{Cc}\p{Cf}]/u.test(row.title)
+      || row.reason !== undefined && (typeof row.reason !== "string" || row.reason.length > 1000 || /[\p{Cc}\p{Cf}]/u.test(row.reason))) throw new Error("invalid task spec report metadata");
+    return { id: row.id, path: row.path, title: row.title, ...(typeof row.reason === "string" ? { reason: row.reason } : {}) };
+  };
+  const specReport: SpecTaskReport = { head: value.head, complete: value.complete, errors: value.errors as number,
+    unchanged: value.unchanged.map(ref), changed: value.changed.map(ref), ...(value.truncated === true ? { truncated: true } : {}), ...(typeof value.reason === "string" ? { reason: value.reason } : {}) };
+  return { specReport, specRefBinding: binding };
+}
 export interface PlannerBinding { planner: PeerId | null; plannerReason: PlannerReason }
 function plannerValue(value: unknown): PeerId | null {
   if (value == null) return null;
@@ -1362,6 +1393,26 @@ export class Board {
   statusTasks(): Pick<Task, "id" | "state" | "owner" | "reviewer">[] {
     return this.db.query("SELECT id, state, owner, reviewer FROM tasks WHERE state NOT IN ('approved','cancelled') ORDER BY id").all() as Pick<Task, "id" | "state" | "owner" | "reviewer">[];
   }
+  /** Fresh privacy classification inputs only; no task history, title, detail or plan decoding. */
+  peerTaskSignals(peer: string): Pick<Task, "state" | "signals">[] {
+    const rows = this.db.query("SELECT state, signals FROM tasks WHERE owner=? OR reviewer=?").all(peer, peer) as { state: unknown; signals: unknown }[];
+    return rows.map(row => {
+      const signals: unknown = JSON.parse(String(row.signals));
+      if (typeof row.state !== "string" || !Array.isArray(signals) || signals.some(signal => typeof signal !== "string")) throw new Error("invalid task privacy projection");
+      return { state: row.state as TaskState, signals: signals as string[] };
+    });
+  }
+  /** Fresh privacy facts for a bounded explicit reference set; no task history or text decoding. */
+  taskPrivacySignals(ids: readonly number[]): Pick<Task, "id" | "signals">[] {
+    if (!Array.isArray(ids) || ids.length > 64 || ids.some(id => !Number.isSafeInteger(id) || id < 1) || new Set(ids).size !== ids.length) throw new Error("invalid task privacy reference set");
+    if (!ids.length) return [];
+    const rows = this.db.query(`SELECT id, signals FROM tasks WHERE id IN (${ids.map(() => "?").join(",")})`).all(...ids) as { id: unknown; signals: unknown }[];
+    return rows.map(row => {
+      const signals: unknown = JSON.parse(String(row.signals));
+      if (!Number.isSafeInteger(row.id) || !Array.isArray(signals) || signals.some(signal => typeof signal !== "string")) throw new Error("invalid task privacy projection");
+      return { id: row.id as number, signals: signals as string[] };
+    });
+  }
   statusReservations(): string[] {
     return (this.db.query("SELECT DISTINCT reserved FROM tasks WHERE state NOT IN ('approved', 'cancelled', 'backlog') AND reserved IS NOT NULL ORDER BY reserved").all() as { reserved: string }[]).map(row => row.reserved);
   }
@@ -1454,7 +1505,7 @@ export class Board {
 
   /** The only way a task changes. Validates the move, records who did what, returns the new row. */
   /** A `plan` in the patch replaces the old one whole: a new plan is the owner's current intent, not an addition. */
-  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "planner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role" | "cancelled" | "codeSymbols">>, note?: string, extra: Pick<HistoryEntry, "invocation" | "plannerReason" | "planAuthor" | "selfReview" | "profile" | "sweep" | "reason" | "from" | "capacity" | "conductorManual" | "withheld" | "noWrites" | "reviewCost" | "reviewContext" | "reviewScope" | "evidenceOnly" | "reviewedHead" | "reviewFindings" | "unmetCriteria" | "deliverables" | "checkKey" | "missingKeys" | "claim" | "planObservation" | "planDeparture" | "planDepartureInvalidated" | keyof ReviewerHistory> = {}, expectedFlowRevision?: number, codeSymbolsAuthority?: typeof HOST_CODE_SYMBOLS): Task {
+  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "planner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role" | "cancelled" | "codeSymbols">>, note?: string, extra: Pick<HistoryEntry, "invocation" | "plannerReason" | "planAuthor" | "selfReview" | "profile" | "sweep" | "reason" | "from" | "capacity" | "conductorManual" | "withheld" | "noWrites" | "reviewCost" | "reviewContext" | "reviewScope" | "evidenceOnly" | "reviewedHead" | "reviewFindings" | "unmetCriteria" | "deliverables" | "checkKey" | "missingKeys" | "claim" | "planObservation" | "planDeparture" | "planDepartureInvalidated" | "specReport" | "specRefBinding" | keyof ReviewerHistory> = {}, expectedFlowRevision?: number, codeSymbolsAuthority?: typeof HOST_CODE_SYMBOLS): Task {
     const task = this.get(id);
     if (!task) throw new Error(`no task #${id}`);
     if (expectedFlowRevision !== undefined && (!Number.isSafeInteger(expectedFlowRevision) || expectedFlowRevision < 0 || task.history.length !== expectedFlowRevision)) throw new Error("task flow revision changed");
@@ -1480,6 +1531,8 @@ export class Board {
     const plannerHistory = Object.hasOwn(patch, "planner") || extra.plannerReason !== undefined ? plannerMetadata(planner, extra.plannerReason) : {};
     const authorHistory = Object.hasOwn(extra, "planAuthor") ? { planAuthor: plannerValue(extra.planAuthor) } : {};
     if (extra.selfReview !== undefined && extra.selfReview !== true) throw new Error("invalid self-review metadata");
+    const specMetadata = extra.specReport !== undefined || extra.specRefBinding !== undefined
+      ? specReportHistory(extra.specReport, extra.specRefBinding, event) : {};
     if (extra.conductorManual !== undefined && (extra.conductorManual !== true || by === "user" || by === "hub" || extra.reason !== "manual"
       || !["assigned", "reassigned", "reserved", "unassigned", "reviewer changed"].includes(event))) throw new Error("invalid conductor manual metadata");
     if (extra.invocation && (by !== HUB || event !== "invocation")) throw new Error("invocation audit is host-only");
@@ -1533,7 +1586,7 @@ export class Board {
       && priorHead !== undefined && /^[a-f0-9]{40}$/.test(priorHead);
     const previousHistory = backfill ? task.history.map((entry, index) => index === priorApproval && !entry.reviewedHead
       ? { ...entry, reviewedHead: entry.reviewFindings?.head ?? priorHead } : entry) : task.history;
-    const history = [...previousHistory, { at: Date.now(), by, event, ...(extra.invocation ? { invocation: extra.invocation } : {}), ...plannerHistory, ...authorHistory, ...(extra.selfReview === true ? { selfReview: true as const } : {}), ...(planRevision ? { planRevision } : {}), ...(extra.planObservation ? { planObservation: extra.planObservation } : {}), ...(extra.planDeparture ? { planDeparture: extra.planDeparture } : {}), ...(departureInvalidated ? { planDepartureInvalidated: true as const } : {}), ...reviewMetadata, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.capacity === true ? { capacity: true as const } : {}), ...(extra.conductorManual === true ? { conductorManual: true as const } : {}), ...(extra.withheld && (note || reviewFindings) ? { withheld: true as const } : {}), ...(reviewFindings ? { reviewFindings } : {}), ...(extra.reviewedHead ? { reviewedHead: extra.reviewedHead } : {}), ...(unmetCriteria?.length ? { unmetCriteria } : {}), ...(deliverables ? { deliverables } : {}), ...(extra.reviewContext === "fresh" || extra.reviewContext === "continuing" ? { reviewContext: extra.reviewContext } : {}), ...(extra.reviewScope === "code" ? { reviewScope: "code" as const } : {}), ...(extra.evidenceOnly === true && event === "changes_requested" ? { evidenceOnly: true as const } : {}), ...(extra.reviewCost ? { reviewCost: extra.reviewCost } : {}), ...(event === "done" && extra.noWrites === true ? { noWrites: true as const } : {}), ...(["check passed", "check failed"].includes(event) && typeof extra.checkKey === "string" && /^[a-z][a-z0-9_]{0,47}$/.test(extra.checkKey) ? { checkKey: extra.checkKey } : {}), ...(["check passed", "check failed"].includes(event) && Number.isSafeInteger(extra.missingKeys) && extra.missingKeys! >= 0 && extra.missingKeys! <= 100_000 ? { missingKeys: extra.missingKeys } : {}), ...(event === "claim verdict" && extra.claim ? { claim: extra.claim } : {}) }];
+    const history = [...previousHistory, { at: Date.now(), by, event, ...(extra.invocation ? { invocation: extra.invocation } : {}), ...plannerHistory, ...authorHistory, ...(extra.selfReview === true ? { selfReview: true as const } : {}), ...(planRevision ? { planRevision } : {}), ...(extra.planObservation ? { planObservation: extra.planObservation } : {}), ...(extra.planDeparture ? { planDeparture: extra.planDeparture } : {}), ...(departureInvalidated ? { planDepartureInvalidated: true as const } : {}), ...reviewMetadata, ...specMetadata, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.capacity === true ? { capacity: true as const } : {}), ...(extra.conductorManual === true ? { conductorManual: true as const } : {}), ...(extra.withheld && (note || reviewFindings) ? { withheld: true as const } : {}), ...(reviewFindings ? { reviewFindings } : {}), ...(extra.reviewedHead ? { reviewedHead: extra.reviewedHead } : {}), ...(unmetCriteria?.length ? { unmetCriteria } : {}), ...(deliverables ? { deliverables } : {}), ...(extra.reviewContext === "fresh" || extra.reviewContext === "continuing" ? { reviewContext: extra.reviewContext } : {}), ...(extra.reviewScope === "code" ? { reviewScope: "code" as const } : {}), ...(extra.evidenceOnly === true && event === "changes_requested" ? { evidenceOnly: true as const } : {}), ...(extra.reviewCost ? { reviewCost: extra.reviewCost } : {}), ...(event === "done" && extra.noWrites === true ? { noWrites: true as const } : {}), ...(["check passed", "check failed"].includes(event) && typeof extra.checkKey === "string" && /^[a-z][a-z0-9_]{0,47}$/.test(extra.checkKey) ? { checkKey: extra.checkKey } : {}), ...(["check passed", "check failed"].includes(event) && Number.isSafeInteger(extra.missingKeys) && extra.missingKeys! >= 0 && extra.missingKeys! <= 100_000 ? { missingKeys: extra.missingKeys } : {}), ...(event === "claim verdict" && extra.claim ? { claim: extra.claim } : {}) }];
     this.taskWrite(() => {
       const result = this.db.query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, reserved = ?, refs = ?, plan = ?, rejections = ?, signals = ?, history = ?, sdlc = ?, task_role = ?, cancelled = ?, updated = ?, planner = ? WHERE id = ?")
         .run(next.state, next.owner, next.reviewer, next.reserved ?? null, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(next.signals), JSON.stringify(history), next.sdlc ? JSON.stringify(next.sdlc) : null, next.role ?? null, next.cancelled ? JSON.stringify(next.cancelled) : null, Date.now(), planner, id);

package/src/hub/bus.ts

@@ -1,8 +1,8 @@
-import { remoteEnvelope, appendNote, DIGEST, frame, HUB, isInvocationKind, keepNotes, MAX_HOP, mergePrefaces, newEnvelope, noteLine, parseMarker, quoteNotes, replyAudience, uniqueMemoryLines, type Envelope, type EnvelopeOpts, type PeerId, type PeerState, type Priority } from "./envelope.ts";
+import { remoteEnvelope, appendNote, DIGEST, frame, HUB, USER, isInvocationKind, keepNotes, MAX_HOP, mergePrefaces, newEnvelope, noteLine, parseMarker, quoteNotes, replyAudience, uniqueMemoryLines, type Envelope, type EnvelopeOpts, type PeerId, type PeerState, type Priority } from "./envelope.ts";
 import type { PeerAdapter, DeliveryReceipt } from "./peers.ts";
 import type { DoingKind } from "./peer-doing.ts";
 import type { QueuePressure } from "./queue-backpressure.ts";
-import { DeliveryJournal, MAX_ENVELOPE_BODY, type JournalDelivery, type JournalDeliveryState } from "./delivery-journal.ts";
+import { DeliveryJournal, MAX_ENVELOPE_BODY, type JournalDelivery, type JournalDeliveryState, type JournalResolution } from "./delivery-journal.ts";
 import { DELIVERY_RETRY_WARNING } from "./delivery-hints.ts";
 import { MAX_DEFERRED_HUB, RecoveryDeferredHubError, validateDeferredHub } from "./deferred-hub.ts";
 import { parseRemotePeerId } from "../rooms/application.ts";
@@ -617,6 +617,31 @@ export class Bus {
     this.resolveDelivery(id, row.revision, "retry", "recipient requested one uncertain redelivery", `peer:${peer}`);
   }
 
+  /** Settle only this peer's own uncertain receipt; this never replays its originals or changes task state. */
+  resolveOwnDelivery(peer: string, id: string, revision: number, action: "completed" | "discard", reason: string): void {
+    const refuse = (message: string): never => { throw new PreEffectToolRefusal(message); };
+    // One message per cause class, each naming its next step. An unknown id, another peer's row and a row that is not needs_review share one message so a refusal never confirms another peer's row.
+    if (peer === USER || peer === HUB || remoteId(peer)) return refuse("hub_delivery_resolve settles a local agent's own held delivery; the person settles any other row with ahub queue resolve <delivery-id>");
+    if (this.closed || this.recoveryHeld || this.storageError || !this.journal) return refuse("the hub is not accepting delivery changes now (recovery, shutdown or delivery storage); run ahub status, then call hub_delivery_resolve again after it recovers");
+    if (this.paused.has(peer) || this.opts.deliveryHeld?.(peer) === true) return refuse("your deliveries are paused or held, so this row cannot be settled now; run ahub status to see which, and call hub_delivery_resolve again once it is released");
+    if (!Number.isSafeInteger(revision) || revision < 0 || (action !== "completed" && action !== "discard") || typeof reason !== "string" || !reason.trim() || reason.trim().length > 1000) return refuse("hub_delivery_resolve needs the revision hub_inbox showed (a whole number), action completed or discard, and a reason of 1 to 1000 characters");
+    const row = this.queueShow(id), actor = `peer:${peer}`, cleanReason = reason.trim();
+    const notYours = "no needs_review delivery with this id is held for you; call hub_inbox to list your held deliveries and their revisions";
+    if (!row || row.peer !== peer) return refuse(notYours);
+    // An uncertain invocation may still be running: a peer claiming it completed would make the caller wait for a result that may never come. Only the person settles it.
+    if (row.originals.some(env => isInvocationKind(env))) return refuse(`delivery ${id} carries an invocation whose outcome is uncertain; only the person settles it (ahub queue show ${id}, then ahub queue resolve ${id})`);
+    const previous = this.journal.resolution(id);
+    if (previous) {
+      if (previous.actor !== actor || previous.action !== action || previous.reason !== cleanReason) return refuse(`delivery ${id} was already settled with a different action or reason; the person can inspect it with ahub queue show ${id}`);
+      if (revision !== previous.observedRevision && revision !== row.revision) return refuse("held delivery revision changed; read hub_inbox again for the current revision");
+      this.resolveDelivery(id, revision, action, cleanReason, actor);
+      return;
+    }
+    if (row.state !== "needs_review") return refuse(notYours);
+    if (row.revision !== revision) return refuse("held delivery revision changed; read hub_inbox again for the current revision");
+    this.resolveDelivery(id, revision, action, cleanReason, actor);
+  }
+
   private retryOut(peer: string, originals: Envelope[], out: Envelope[]): Envelope[] {
     if (remoteId(peer)) return out;
     if (!out.length || !this.journal || !this.journal.retryWarning(peer, originals)) return out;
@@ -631,6 +656,11 @@ export class Bus {
     });
   }
 
+  /** #1096: the operator action that settled this delivery, when one did (`queue show` reads it to say what is left to do). */
+  deliveryResolution(id: string): JournalResolution | undefined { return this.journal && !this.storageError ? this.journal.resolution(id)?.action : undefined; }
+  /** #1096: ids of the deliveries an operator action already settled, in one read; empty without a journal. `queue list` hides them unless asked for all. */
+  settledIds(): Set<string> { return this.journal && !this.storageError ? this.journal.resolvedIds() : new Set(); }
+
   resolveDelivery(id: string, revision: number, action: "completed" | "retry" | "discard", reason: string, actor: string = "user"): void {
     if (!this.journal || this.storageError) throw new Error("delivery journal unavailable");
     this.trackingQueuePressure();
@@ -638,7 +668,13 @@ export class Bus {
     if (!record) throw new Error("unknown delivery");
     const previous = this.journal.resolution(id);
     if (previous) {
-      this.journal.resolve(id, revision, action, reason, revision, actor); // verifies identical request; no second enqueue
+      // #1096: a row that already carries a resolution is settled. The same request again is idempotent (the journal verifies it); any other request is not a
+      // stale read, and `retry` in particular leaves its parent in `failed` for good, because the redelivery is a new row. Say so instead of "stale revision".
+      try { this.journal.resolve(id, revision, action, reason, revision, actor); }
+      catch (error) {
+        if (/stale delivery revision or conflicting operator resolution/.test(error instanceof Error ? error.message : "")) throw new Error(`delivery already resolved by ${previous.action}`);
+        throw error;
+      }
       return;
     }
     if (action === "retry" && remoteId(record.peer)) {
@@ -648,12 +684,14 @@ export class Bus {
       if (!Number.isSafeInteger(deadline) || deadline! <= Date.now()) throw new PreEffectToolRefusal("remote original deadline unavailable or expired; discard it or send a new message explicitly");
       this.checkRemotePublication(record.originals[0]!);
     }
-    const recipientConsent = actor === `peer:${record.peer}` && action === "retry" && record.state === "needs_review";
+    const recipientConsent = actor === `peer:${record.peer}` && record.state === "needs_review" && (action === "retry" || action === "completed" || action === "discard");
     // #713: a `queued` delivery was never handed to the peer, so nothing is in flight and a busy peer (a pull-only TUI is busy most of the time) does not block
     // discarding it. `dispatching` and `accepted` stay refused, and every other resolution keeps the busy fence.
     if (["dispatching", "accepted"].includes(record.state)) throw new Error("active delivery cannot be resolved");
     const queuedDiscard = record.state === "queued" && action === "discard";
-    if (this.peers.get(record.peer)?.state === "busy" && !recipientConsent && !queuedDiscard) throw new Error("peer busy: its delivery cannot be resolved while it works");
+    // #1096: a `failed` row was refused before it ran and discarding it touches no queue, so a busy peer has nothing in flight to protect either.
+    const failedDiscard = record.state === "failed" && action === "discard";
+    if (this.peers.get(record.peer)?.state === "busy" && !recipientConsent && !queuedDiscard && !failedDiscard) throw new Error("peer busy: its delivery cannot be resolved while it works");
     if (record.revision !== revision) throw new Error("stale delivery revision");
     if (record.state === "queued" && action === "retry") throw new Error("queued delivery is already scheduled");
     if (action === "retry" && !remoteId(record.peer) && (this.queues.get(record.peer)?.length ?? 0) + record.originals.length > this.opts.queueCap) throw new Error("recipient queue is full");
@@ -1435,10 +1473,10 @@ export class Bus {
    * terminal row. The completed row keeps the envelopes (`ahub queue show <id>`) to resend by hand; take/confirm in two
    * steps if loss is ever observed.
    */
-  pull(id: PeerId): Envelope[] | undefined {
+  pull(id: PeerId, options: { allowNeedsReviewHold?: boolean } = {}): Envelope[] | undefined {
     if (remoteId(id)) return undefined; // A local inbox read is not signed remote queue admission.
     if (this.storageError) throw new Error("delivery journal unavailable");
-    if (this.held(id)) return undefined;
+    if (this.held(id) && !(options.allowNeedsReviewHold === true && this.pullMayReadBehindNeedsReview(id))) return undefined;
     const queue = this.queues.get(id) ?? [];
     this.dropIrrelevant(id, queue);
     const preface = this.prefaces.get(id);
@@ -1472,6 +1510,15 @@ export class Bus {
     return out;
   }
 
+  /** Explicit inbox reads may pass only a needs_review hold; every other recovery fence still blocks. */
+  private pullMayReadBehindNeedsReview(id: PeerId): boolean {
+    if (!this.journal || this.closed || this.storageError || !this.isRostered(id) || this.recoveryHeld || this.paused.has(id) || this.opts.deliveryHeld?.(id) === true) return false;
+    if (this.pendingOutcomes.some(row => row.peer === id)) return false;
+    const unresolved = this.journal.unresolved(id);
+    return unresolved.some(row => row.state === "needs_review") &&
+      unresolved.every(row => row.state === "needs_review" || row.state === "queued");
+  }
+
   private async drain(id: PeerId): Promise<void> {
     if (this.storageError || this.draining.has(id) || !this.peers.has(id)) return;
     if (remoteId(id)) this.expireRemoteQueues();

package/src/hub/child-process.ts

@@ -7,6 +7,8 @@ import { withoutOrcaEnv } from "./orca-env.ts";
  * lifecycle calls could bypass the machine recovery lock.
  */
 export function childEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  // Keep the caller's environment for person-owned native launch paths; peer and helper
+  // children that must not inherit Orca use peerChildEnv or withoutOrcaEnv explicitly.
   const env = { ...source };
   delete env.AGENTHUB_RECOVERY_OPERATION;
   delete env.AGENTHUB_RECOVERY_CONDUCTOR;
@@ -20,15 +22,15 @@ export function childEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.Proces
  * typed or started there has the console's identity, whatever started the hub.
  */
 export function personEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
-  // The Orca terminal the hub itself was started in is not this new terminal: a launch there must not record it as its own, so every ORCA_ variable goes (#613).
   const env = withoutOrcaEnv(childEnv(source));
   for (const name of ["CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID", "AGENTHUB_CHANNEL", "AGENTHUB_PEER_ID", "AGENTHUB_UNATTENDED"]) delete env[name];
   return env;
 }
 
 /** Every native child owns its marker; caller vendor markers must not leak across peers (#193). */
-export function peerChildEnv(peer: string, source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
-  const env = childEnv(source);
+export function peerChildEnv(peer: string, source: NodeJS.ProcessEnv = process.env, options: { preserveOrca?: true } = {}): NodeJS.ProcessEnv {
+  const inherited = childEnv(source);
+  const env = options.preserveOrca ? inherited : withoutOrcaEnv(inherited);
   delete env.CLAUDECODE;
   delete env.CLAUDE_CODE_SESSION_ID;
   delete env.CODEX_THREAD_ID;
@@ -60,7 +62,7 @@ export function parseProcessTable(text: string): ProcRow[] {
 
 const PS = ["ps", "-axo", "pid=,ppid=,pgid=,stat=,lstart=,command="];
 // `lstart` is local time: one zone for every reader, or a reader in another zone sees every identity as changed.
-const PS_OPTIONS = { env: { ...process.env, LC_ALL: "C", TZ: "UTC" }, detached: true } as const;
+const PS_OPTIONS = { env: { ...withoutOrcaEnv(childEnv(process.env)), LC_ALL: "C", TZ: "UTC" }, detached: true } as const;
 /** The rows of one read, or undefined when they do not show the reader: a parse that found nothing is not a table. */
 const own = (text: string) => { const rows = parseProcessTable(text); return rows.some((row) => row.pid === process.pid) ? rows : undefined; };
 

package/src/hub/config-apply.ts

@@ -27,6 +27,7 @@ import { peerRosterConfig, staleInstanceKey } from "./roster.ts";
 import { CHARACTER_IDS } from "../pet/characters.ts";
 import { autonomyOwnership, checkSettingValue, settingDef } from "./settings.ts";
 import { petPalette } from "../pet/config.ts";
+import { parseSpecsConfig } from "./specs-config.ts";
 
 export type ApplyClass = "live" | "next use" | "restart";
 export interface ApplyRule { applies: ApplyClass; reason?: string }
@@ -202,6 +203,7 @@ const schema: Record<string, Check> = {
   pii: block({ paths: strings }), data: block({ readonly: strings }),
   text_projection: v => { projectionConfig(v); },
   corpus: v => { corpusConfig(v); },
+  specs: (v, k) => { block({ enabled: bool, review: words(["off", "report", "require"]), roots: strings, stamps_file: text })(v, k); parseSpecsConfig(v); },
   conductor: block({ feed: words(["own", "all", "off"]), approval_wait_s: number(0, 2_147_483_647 / 1000) }),
   budget: block({ gate: number(0, 1), stale_min: timerMinutes, poll_min: timerMinutes, checkpoint_timeout_s: timerSeconds, kimi_tokens_5h: number(0), wait_max_min: number(0) }),
   context: block({ gate: number(0, 1), stale_min: timerMinutes, max_assignment_used: number(0, 1) }),
@@ -271,7 +273,7 @@ const restart: Record<string, string> = {
   profile: "Session tool schemas and profile contracts are bound at startup", profile_overrides: "Session tool schemas and profile contracts are bound at startup",
   text_projection: "Converter and cache ownership are bound at startup", corpus: "The corpus index is bound to its roots at startup", terminal: "Terminal provider is supplied by the daemon lifecycle", bench: "Benchmark execution environment is selected before work starts",
 };
-const live = new Set(["action_policy", "permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "invocation", "research", "snapshots", "tasks.wip_limits", "tasks.escalate_after", "tasks.auto_pull", "tasks.queue_backpressure", "schedules", "approvals.notify", "pet"]);
+const live = new Set(["action_policy", "permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "invocation", "research", "snapshots", "tasks.wip_limits", "tasks.escalate_after", "tasks.auto_pull", "tasks.queue_backpressure", "schedules", "approvals.notify", "pet", "specs"]);
 const nextMemory = new Set(["memory.inject_tokens", "memory.brief_items", "memory.suggest_edges"]);
 /** Closed top-level schema; leaf overrides retain the existing session/runtime boundaries. */
 export function configApply(key: string, scopes: readonly ConfigIdentityScope[] = []): ApplyRule {
@@ -279,6 +281,7 @@ export function configApply(key: string, scopes: readonly ConfigIdentityScope[]
   if (!(Object.hasOwn(schema, top) || top === "permission" || top === "routing")) return fail(key, "unknown configuration key");
   if (top !== "routing" && top !== "permission" && key.includes(".")) {
     const special: Record<string, readonly string[]> = {
+      specs: ["enabled", "review", "roots", "stamps_file"],
       task_sweep: ["enabled", "auto_reassign", "no_writes_turns", "interval_s", "unaccepted_min", "idle_min", "review_min", "ready_min", "ladder_min"],
       checks: ["timeout_s", "runner", "remote", ...CLASSES], terminal: ["open"], start: ["agents"],
     };

package/src/hub/config-edit.ts

@@ -132,7 +132,7 @@ function topLevel(lines: readonly string[]): { end: number; spans: Map<string, [
  * Edits `mode` and `required_checks` line by line. Every line the edit does not touch keeps its own ending, so a one-key change never
  * rewrites a CRLF checkout; a line the edit writes or adds takes the ending of the first line break the file has (LF for a new file).
  */
-function editSdlcText(text: string | null, set: ConfigEditSet[]): string | null {
+export function editSdlcText(text: string | null, set: ConfigEditSet[]): string | null {
   const raw = text === null ? [] : text.split("\n");
   const trailing = raw.length > 0 && raw.at(-1) === "";
   if (trailing) raw.pop();

package/src/hub/config-tier.ts

@@ -39,6 +39,7 @@ const isObject = (value: unknown): value is Record<string, unknown> => !!value &
 export function configTier(file: ConfigEditFile, path: readonly string[], value?: unknown, held?: unknown): ConfigTier {
   if (!path.length || path.some(part => typeof part !== "string" || !part || part.length > 64 || UNSAFE.has(part) || /[\s\x00-\x1f]/.test(part))) return refuse("invalid configuration path");
   const key = path.join(".");
+  if (file === "config.local.json" && path[0] === "specs" && path.length === 2 && ["enabled", "review", "roots", "stamps_file"].includes(path[1]!)) return { tier: 2 };
   if (file === "sdlc.toml") return path.length === 1 && (SDLC_KEYS as readonly string[]).includes(path[0]!) ? { tier: 2 } : refuse(`sdlc.${key} is not editable here: only mode and required_checks are; edit .agenthub/sdlc.toml in your editor`);
   if (registryKey(key)) return { refused: `${key} is already editable with ahub settings set ${key}; nothing was written` };
   if (path[0] === "research" && path[1] === "runners") {

package/src/hub/control-client.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { projectContext } from "./project.ts";
+import { newToolRequestId, TOOL_WRITE_FEATURE, toolWriteOperation, toolWriteUnknownReply, toolWriteRefusedReply } from "./tool-request.ts";
 import { externalAdapterMetadata, externalInstanceCatalog, type ExternalInstanceCatalog, type ExternalAdapterMetadata } from "../adapters/external-metadata.ts";
 import { negotiateProtocol, protocolWindow, type ProtocolWindow } from "./protocol-window.ts";
 
@@ -12,7 +13,8 @@ export function stateDirFor(cwd: string): string {
 export const PROTOCOL = 17;
 /** The descriptor's legacy protocol field remains this floor for previous published clients. */
 export const PROTOCOL_MIN = 16;
-export const DAEMON_FEATURES = ["project_autonomy", "conductor_recovery", "encrypted_rooms", "external_adapter_instances", "external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "invocation", "recovery_deferred_hub", "peer_instances", "role_stages", "task_planners", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated", "action_policy_floor", "calendar_schedules", "research_records", "research_dispatch", "research_dropped_offers", "research_experiments", "research_comparisons", "research_runners", "task_handoff", "session_identity", "schema_guard"] as const;
+// Literal metadata is read without executing a recovery target; consistency is pinned in tests.
+export const DAEMON_FEATURES = ["project_autonomy", "conductor_recovery", "encrypted_rooms", "external_adapter_instances", "external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "invocation", "recovery_deferred_hub", "peer_instances", "role_stages", "task_planners", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated", "action_policy_floor", "calendar_schedules", "research_records", "research_dispatch", "research_dropped_offers", "research_experiments", "research_comparisons", "research_runners", "task_handoff", "session_identity", "schema_guard", "design_specs", "queue_discard_states", "tool_write_idempotency"] 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, 16, PROTOCOL] as const;
 
@@ -221,20 +223,42 @@ export class ControlClient {
   request(msg: Record<string, unknown>, timeoutMs = 30_000, signal?: AbortSignal): Promise<any> {
     if (this.ws.readyState !== WebSocket.OPEN || this.closing && msg.t !== "request_cancel") return Promise.resolve({ ok: false, error: "hub connection is not open" });
     const invocation = msg.t === "task" && msg.op === "hub_invoke";
+    const operation = toolWriteOperation(msg), write = operation !== undefined;
+    const keyedWrite = write && operation !== "hub_delivery_done";
+    if (keyedWrite && msg.args && typeof msg.args === "object" && !Array.isArray(msg.args) && Object.hasOwn(msg.args, "request_id")) {
+      const { request_id: key, ...args } = msg.args as Record<string, unknown>;
+      if (typeof key !== "string" || !key || key.length > 256 || /[\p{Cc}\p{Cf}]/u.test(key)
+        || msg.requestId !== undefined && msg.requestId !== key) {
+        return Promise.resolve(toolWriteRefusedReply(msg, undefined, "request_id must be a non-empty echoed request key and agree with requestId"));
+      }
+      msg = { ...msg, args, requestId: key };
+    }
+    if (keyedWrite && msg.requestId !== undefined && !this.features.includes(TOOL_WRITE_FEATURE)) {
+      return Promise.resolve(toolWriteRefusedReply(msg, typeof msg.requestId === "string" ? msg.requestId : undefined,
+        "this daemon does not advertise replay protection; nothing was resubmitted"));
+    }
+    let wire = msg;
+    if (keyedWrite && this.features.includes(TOOL_WRITE_FEATURE) && msg.requestId === undefined) {
+      try { wire = { ...msg, requestId: newToolRequestId(this.instanceId ?? "") }; }
+      catch { return Promise.resolve({ ok: false, error: "write request identity is unavailable; inspect ahub status before retrying" }); }
+    }
+    const requestId = typeof wire.requestId === "string" ? wire.requestId : undefined;
+    const uncertain = (cause: string) => toolWriteUnknownReply(wire, requestId,
+      this.features.includes(TOOL_WRITE_FEATURE) ? cause : `${cause}; this daemon does not advertise replay protection`);
     timeoutMs = controlRequestTimeout(msg, timeoutMs);
     if (signal?.aborted) return Promise.resolve({ ok: false, error: "hub request cancelled before sending" });
     const rid = this.nextRid++;
     return new Promise((resolve) => {
       let timer: ReturnType<typeof setTimeout> | undefined;
       const done = (reply: any) => {
-        this.pending.delete(rid); this.invocations.delete(rid); clearTimeout(timer); signal?.removeEventListener("abort", aborted); resolve(reply);
+        this.pending.delete(rid); this.invocations.delete(rid); clearTimeout(timer); signal?.removeEventListener("abort", aborted); resolve(write && reply?.error === "hub connection closed" ? uncertain(reply.error) : reply);
       };
       const abandon = (error: string) => {
         if (!this.pending.has(rid)) return;
         if (invocation && this.ws.readyState === WebSocket.OPEN) {
           try { this.ws.send(JSON.stringify({ t: "request_cancel", request: rid })); } catch { /* Socket close also withdraws admission. */ }
         }
-        done({ ok: false, error: invocation ? `${error}; invocation admission unconfirmed, inspect before retrying` : error });
+        done(write ? uncertain(error) : { ok: false, error: invocation ? `${error}; invocation admission unconfirmed, inspect before retrying` : error });
       };
       const aborted = () => abandon("hub request cancelled");
       this.pending.set(rid, done);
@@ -242,7 +266,7 @@ export class ControlClient {
       signal?.addEventListener("abort", aborted, { once: true });
       if (signal?.aborted) { aborted(); return; }
       timer = timeoutMs ? setTimeout(() => abandon(`no answer from the hub within ${Math.round(timeoutMs / 1000)} s`), timeoutMs) : undefined;
-      try { this.ws.send(JSON.stringify({ ...msg, rid })); }
+      try { this.ws.send(JSON.stringify({ ...wire, rid })); }
       catch { abandon("hub request could not be sent"); }
     });
   }