@staix/agent-hub 0.27.0 → 0.28.0

package/src/hub/delivery-hints.ts

@@ -3,7 +3,7 @@ import { KINDS, sanitize, type Kind } from "./envelope.ts";
 export const DELIVERY_RETRY_WARNING = sanitize("Hub redelivery warning: An earlier attempt of this delivery is uncertain; check for its effects before acting.");
 export interface HeldDeliveryHints {
   count: number;
-  rows: { id: string; senders: string[]; kinds: Kind[]; createdAt: number }[];
+  rows: { id: string; revision?: number; senders: string[]; kinds: Kind[]; createdAt: number }[];
   truncated: boolean;
 }
 export function heldDeliveryHints(rows: readonly HeldDeliveryHints["rows"][number][], count = rows.length): HeldDeliveryHints {
@@ -23,8 +23,11 @@ export function renderHeldHint(value: unknown, now = Date.now(), recipientRetry
     if (!Number.isSafeInteger(held.count) || held.count < 1 || !Array.isArray(held.rows) || held.rows.length > 32 || held.rows.length > held.count || typeof held.truncated !== "boolean" || Buffer.byteLength(JSON.stringify(held), "utf8") > 4096) return "";
     if (held.rows.some(row => !row || typeof row !== "object" || typeof row.id !== "string" || !row.id.length || row.id.length > 256 || !Number.isFinite(row.createdAt) || !Array.isArray(row.senders) || !Array.isArray(row.kinds) || row.senders.some(sender => typeof sender !== "string" || sender.length > 256) || row.kinds.some(kind => !kinds.has(kind)))) return "";
   } catch { return ""; }
-  const rows = held.rows.map(row => `${sanitize(row.id)} from ${row.senders.map(sanitize).join(",")} kind ${row.kinds.join(",")} age ${Math.max(0, Math.floor((now - row.createdAt) / 1000))}s`);
-  const action = recipientRetry ? "Use hub_delivery_retry {delivery_id} for one retry of your own uncertain row; check for earlier effects. A repeated uncertain retry needs the person." : "Ask the person to resolve these held deliveries; this delivery-only peer cannot initiate recipient retry.";
+  const rows = held.rows.map(row => `${sanitize(row.id)}${Number.isSafeInteger(row.revision) && row.revision! >= 0 ? ` revision ${row.revision}` : ""} from ${row.senders.map(sanitize).join(",")} kind ${row.kinds.join(",")} age ${Math.max(0, Math.floor((now - row.createdAt) / 1000))}s`);
+  const resolvable = held.rows.some(row => Number.isSafeInteger(row.revision) && row.revision! >= 0);
+  const action = resolvable
+    ? `Use hub_delivery_resolve {delivery_id, revision, action, reason} to confirm completion or discard your own held row. ${recipientRetry ? "Use hub_delivery_retry only to request its one uncertain redelivery; check for earlier effects." : "Retry remains person-only for this delivery mode."}`
+    : `Ask the person to resolve these held deliveries because this hint has no usable revision. ${recipientRetry ? "A retry may be requested with hub_delivery_retry {delivery_id}; check for earlier effects." : "Retry remains person-only for this delivery mode."}`;
   const out = `Held hub deliveries: ${held.count}${held.truncated ? " (metadata truncated)" : ""}\n${rows.join("\n")}\n${action}`;
   return Buffer.byteLength(out, "utf8") <= 4096 ? out : `Held hub deliveries: ${held.count} (metadata truncated; ask the person to inspect the queue).`;
 }

package/src/hub/delivery-journal.ts

@@ -895,8 +895,8 @@ export class DeliveryJournal {
   heldDeliveryHints(peer: string) {
     this.ensureOpen();
     const count = Number((this.db.query("SELECT COUNT(*) AS n FROM deliveries WHERE project_id = ? AND peer = ? AND state = 'needs_review'").get(this.projectId, peer) as { n: number }).n);
-    const rows = this.db.query("SELECT d.id, d.created_at, (SELECT json_group_array(DISTINCT json_extract(env.value, '$.from')) FROM json_each(d.originals) env) AS senders, (SELECT json_group_array(DISTINCT json_extract(env.value, '$.kind')) FROM json_each(d.originals) env) AS kinds FROM deliveries d WHERE d.project_id = ? AND d.peer = ? AND d.state = 'needs_review' ORDER BY d.created_at, d.id LIMIT 33").all(this.projectId, peer) as { id: string; created_at: number; senders: string; kinds: string }[];
-    return heldDeliveryHints(rows.map(row => ({ id: row.id, createdAt: row.created_at, senders: JSON.parse(row.senders) as string[], kinds: JSON.parse(row.kinds) as Kind[] })), count);
+    const rows = this.db.query("SELECT d.id, d.revision, d.created_at, (SELECT json_group_array(DISTINCT json_extract(env.value, '$.from')) FROM json_each(d.originals) env) AS senders, (SELECT json_group_array(DISTINCT json_extract(env.value, '$.kind')) FROM json_each(d.originals) env) AS kinds FROM deliveries d WHERE d.project_id = ? AND d.peer = ? AND d.state = 'needs_review' ORDER BY d.created_at, d.id LIMIT 33").all(this.projectId, peer) as { id: string; revision: number; created_at: number; senders: string; kinds: string }[];
+    return heldDeliveryHints(rows.map(row => ({ id: row.id, revision: row.revision, createdAt: row.created_at, senders: JSON.parse(row.senders) as string[], kinds: JSON.parse(row.kinds) as Kind[] })), count);
   }
   /** Explicit resolutions, not automatic safe failures, consume the immutable originals' retry lineage. */
   retryEvidence(peer: string, originals: readonly Envelope[]): "unused" | "used" | "unknown" {
@@ -993,7 +993,12 @@ export class DeliveryJournal {
       if (prior) return this.get(id)!;
       const current = this.get(id);
       if (!current) throw new Error(`unknown delivery ${id}`);
-      if (actor.startsWith("peer:") && (action !== "retry" || current.peer !== actor.slice(5) || current.state !== "needs_review" || this.retryEvidence(current.peer, current.originals) !== "unused")) throw new Error("recipient retry unavailable; inspect the held delivery or ask the person");
+      if (actor.startsWith("peer:")) {
+        const peer = actor.slice(5);
+        const recipientRetry = action === "retry" && current.peer === peer && current.state === "needs_review" && this.retryEvidence(current.peer, current.originals) === "unused";
+        const ownerDisposition = (action === "completed" || action === "discard") && current.peer === peer && current.state === "needs_review";
+        if (!recipientRetry && !ownerDisposition) throw new Error("recipient delivery resolution unavailable; inspect the held delivery or ask the person");
+      }
       if (current.revision !== revision)
         throw new Error(`stale delivery revision for ${id}`);
       if (
@@ -1037,6 +1042,12 @@ export class DeliveryJournal {
       return result;
     })();
   }
+  /** #1096: the ids of every delivery an operator action (completed, retry, discard) already settled. One query, so a list of any length costs one read. */
+  resolvedIds(): Set<string> {
+    this.ensureOpen();
+    const rows = this.db.query("SELECT DISTINCT delivery_id FROM resolution_history WHERE project_id=?").all(this.projectId) as { delivery_id: string }[];
+    return new Set(rows.map(row => row.delivery_id));
+  }
   resolution(id: string): { action: JournalResolution; reason: string; observedRevision: number; actor: string } | undefined {
     const row = this.db.query("SELECT action,reason,observed_revision,actor FROM resolution_history WHERE project_id=? AND delivery_id=? ORDER BY id DESC LIMIT 1").get(this.projectId, id) as { action: JournalResolution; reason: string; observed_revision: number; actor: string } | null;
     return row ? { action: row.action, reason: row.reason, observedRevision: row.observed_revision, actor: row.actor } : undefined;

package/src/hub/hub-tools.ts

@@ -8,7 +8,7 @@ import { NOTE_KINDS } from "./envelope.ts";
 
 /** Restricted to the fixed current-child tools server, never an ordinary peer tool. */
 /** The fixed MCP surface of a current owned implementer child; independent of broader project roles. */
-export const IMPLEMENTER_HUB_TOOL_NAMES: readonly string[] = Object.freeze(["hub_task_accept", "hub_task_decline", "hub_task_done", "hub_checkpoint", "hub_send", "hub_task_show", "hub_task_propose", "hub_remember", "hub_inbox", "hub_permission_request", "hub_study_show", "hub_experiment_show", "hub_experiment_record", "hub_study_handoff"]);
+export const IMPLEMENTER_HUB_TOOL_NAMES: readonly string[] = Object.freeze(["hub_task_accept", "hub_task_decline", "hub_task_done", "hub_checkpoint", "hub_send", "hub_task_show", "hub_task_propose", "hub_remember", "hub_inbox", "hub_permission_request", "hub_study_show", "hub_experiment_show", "hub_experiment_record", "hub_study_handoff", "hub_specs", "hub_delivery_resolve"]);
 
 export const IMPLEMENTER_PERMISSION_TOOL = {
   name: "hub_permission_request",
@@ -21,6 +21,7 @@ export const ACTIONABLE_MESSAGE_INSTRUCTION = "Do not use [FYI] for PR ready, do
 
 const str = { type: "string" } as const;
 const id = { type: "integer", description: "task id" } as const;
+const toolWriteRequestId = { type: "string", minLength: 1, maxLength: 256, pattern: "^v1/[A-Za-z0-9._-]{1,128}/[1-9][0-9]{0,15}/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$", description: "control-transport-only request_id returned by an outcome-unknown write; inspect first and retry with the same key and identical arguments only if absent. Direct in-process tool calls cannot use request_id" } as const;
 const refs = {
   type: "object",
   description: "where the work lives",
@@ -28,6 +29,7 @@ const refs = {
   additionalProperties: false,
 } as const;
 const list = (description: string) => ({ type: "array", items: str, description }) as const;
+const specAck = { type: "array", maxItems: 20, items: { type: "object", properties: { id: { type: "string", minLength: 1, maxLength: 160 }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, required: ["id", "reason"], additionalProperties: false } } as const;
 /** #509a: files a task delivered. The hub hashes them itself; there is no hash field, and one is refused. */
 const deliverablesSchema = {
   type: "array", minItems: 1, maxItems: 16,
@@ -78,7 +80,7 @@ export interface HubTool {
 const tool = (name: string, description: string, properties: Record<string, unknown>, required: string[] = []): HubTool => ({
   name,
   description,
-  inputSchema: { type: "object", properties, required, additionalProperties: false },
+  inputSchema: { type: "object", properties: name === "hub_review" || name === "hub_task_propose" ? { ...properties, request_id: toolWriteRequestId } : properties, required, additionalProperties: false },
 });
 
 /** #601: a campaign's contract and handoff are model-written text about its sources. The write tools' arguments and every study result stay out of memory capture. */
@@ -95,6 +97,7 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_check_result", "Read your current task-bound isolated check receipt. Stale ownership/generation refuses; output is policy screened.", { run: str }, ["run"]),
   tool("hub_check_cancel", "Cancel your task-bound isolated check; only its owner or the person may cancel.", { run: str }, ["run"]),
   tool("hub_delivery_retry", "Request one redelivery of your own needs_review delivery. An earlier attempt may have effects: inspect those effects before acting. Refuses another peer's row or any lineage already explicitly retried; a repeated uncertain row needs the person. Never completes/discards a delivery or changes task state.", { delivery_id: { type: "string", minLength: 1, maxLength: 256 } }, ["delivery_id"]),
+  tool("hub_delivery_resolve", "Confirm completion or discard your own needs_review delivery using the revision shown by hub_inbox. Requires a reason. Never replays the delivery or changes task state; another peer's row and stale revisions are refused.", { delivery_id: { type: "string", minLength: 1, maxLength: 256 }, revision: { type: "integer", minimum: 0 }, action: { type: "string", enum: ["completed", "discard"] }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, ["delivery_id", "revision", "action", "reason"]),
   tool("hub_backlog_list", "Read public backlog cards with planning revisions. Configured planners only; PII remains a stub.", {}),
   tool("hub_backlog_plan", "Plan an unpinned backlog item outside frozen releases with the revision you read and a bounded reason. Omit fields or give {} for a note-only revision. fields.sdlc accepts only repo/issue identity on unstarted backlog work; relinking clears old spec acceptance. A person's rank is retained. Actual dates cannot be set.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", maxLength: 1000 }, fields: { type: "object", properties: { sdlc: { type: "object", minProperties: 1, properties: { repo: { type: ["string", "null"], maxLength: 400 }, issue: { type: ["integer", "null"], minimum: 1 } }, additionalProperties: false }, rank: { type: ["integer", "null"], minimum: 0 }, priority: { type: ["integer", "null"], minimum: 0, maximum: 3 }, release: { type: ["integer", "null"], minimum: 1 }, plannedStart: { type: ["integer", "null"], minimum: 1 }, due: { type: ["integer", "null"], minimum: 1 }, deps: { type: "array", maxItems: 64, uniqueItems: true, items: { type: "integer", minimum: 1 } }, reserved: { type: ["string", "null"], minLength: 1, maxLength: 32 } }, additionalProperties: false } }, ["id", "revision", "reason"]),
   tool("hub_backlog_pull", "Reserve a WIP slot and pull ready unpinned backlog work into To Do at its current revision. Preserves person order/reservations and frozen scope; pending unowned work can be undone with hub_backlog_undo.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, ["id", "revision", "reason"]),
@@ -115,13 +118,14 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_release_cut", "Freeze an active release's approved scope after host resource admission and fresh peer quota checks. Unknown evidence defers; no publish, tag, upgrade or authorization.", { id, revision: { type: "integer", minimum: 0 } }, ["id", "revision"]),
   tool("hub_release_list", "Read public release scope and planned/actual dates for phased planning. Configured planners only.", {}),
 
-  tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs, set refs.repo for work in another repository, and when you claim work, a plan; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, role: { type: "string", description: "catalog role id for this task class; guidance only, no routing or authority change" }, refs, plan, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it. With after, the owner is reserved: offered the task first once it is ready" }, after: { type: "array", items: { type: "integer" }, description: "ids of tasks that must be approved first; until then this one waits, offered to nobody, and cannot be claimed" }, backlog: { type: "boolean", description: "stage unoffered work; owner is only a reservation, even when naming yourself" }, urgent: { type: "boolean", description: "hand it over even when its owner is paused for quota only briefly" }, goal: { type: "string", description: "id of this project's long-term task (ahub goal list) the work is part of" } }, ["title"]),
+  tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs, set refs.repo for work in another repository, and when you claim work, a plan; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, role: { type: "string", description: "catalog role id for this task class; guidance only, no routing or authority change" }, refs, plan, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it. With after, the owner is reserved: offered the task first once it is ready" }, after: { type: "array", items: { type: "integer" }, description: "ids of tasks that must be approved first; until then this one waits, offered to nobody, and cannot be claimed" }, backlog: { type: "boolean", description: "stage unoffered work; owner is only a reservation, even when naming yourself" }, urgent: { type: "boolean", description: "hand it over even when its owner is paused for quota only briefly" }, needs_network: { type: "boolean", description: "the work needs the network (a package registry, git fetch or push, an API); it is never offered to a peer whose shell has none" }, needs_worktree: { type: "boolean", description: "the work needs its own git worktree on a task branch (the repository rule); it is never offered to a sandboxed peer, which cannot create one" }, goal: { type: "string", description: "id of this project's long-term task (ahub goal list) the work is part of" } }, ["title"]),
   tool("hub_task_accept", "Take a task that was assigned to you, with your plan for it. Set refs.repo for work in another repository; acceptance may correct only that repository metadata.", { id, plan: acceptPlan, refs: { ...refs, properties: { repo: refs.properties.repo } } }, ["id"]),
   tool("hub_task_cancel", "Cancel proposed/backlog work you proposed as its configured planner, including work an owner accepted and then declined while it has no execution, branch, commit or PR evidence; work with any such evidence is person-only. Keeps history and does not stop a native turn or delete files.", { id, reason: str, superseded_by: str, revision: { type: "integer", minimum: 0 } }, ["id", "reason"]),
   tool("hub_task_decline", "Pass on a task assigned to you; the hub offers it to the next peer. A plain decline is a lasting refusal: you are never offered this task again. Pass capacity: true when you only have no room right now: you are skipped for this move only, and a later reroute or planner pull may offer it to you again.", { id, reason: str, capacity: { type: "boolean" } }, ["id"]),
-  tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs; no duplicate hub_send chat is needed. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs, deliverables: deliverablesSchema }, ["id", "summary"]),
+  tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs; no duplicate hub_send chat is needed. If a covering spec is unchanged, update it or provide spec_ack with a public reason for each unchanged spec. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs, deliverables: deliverablesSchema, spec_ack: specAck }, ["id", "summary"]),
   tool("hub_sdlc_record", "Record artifact ids or claimed local checks on your task. This grants no authority or external-check evidence. Only its owner/reviewer or the person may record; only its reviewer/person may name a reviewed head or phase checklist. Phase evidence refs are content hashes, not external verification.", { id, receipt: { type: "object", properties: { deliverables: deliverablesSchema, stage: { type: "string", enum: ["spec", "plan", "implement", "review", "verify", "merge", "release"] }, repo: str, issue: id, pr: id, localHead: str, localResult: { type: "string", enum: ["passed", "failed", "unknown"] }, reviewedHead: str, phase: { type: "object", properties: { id: str, head: str, tasks: { type: "array", maxItems: 64, items: { type: "object", properties: { id, after: { type: "array", maxItems: 16, items: id } }, required: ["id", "after"], additionalProperties: false } }, criteria: { type: "array", maxItems: 32, items: { type: "object", properties: { id: str, required: { type: "boolean" }, result: { type: "string", enum: ["verified", "failed", "unverified"] }, refs: { type: "array", maxItems: 8, items: str } }, required: ["id", "required", "result", "refs"], additionalProperties: false } } }, required: ["id", "tasks", "criteria"], additionalProperties: false } }, additionalProperties: false } }, ["id", "receipt"]),
-  tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested", "cancelled"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
+  tool("hub_task_list", "The task board, newest updated first, 50 compact rows (id, state, owner, reviewer, title) per call. The reply is {tasks, total, next?}: pass next as cursor for the following page. Use ids for full rows of specific tasks, or detail: true for full rows of a page. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested", "cancelled"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" }, limit: { type: "integer", minimum: 1, maximum: 200, description: "rows per page, default 50" }, cursor: { type: "string", description: "the next value from the previous reply, unchanged" }, ids: { type: "array", minItems: 1, maxItems: 200, items: { type: "integer", minimum: 1 }, description: "full rows for exactly these task numbers; no paging" }, detail: { type: "boolean", description: "full rows instead of compact rows" } }),
+  tool("hub_specs", "Read the project's design-spec checks or find specs covering repository-relative paths. Read-only; at most 20 result items are returned. Does not reveal private task data.", { action: { type: "string", enum: ["check", "covers"] }, paths: { type: "array", maxItems: 32, items: { type: "string", minLength: 1, maxLength: 2000 } } }, ["action"]),
   tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, findings: reviewFindings, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet; when the review request lists acceptance criteria, start an item with its id (\"AC1: what is missing\") so the verdict names it" }, coverage: { type: "object", description: "the review brief's reviewable paths you read (reviewed) and any you did not (skipped, each with a reason); in enforce an approval must account for every one", properties: { reviewed: { type: "array", items: str }, skipped: { type: "array", items: { type: "object", properties: { path: str, reason: str }, required: ["path", "reason"] } } } } }, ["id", "verdict"]),
   tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
   tool("hub_source_read", "Read a registered source snapshot. Unicode character range, at most 32 KiB of sanitized UTF-8 text with next character offset. Private sources return only id, kind and private unless called by the on-prem worker inside a PII task. Excluded from capture.", { id: { type: "string", pattern: "^src:[0-9a-f]{16}$" }, range: { type: "object", properties: { offset: { type: "integer", minimum: 0 }, length: { type: "integer", minimum: 1 } }, required: ["offset", "length"], additionalProperties: false } }, ["id"]),
@@ -196,7 +200,7 @@ export function configuredToolContext(status: unknown, peer: string): ProjectToo
   return { startPeers, readOnly: readOnlyPeers.includes(peer) };
 }
 
-const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_capabilities", "hub_send", "hub_inbox", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_study_show", "hub_experiment_show", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "hub_source_read", "hub_status"]);
+const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_specs", "hub_capabilities", "hub_send", "hub_inbox", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_study_show", "hub_experiment_show", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "hub_source_read", "hub_status"]);
 /** Publication restricts exposure only; server-side authority remains mandatory for every call. */
 export function projectToolList<T extends { name: string }>(tools: T[], readOnly = false): T[] {
   return readOnly ? tools.filter(tool => READ_ONLY_PROJECT_TOOLS.includes(tool.name)) : tools;

package/src/hub/peers.ts

@@ -64,7 +64,7 @@ export interface PeerAdapter {
   /** Fixed-builtin native proof only; present undefined is unknown, not an absent proxy. */
   readonly frontendProxy?: FrontendProxyPort;
   /** Fixed operator notices from builtin native adapters, never provider text or native ids. */
-  readonly statusNotice?: { code: "unidentified-cancellation" | "qwen-detached" | "qwen-stalled"; message: string };
+  readonly statusNotice?: { code: "unidentified-cancellation" | "qwen-detached" | "qwen-stalled" | "jcode-headless-after-recovery"; message: string };
   /** Fixed builtins with session.nativeRevert only. Native conversation effects remain in the adapter. */
   revertTurn?(nativeTurn: string): Promise<void>;
   /** #445 C1: what this peer's native source lists right now (a probed version only), or an empty manifest. Never throws for an unprobed version; a transport failure rejects. */

package/src/hub/review-brief.ts

@@ -1,7 +1,9 @@
 import type { CodeFactResult, CodeSymbol } from "./code-facts.ts";
+import { sanitize } from "./envelope.ts";
 import { childEnv } from "./child-process.ts";
 import { hubGitSync } from "./git.ts";
 import { symbolsOverlap } from "./symbol-normalizer.ts";
+import type { SpecTaskReport } from "./board.ts";
 
 /**
  * #520: the review brief ahub builds itself, in place of `ocr delegate preview` and `rule`. Every reviewer gets the same
@@ -30,6 +32,22 @@ export interface ReviewBrief {
   /** Paths in the plain name list of the range that the brief does not list: read them directly. */
   unlisted: string[];
 }
+
+/** A bounded, public summary of the design specs affected by one exact task head. */
+export function renderSpecTaskReport(report: SpecTaskReport): string {
+  const head = /^[0-9a-f]{40}$/.test(report.head) ? report.head : "unknown";
+  const lines = [`Design specs at ${head}:`];
+  if (!report.complete) lines.push(`Spec inspection incomplete${report.reason ? `: ${report.reason}` : "; coverage is unknown"}.`);
+  if (report.errors > 0) lines.push(`spec errors: ${report.errors}; run ahub specs check.`);
+  for (const spec of report.unchanged.slice(0, 20)) {
+    const label = `${spec.id}${spec.path ? ` (${spec.path})` : ""}`;
+    lines.push(`spec not updated: ${label}${spec.reason ? `; acknowledged: ${spec.reason}` : ""}`);
+  }
+  for (const spec of report.changed.slice(0, 20)) lines.push(`spec updated: ${spec.id}${spec.path ? ` (${spec.path})` : ""}`);
+  if (report.truncated || report.unchanged.length > 20 || report.changed.length > 20) lines.push("Spec report truncated; run ahub specs check for the full report.");
+  if (report.complete && report.errors === 0 && report.unchanged.length === 0 && report.changed.length === 0) lines.push("No covering specs were found for the changed files.");
+  return sanitize(lines.join("\n"));
+}
 export interface BriefPolicy { privatePath(path: string): boolean; nameable(text: string): boolean }
 
 const MAX_FILES = 500, RULE_BYTES = 32_000, MAX_RULE_FILES = 8;

package/src/hub/routing.ts

@@ -7,7 +7,7 @@ import { join, resolve } from "node:path";
 import { CLASSES, type Task, type TaskClass } from "./board.ts";
 import { isGitHubRepository, specRefs } from "./spec-read.ts";
 
-export interface PeerCapabilities { tests: boolean; spec: boolean; testsReason?: string; specReason?: string; }
+export interface PeerCapabilities { tests: boolean; spec: boolean; testsReason?: string; specReason?: string; /** #1081: the peer's shell can reach the network (through the egress proxy or directly). Absent means unknown, never refused. */ network?: boolean; networkReason?: string; /** #1081: the peer can create the task worktree (`git worktree add` runs outside a hub sandbox, #270). Absent means unknown, never refused. */ worktree?: boolean; worktreeReason?: string; }
 import type { PeerId, PeerState } from "./envelope.ts";
 
 import { parseHubRoutes, type HubRoute } from "../models/route/config.ts";
@@ -289,7 +289,7 @@ export function currentRouting(cwd: string, log: (line: string) => void = () =>
   }
 }
 
-export type Signal = "pii" | "pii_path" | "long_context" | "urgent";
+export type Signal = "pii" | "pii_path" | "long_context" | "urgent" | "needs_network" | "needs_worktree";
 
 /** What the policy can see in a task. Context length is estimated from the referenced files, 3 characters per token as elsewhere. */
 export function detectSignals(task: Pick<Task, "title" | "detail" | "refs">, routing: Routing, cwd: string): Signal[] {
@@ -310,7 +310,7 @@ export function detectSignals(task: Pick<Task, "title" | "detail" | "refs">, rou
 /** A peer's entry in a peer-indexed map: own keys only, so a peer named `constructor` is never an inherited Object member. */
 export const peerEntry = <T>(map: Readonly<Record<string, T>> | undefined, peer: string): T | undefined => (map && Object.hasOwn(map, peer) ? map[peer] : undefined);
 
-export type RoutingRefusalCode = QueueBackpressureCode | "context-headroom" | "instance" | "family" | "tests" | "spec" | "roster" | "pull-only" | "not-attached" | "excluded" | "owner-admission" | "offline" | "paused" | "failing" | "pii" | "policy";
+export type RoutingRefusalCode = QueueBackpressureCode | "context-headroom" | "instance" | "family" | "tests" | "spec" | "network" | "worktree" | "roster" | "pull-only" | "not-attached" | "excluded" | "owner-admission" | "offline" | "paused" | "failing" | "pii" | "policy";
 export interface RoutingRefusal { peer: PeerId; role: "owner" | "reviewer"; code: RoutingRefusalCode; reason: string }
 export interface Assignment {
   reviewSelection?: ReviewerPoolSelection;
@@ -490,6 +490,10 @@ export function assign(
       const caps = peerEntry(opts.capabilities, peer);
       if (needsTests && !caps?.tests) return deny("tests", `missing tests: ${caps?.testsReason ?? "capability unavailable"}`);
       if (needsSpec && !caps?.spec) return deny("spec", `missing spec: ${caps?.specReason ?? "capability unavailable"}`);
+      // #1081: work that declares it needs the network is never offered to a peer whose shell has none. Unknown (no `network` entry) is not a refusal.
+      if (task.signals.includes("needs_network") && caps?.network === false) return deny("network", `no network: ${caps.networkReason ?? "its shell cannot reach the network"}`);
+      // #1081: work that declares it needs a task worktree is never offered to a peer that cannot create one, so no branch ref is left behind by a refused accept.
+      if (task.signals.includes("needs_worktree") && caps?.worktree === false) return deny("worktree", `no worktree: ${caps.worktreeReason ?? "it cannot create the task worktree"}`);
     }
     if (opts.offRoster?.includes(peer)) return deny("roster", "off roster");
     const named = role === "owner" ? opts.namedOwner ?? reserved : opts.namedReviewer;

package/src/hub/settings.ts

@@ -81,6 +81,8 @@ export const SETTINGS: readonly SettingDef[] = [
   { key: "routing.stay_switch", group: "Routing", label: "Stay or switch (hub/auto and stage routes)", type: "enum", values: ["off", "shadow", "enforce"], store: "routing", applies: "live", risk: "raises", path: ["stay_switch"] },
   ...CLASSES.flatMap(perClass),
   { key: "research.enabled", group: "Switches", label: "Research records", type: "boolean", store: "config", applies: "live", risk: "safe", path: ["research", "enabled"] },
+  { key: "specs.enabled", group: "Switches", label: "Design specs and freshness", type: "boolean", store: "config", applies: "live", risk: "safe", path: ["specs", "enabled"] },
+  { key: "specs.review", group: "Switches", label: "Covering spec review", type: "enum", values: ["off", "report", "require"], store: "config", applies: "live", risk: "safe", path: ["specs", "review"] },
   { key: "approvals.notify", group: "Switches", label: "Desktop notice for a waiting approval", type: "boolean", store: "config", applies: "live", risk: "safe", path: ["approvals", "notify"] },
   { key: "snapshots.enabled", group: "Switches", label: "Per-turn snapshots", type: "boolean", store: "config", applies: "live", risk: "safe", path: ["snapshots", "enabled"] },
   { key: "coordination", group: "Switches", label: "Coordination of overlapping owners", type: "enum", values: ["advisory", "turn-free"], store: "config", applies: "next use", risk: "safe", path: ["coordination"] },

package/src/hub/specs-config.ts

@@ -0,0 +1,43 @@
+export type SpecsReview = "off" | "report" | "require";
+
+export interface SpecsConfig {
+  enabled: boolean;
+  review: SpecsReview;
+  roots: string[];
+  stamps_file: string;
+}
+
+export const DEFAULT_SPECS_CONFIG: Readonly<SpecsConfig> = Object.freeze({
+  enabled: true,
+  review: "report",
+  roots: [],
+  stamps_file: "",
+});
+
+function object(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function safeRelative(value: unknown): value is string {
+  if (typeof value !== "string" || !value.length || value.length > 1024 || value.startsWith("/") || value.startsWith("-") || /^[A-Za-z]:/.test(value) || value.includes("\\") || value.includes(":") || /[\u0000-\u001f\u007f]/.test(value)) return false;
+  const normalized = value.endsWith("/") ? value.slice(0, -1) : value;
+  return !!normalized && !normalized.split("/").some(part => part === ".." || part === "." || part === "");
+}
+
+function invalid(message: string, nextSteps: string): never { throw new Error(`${message}; ${nextSteps}`); }
+
+/** Filesystem-free parser shared by config loading and the specs engine. */
+export function parseSpecsConfig(value: unknown): SpecsConfig {
+  if (value === undefined) return { ...DEFAULT_SPECS_CONFIG, roots: [] };
+  if (!object(value)) invalid("specs must be an object", "use an object with enabled, review, roots and stamps_file fields");
+  if (Object.keys(value).some(key => !["enabled", "review", "roots", "stamps_file"].includes(key))) invalid("specs has an unknown field", "use only enabled, review, roots and stamps_file");
+  const enabled = value.enabled === undefined ? DEFAULT_SPECS_CONFIG.enabled : value.enabled;
+  const review = value.review === undefined ? DEFAULT_SPECS_CONFIG.review : value.review;
+  const roots = value.roots === undefined ? DEFAULT_SPECS_CONFIG.roots : value.roots;
+  const stampsFile = value.stamps_file === undefined ? DEFAULT_SPECS_CONFIG.stamps_file : value.stamps_file;
+  if (typeof enabled !== "boolean") invalid("specs.enabled must be a boolean", "set it to true or false");
+  if (review !== "off" && review !== "report" && review !== "require") invalid("specs.review is invalid", "choose off, report or require");
+  if (!Array.isArray(roots) || roots.length > 1024 || roots.some(root => !safeRelative(root))) invalid("specs.roots is invalid", "use at most 1024 repository-relative directories without dot segments");
+  if (stampsFile !== "" && !safeRelative(stampsFile)) invalid("specs.stamps_file is invalid", "use an empty value or one repository-relative path without dot segments");
+  return { enabled, review, roots: [...roots] as string[], stamps_file: stampsFile as string };
+}

package/src/hub/specs-task.ts

@@ -0,0 +1,108 @@
+import type { BriefFile } from "./review-brief.ts";
+import { parseSpecsConfig, SpecsEngine, type SpecsConfig, type SpecsCheckReport, type SpecsCoverReport } from "./specs.ts";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
+import { realPath } from "./project.ts";
+
+export interface SpecAck { id: string; reason: string }
+export interface SpecRef { id: string; path: string; title: string; reason?: string }
+export interface SpecTaskReport {
+  head: string;
+  complete: boolean;
+  errors: number;
+  unchanged: SpecRef[];
+  changed: SpecRef[];
+  truncated?: boolean;
+  reason?: string;
+}
+export interface SpecsStatus { specCount: number; documents: number; errors: number; stale: number; truncated: boolean }
+
+const UNAVAILABLE = new Set(["discovery-unavailable", "snapshot-unavailable", "coverage-unavailable"]);
+
+/** Host-bound repository inspection only. Tasks owns caller/privacy projection and every board write. */
+export class SpecTaskInspector {
+  private readonly engines = new Map<string, SpecsEngine>();
+  private readonly root: string;
+  constructor(root: string, private readonly config: () => SpecsConfig) { this.root = realPath(root); }
+
+  /** A positive absence only; unsafe or incomplete reads must not claim the block is missing. */
+  missingBlock(): boolean | undefined {
+    const file = join(this.root, "AGENTS.md");
+    let fd: number | undefined;
+    try {
+      const before = lstatSync(file);
+      if (!before.isFile() || before.isSymbolicLink() || before.size > 256 * 1024) return undefined;
+      fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+      const opened = fstatSync(fd);
+      if (opened.dev !== before.dev || opened.ino !== before.ino) return undefined;
+      const bytes = Buffer.alloc(before.size + 1);
+      let count = 0;
+      while (count < bytes.length) { const got = readSync(fd, bytes, count, bytes.length - count, count); if (!got) break; count += got; }
+      const text = bytes.subarray(0, count).toString("utf8"), after = lstatSync(file);
+      if (after.dev !== before.dev || after.ino !== before.ino || after.size !== before.size || after.mtimeMs !== before.mtimeMs) return undefined;
+      const begin = text.indexOf("<!-- AGENT_HUB_SPECS:BEGIN"), end = text.indexOf("<!-- AGENT_HUB_SPECS:END");
+      return begin < 0 || end < begin;
+    } catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT" ? true : undefined; }
+    finally { if (fd !== undefined) try { closeSync(fd); } catch { /* The optional hint must not break status. */ } }
+  }
+
+  private engine(commit?: string): SpecsEngine {
+    const config = parseSpecsConfig(this.config());
+    const key = JSON.stringify([config.roots, config.stamps_file, commit ?? "live"]);
+    const cached = this.engines.get(key);
+    if (cached) { this.engines.delete(key); this.engines.set(key, cached); return cached; }
+    const engine = new SpecsEngine(this.root, config, commit === undefined ? {} : { commit });
+    this.engines.set(key, engine);
+    // One live view and a small number of immutable submitted-head views, never an unbounded PR cache.
+    if (this.engines.size > 4) this.engines.delete(this.engines.keys().next().value!);
+    return engine;
+  }
+
+  notice(paths: readonly string[]): SpecsCoverReport | undefined {
+    const config = this.config();
+    if (!config.enabled || config.review === "off" || !paths.length) return undefined;
+    const report = this.engine().covers(paths);
+    return report.specs.length ? report : undefined;
+  }
+
+  read(action: "check", paths: readonly string[]): SpecsCheckReport;
+  read(action: "covers", paths: readonly string[]): SpecsCoverReport;
+  read(action: "check" | "covers", paths: readonly string[]): SpecsCheckReport | SpecsCoverReport;
+  read(action: "check" | "covers", paths: readonly string[]): SpecsCheckReport | SpecsCoverReport {
+    return action === "check" ? this.engine().check() : this.engine().covers(paths);
+  }
+
+  status(): SpecsStatus | undefined {
+    const config = this.config();
+    if (!config.enabled) return undefined;
+    const report = this.engine().check();
+    if (!report.specCount && !report.freshness.length && !(config.stamps_file && report.errors)) return undefined;
+    return { specCount: report.specCount, documents: report.freshness.length, errors: report.errors, stale: report.stale, truncated: report.truncated };
+  }
+
+  inspect(head: string, changedFiles: readonly BriefFile[] | undefined, options: { complete: boolean; acks?: readonly SpecAck[] }): SpecTaskReport | undefined {
+    const config = this.config();
+    if (!config.enabled || config.review === "off") return undefined;
+    // Commitless and explicitly empty changes carry no coverage obligation.
+    if (!/^[0-9a-f]{40}$/.test(head) || changedFiles?.length === 0 && options.complete) return undefined;
+    let engine: SpecsEngine, check: SpecsCheckReport;
+    try { engine = this.engine(head); check = engine.check(); }
+    catch { return { head, complete: false, errors: 0, unchanged: [], changed: [], reason: "submitted spec tree is unavailable" }; }
+    if (!check.specCount && !check.freshness.length && !config.stamps_file && !check.truncated && !check.errors) return undefined;
+    const coverage = engine.list();
+    const unavailable = coverage.items.some(item => UNAVAILABLE.has(item.code));
+    if (!options.complete || !changedFiles || coverage.truncated || unavailable) return { head, complete: false, errors: check.errors, unchanged: [], changed: [], truncated: coverage.truncated, reason: "spec coverage or submitted changed-file evidence is incomplete" };
+    const changedPaths = new Set(changedFiles.flatMap(file => [file.path, ...(file.oldPath ? [file.oldPath] : [])]));
+    const covers = engine.covers([...changedPaths]);
+    if (covers.items.some(item => UNAVAILABLE.has(item.code) || item.code === "invalid-cover-path")) return { head, complete: false, errors: check.errors, unchanged: [], changed: [], reason: "changed-file path coverage is unavailable" };
+    const acks = new Map((options.acks ?? []).map(ack => [ack.id, ack.reason]));
+    const changed: SpecRef[] = [], unchanged: SpecRef[] = [];
+    for (const spec of covers.specs) {
+      const row: SpecRef = { ...spec, ...(acks.has(spec.id) ? { reason: acks.get(spec.id)! } : {}) };
+      (changedPaths.has(spec.path) ? changed : unchanged).push(row);
+    }
+    const touchedSpec = coverage.specs.some(spec => changedPaths.has(spec.path));
+    if (!changed.length && !unchanged.length && !touchedSpec && !covers.truncated) return undefined;
+    return { head, complete: !covers.truncated, errors: check.errors, changed, unchanged, truncated: covers.truncated };
+  }
+}