@staix/agent-hub 0.29.0 → 0.31.0

package/src/hub/delivery-superseded.ts

@@ -33,6 +33,9 @@ export function supersededDeliveryReason(
     if (!Number.isSafeInteger(id)) return undefined;
     const task = board.get(id);
     if (!task) return undefined;
+    // Owner review packages and verdicts carry outcomes, not a reviewer assignment.
+    // A task/role move cannot prove that their recipient consumed them.
+    if (env.kind === "review" && env.refs.taskRecipient === "owner") return undefined;
     if (task.state === "cancelled") {
       if (typeof env.refs.taskCancelled === "number" && env.refs.taskCancelled === task.cancelled?.flowRevision) return undefined;
       reasons.add(`task #${task.id} cancelled`);
@@ -63,7 +66,7 @@ export function deliveryTaskContext(
     if (task.state === "cancelled") context.add(`task #${task.id} cancelled`);
     else if (task.state === "approved") context.add(`task #${task.id} approved`);
     else if (task.owner !== recipient && task.reviewer !== recipient) context.add(`task #${task.id} moved`);
-    else if ((env.kind === "review" || env.refs.taskRecipient === "reviewer") && (task.state !== "in_review" || task.reviewer !== recipient)) context.add(`task #${task.id} review moved`);
+    else if ((env.kind === "review" && env.refs.taskRecipient !== "owner" || env.refs.taskRecipient === "reviewer") && (task.state !== "in_review" || task.reviewer !== recipient)) context.add(`task #${task.id} review moved`);
   }
   return context.size ? [...context].join("; ") : undefined;
 }

package/src/hub/dogfood-read.ts

@@ -12,7 +12,8 @@ import type { ProfileName } from "./profiles.ts";
 import type { StampedEvent } from "./events.ts";
 
 export const DOGFOOD_BYTE_CAP = 16 * 1024 * 1024;
-const MAX_TASKS = 500, MAX_PRS = 16, MAX_CI_HEADS = 8, MAX_CI_READS = 32;
+/** MAX_PII bounds the PII inventory (ids and PR refs only), separately from the windowed task rows (#1147). */
+const MAX_TASKS = 500, MAX_PII = 2000, MAX_PRS = 16, MAX_CI_HEADS = 8, MAX_CI_READS = 32;
 const date = (value: unknown): number | undefined => typeof value === "string" && Number.isFinite(Date.parse(value)) ? Date.parse(value) : undefined;
 const id = (value: unknown): value is number => Number.isSafeInteger(value) && (value as number) > 0;
 const repoName = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value) && !value.startsWith("-");
@@ -51,13 +52,59 @@ export function dogfoodEvents(lines: Source<string[]>, since: number, until: num
   }
   return { data: out, available: lines.available, complete };
 }
-/** Bounded read-only board snapshot. Select no task title/detail or history note into the result. */
-export function dogfoodTasks(file: string): Source<DogfoodTask[]> {
+/** One PII task as the privacy inventory knows it: an id and its PR ref, never any text. */
+export interface PiiRef { id: number; repo?: string; pr?: number }
+/**
+ * #1147: every PII task of the board, read completely and independently of the scorecard window. Privacy depends only on a task's
+ * signals and its sdlc receipt, so only those are read. A row whose signals cannot be read (null, oversized, not a JSON array)
+ * could be a PII task, and a PII receipt that cannot be parsed hides its PR: both make the inventory incomplete, as does overflowing MAX_PII.
+ */
+export function dogfoodPiiInventory(file: string): Source<PiiRef[]> {
+  let db: Database | undefined;
+  try {
+    db = new Database(file, { readonly: true });
+    db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    const rows = db.query(`SELECT id, unreadable, receipt_cut, sdlc FROM (
+      SELECT id,
+        CASE WHEN signals IS NULL OR length(signals) > 65536 THEN 1 WHEN NOT json_valid(signals) THEN 1 WHEN json_type(signals) <> 'array' THEN 1 ELSE 0 END AS unreadable,
+        CASE WHEN signals IS NOT NULL AND length(signals) <= 65536 AND json_valid(signals) AND json_type(signals) = 'array'
+          THEN EXISTS (SELECT 1 FROM json_each(signals) WHERE value IN ('pii','pii_path')) ELSE 0 END AS pii,
+        (sdlc IS NOT NULL AND length(sdlc) > 65536) AS receipt_cut,
+        CASE WHEN length(sdlc) <= 65536 THEN sdlc END AS sdlc FROM tasks)
+      WHERE unreadable = 1 OR pii = 1 ORDER BY id DESC LIMIT ?`).all(MAX_PII + 1) as { id: number; unreadable: number; receipt_cut: number; sdlc: string | null }[];
+    let complete = rows.length <= MAX_PII;
+    const refs: PiiRef[] = [];
+    for (const row of rows.slice(0, MAX_PII)) {
+      if (row.unreadable || row.receipt_cut || !id(row.id)) { complete = false; continue; }
+      try {
+        const receipt = JSON.parse(row.sdlc ?? "{}");
+        refs.push({ id: row.id, ...(repoName(receipt?.repo) ? { repo: receipt.repo } : {}), ...(id(receipt?.pr) ? { pr: receipt.pr } : {}) });
+      } catch { complete = false; }
+    }
+    return source(refs, complete);
+  } catch { return missing([]); }
+  finally { db?.close(); }
+}
+/**
+ * Bounded read-only board snapshot. Select no task title/detail or history note into the result.
+ * With a window (#1147) only tasks that overlap [since, until] are read (updated >= since and created <= until), so a board over
+ * MAX_TASKS rows still reads completely when the window holds few of them. A board without those columns reads its newest MAX_TASKS rows.
+ * `linkedPrs` adds every task whose receipt links one of those PR numbers, window or not: a PR's lead time, review rounds and findings
+ * need all its tasks, so a sibling last updated before `since` must not be dropped. Their overflow shares the MAX_TASKS bound and
+ * makes the source incomplete, which turns every board-derived PR metric unknown.
+ */
+export function dogfoodTasks(file: string, window?: { since: number; until: number }, linkedPrs: number[] = []): Source<DogfoodTask[]> {
   let db: Database | undefined;
   try {
     db = new Database(file, { readonly: true });
     db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
     const columns = new Set((db.query("PRAGMA table_info(tasks)").all() as {name:string}[]).map(c=>c.name));
+    const windowed = window !== undefined && Number.isFinite(window.since) && Number.isFinite(window.until) && columns.has("created") && columns.has("updated");
+    const linked = windowed && columns.has("sdlc") ? [...new Set(linkedPrs.filter(n => Number.isSafeInteger(n) && n > 0))].slice(0, MAX_PRS) : [];
+    // json_extract raises on malformed JSON, so a row is only asked when its receipt is valid JSON.
+    const where = !windowed ? "" : linked.length
+      ? `WHERE (updated >= ? AND created <= ?) OR (CASE WHEN json_valid(sdlc) THEN json_extract(sdlc,'$.pr') END) IN (${linked.map(() => "?").join(",")})`
+      : "WHERE updated >= ? AND created <= ?";
     const metadata = columns.has("class") ? "CASE WHEN length(class) <= 48 THEN class END" : "NULL";
     const profile = columns.has("project_profile") ? "CASE WHEN length(project_profile) <= 65536 THEN project_profile END" : "NULL";
     const plan = columns.has("plan") ? "CASE WHEN length(plan) <= 65536 THEN plan END" : "NULL";
@@ -67,7 +114,7 @@ export function dogfoodTasks(file: string): Source<DogfoodTask[]> {
     const profileCut = columns.has("project_profile") ? "(project_profile IS NOT NULL AND length(project_profile) > 65536)" : "0";
     const rows = db.query(`SELECT (${planCut}) AS plan_cut, ${plan} AS plan, (${metadataCut}) AS metadata_cut, ${state} AS current_state, ${metadata} AS base_class, ${profileCut} AS profile_cut, ${profile} AS project_profile, id, (sdlc IS NOT NULL AND length(sdlc) > 65536) AS receipt_cut, CASE WHEN length(sdlc) <= 65536 THEN sdlc END AS sdlc,
       CASE WHEN length(signals) <= 65536 THEN signals END AS signals,
-      CASE WHEN length(history) <= 131072 THEN history END AS history FROM tasks ORDER BY id DESC LIMIT ?`).all(MAX_TASKS + 1) as { plan_cut: number; plan: string | null; metadata_cut: number; current_state: string | null; profile_cut: number; base_class: string | null; project_profile: string | null; id: number; receipt_cut: number; sdlc: string | null; signals: string | null; history: string | null }[];
+      CASE WHEN length(history) <= 131072 THEN history END AS history FROM tasks ${where} ORDER BY id DESC LIMIT ?`).all(...(windowed ? [window!.since, window!.until, ...linked] : []), MAX_TASKS + 1) as { plan_cut: number; plan: string | null; metadata_cut: number; current_state: string | null; profile_cut: number; base_class: string | null; project_profile: string | null; id: number; receipt_cut: number; sdlc: string | null; signals: string | null; history: string | null }[];
     let complete = rows.length <= MAX_TASKS, bytes = 0;
     const tasks: DogfoodTask[] = [];
     for (const row of rows.slice(0,MAX_TASKS)) {
@@ -144,15 +191,18 @@ export function dogfoodJournal(file: string, since: number, until: number): Sour
 }
 const connection = (value: any): any[] | undefined => value?.pageInfo?.hasNextPage === false && Array.isArray(value.nodes) && value.nodes.length <= 100 ? value.nodes : undefined;
 /** Reuse S10 cost readback; supplementary reads carry timestamps/ids only, never comment or issue bodies. */
-export async function dogfoodPrs(repo: string, tasks: Source<DogfoodTask[]>, since: number, until: number, run: SdlcGh = sdlcGh): Promise<Source<DogfoodPr[]>> {
-  if (!repoName(repo) || !tasks.available || !tasks.complete) return missing([]); // unknown privacy inventory forbids remote per-PR reads
+export async function dogfoodPrs(repo: string, tasks: Source<DogfoodTask[]>, since: number, until: number, run: SdlcGh = sdlcGh, pii?: Source<PiiRef[]>): Promise<Source<DogfoodPr[]>> {
+  // An unknown privacy inventory forbids remote per-PR reads. With the PII inventory (#1147) only it decides privacy, so an incomplete
+  // windowed task list no longer blocks them (its links stay unknown elsewhere); without it the task list is the inventory, as before.
+  const inventory: Source<PiiRef[]> = pii ?? { ...tasks, data: tasks.data.filter(t => t.pii).map(t => ({ id: t.id, ...(t.repo ? { repo: t.repo } : {}), ...(t.pr ? { pr: t.pr } : {}) })) };
+  if (!repoName(repo) || !inventory.available || !inventory.complete) return missing([]);
   const deadline = performance.now() + 20000;
   const gh: SdlcGh = (args, timeout, cwd, cap) => performance.now() < deadline
     ? run(args, Math.max(1,Math.min(timeout ?? 5000,deadline-performance.now())),cwd,Math.min(cap ?? 128*1024,128*1024)) : Promise.resolve({code:1,stdout:""});
   const parse = async (args: string[]) => { try { const r = await gh(args); return r.code === 0 ? JSON.parse(r.stdout) : undefined; } catch { return undefined; } };
   const list = await parse(["pr","list","--repo",repo,"--state","merged","--search",`merged:>=${new Date(since).toISOString()}`,"--limit","100","--json","number,mergedAt,createdAt"]);
   if (!Array.isArray(list)) return missing([]);
-  const hidden = new Set(tasks.data.filter(t => t.pii && (!t.repo || t.repo.toLowerCase() === repo.toLowerCase())).map(t => t.pr));
+  const hidden = new Set(inventory.data.filter(t => !t.repo || t.repo.toLowerCase() === repo.toLowerCase()).map(t => t.pr));
   const visible = list.filter(p => id(p?.number) && date(p.mergedAt) !== undefined && date(p.mergedAt)! <= until && !hidden.has(p.number));
   let complete = list.length < 100 && list.every(p => id(p?.number) && date(p.mergedAt) !== undefined) && visible.length <= MAX_PRS;
   // Read recent PRs first: their complete recorded head sets usually fit before
@@ -252,15 +302,18 @@ export function dogfoodProjectProfile(root: string): Source<ProfileName | null>
   return source(selected);
 }
 export async function readDogfood(root: string, stateDir: string, since: number, until = Date.now(), run: SdlcGh = sdlcGh) {
-  const tasks = dogfoodTasks(join(stateDir,"hub.db"));
+  const tasks = dogfoodTasks(join(stateDir,"hub.db"),{since,until}), pii = dogfoodPiiInventory(join(stateDir,"hub.db"));
   let repo = "";
   try { const r = await run(["repo","view","--json","nameWithOwner"],5000,root,8192); if (r.code === 0) repo = JSON.parse(r.stdout).nameWithOwner; } catch { /* unknown */ }
   const events = dogfoodEvents(dogfoodLines(join(stateDir,"events.jsonl")),since,until);
   const log = dogfoodLines(join(stateDir,"hub.log"));
+  const prs = await dogfoodPrs(repo,tasks,since,until,run,pii);
   log.data = log.data.filter(line => {
     const at=date(line.slice(0,24));
     if (at === undefined) { log.complete = false; return false; }
     return at >= since && at <= until;
   });
-  return dogfoodScorecard({since,until,tasks,events,log,projectProfile:dogfoodProjectProfile(root),journal:dogfoodJournal(join(stateDir,"hub.db"),since,until),prs:await dogfoodPrs(repo,tasks,since,until,run),features:dogfoodFeatures(join(root,"docs/dogfood.md"))});
+  const merged = prs.available ? prs.data.map(p => p.pr) : [];
+  const board = merged.length ? dogfoodTasks(join(stateDir,"hub.db"),{since,until},merged) : tasks;
+  return dogfoodScorecard({since,until,tasks:board,events,log,projectProfile:dogfoodProjectProfile(root),journal:dogfoodJournal(join(stateDir,"hub.db"),since,until),prs,features:dogfoodFeatures(join(root,"docs/dogfood.md"))});
 }

package/src/hub/envelope.ts

@@ -3,8 +3,8 @@ import { randomUUID } from "node:crypto";
 export type PeerId = string;
 export type PeerState = "idle" | "busy" | "paused" | "offline";
 export type Priority = "important" | "status" | "fyi";
-/** Every envelope kind, once: the journal, the restart reader, the deferred-notice check and the held-delivery hints all read this list. `invocation` and `invocation_result` are #445 C2. */
-export const KINDS = ["chat", "task", "review", "status", "budget", "presence", "invocation", "invocation_result"] as const;
+/** Every envelope kind, once: the journal, the restart reader, the deferred-notice check and the held-delivery hints all read this list. `invocation` and `invocation_result` are #445 C2, `answer` is #1053: a hub-built late answer (or expiry notice) to a question, `refs.question` names the set. */
+export const KINDS = ["chat", "task", "review", "status", "budget", "presence", "invocation", "invocation_result", "answer"] as const;
 export type Kind = (typeof KINDS)[number];
 
 export interface Envelope {
@@ -16,7 +16,7 @@ export interface Envelope {
   kind: Kind;
   priority: Priority;
   body: string; // agent conclusions only, never tool noise
-  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; reviewRevision?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; planReview?: number; planReviewFlow?: number; planAuthor?: string; backlog?: number[]; supervision?: boolean; supervisionKey?: string; completedFor?: number; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[]; invocation?: string; invocationRemote?: true };
+  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; reviewRevision?: string; reviewPackage?: string; reviewResponse?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; planReview?: number; planReviewFlow?: number; planAuthor?: string; backlog?: number[]; supervision?: boolean; supervisionKey?: string; completedFor?: number; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[]; invocation?: string; invocationRemote?: true; question?: string; handoff?: { project: string; task: number } };
   /** The body must not be shown outside its recipients: console tail and log print a stub instead (PII tasks). */
   private?: boolean;
   /** Sent by a distinct session (`<peer>~<origin>`, agent-hub#1036): a connection that named a peer id but is not that peer's current session. It grants nothing; it marks the sender for the log. */

package/src/hub/events.ts

@@ -54,8 +54,14 @@ export type HubEvent =
   | { type: "conduct"; peer: string; action: string; task?: number; target?: string }
   | { type: "agent_cli"; peer: string; command: string; refused: boolean; delegated?: true }
   | { type: "permission"; id: string; peer: string; event: "requested" | "answered" | "expired" | "cancelled"; latencyMs?: number; surface?: "console" | "dashboard" | "terminal"; option?: "allow_once" | "allow_always" | "reject_once" | "reject_always" }
+  /** #1053: one question a peer asked the person, and how it ended. Counts, ids and a closed reason only: never a prompt, an option, an answer or other text. */
+  | { type: "question"; set: string; peer: string; event: "asked" | "answered" | "pending" | "superseded" | "cancelled" | "expired" | "unavailable"; latencyMs?: number; surface?: "terminal" | "console" | "dashboard" | "acon"; person?: string; reason?: "superseded" | "stopped" | "turn_aborted" | "session_changed" | "expired" | "unattended"; questions?: number; private?: boolean }
   /** Completed native turns that received supervision, not feed enqueues or inferred costs. */
   | { type: "supervision_turn"; peer: string; turn: string; tokens?: number; ms?: number }
+  /** #1054: a run a person started settled (or a restart cut it short). Ids, a closed outcome and a duration only: never the prompt or the reply. */
+  /** #1054: a person (or the hub on a person's command) marked a result read. A receipt only: never read from a snapshot. */
+  | { type: "completion_seen"; id: string; surface: "terminal" | "console" | "dashboard" | "acon" }
+  | { type: "completion"; id: string; peer: string; outcome: "done" | "failed" | "limit" | "interrupted"; ms: number }
   | { type: "hook_stats"; peer: string; n: number; startupMs: number; hubMs: number; maxStartupMs: number }
   | { type: "cohort"; id: number; event: "formed" | "joined" | "lifted"; silent: boolean; tasks: number[]; owners: string[] }
   | ({ type: "tokens"; peer: string; n: number } & Partial<TaskAttribution>)

package/src/hub/handoff.ts

@@ -1,16 +1,19 @@
 // Cross-project task handoff (#604, agent-hub#1030). Pure: values in, values out, no clock, no file system, no socket. The daemon, the registry and the control client are
 // passed in as data or as small ports, so every refusal here is testable without a second daemon and the policy cannot drift from what the daemon enforces.
+import { createHash } from "node:crypto";
 import { CLASSES, type TaskClass } from "./board.ts";
 
 /**
  * What crosses projects, and nothing else: no memory, evidence, turn content or task history (#1030 design 5). The per-field limits alone allow about 13 KB, so `bodyBytes` is the real
  * ceiling on the whole request: a body that fills several fields is refused whole, and no partial task is built from it.
  */
-export const HANDOFF_LIMITS = Object.freeze({ title: 300, detail: 4000, paths: 16, path: 512, issue: 2_000_000_000, bodyBytes: 8 * 1024 });
-export const HANDOFF_FIELDS = Object.freeze(["project", "title", "class", "detail", "paths", "issue", "task"] as const);
+export const HANDOFF_LIMITS = Object.freeze({ title: 300, detail: 4000, paths: 16, path: 512, issue: 2_000_000_000, bodyBytes: 8 * 1024, duplicateOk: 300 });
+export const HANDOFF_FIELDS = Object.freeze(["project", "title", "class", "detail", "paths", "issue", "task", "duplicate_ok", "handoffKey"] as const);
+/** #731 (agent-hub#1203): the origin's idempotency key for one handoff request, a lowercase UUID v4 (what `randomUUID` writes). */
+export const HANDOFF_KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 
 export type HandoffRefusalCode =
-  | "invalid" | "too_large" | "unregistered" | "same_project" | "not_running" | "older_target" | "pii_turn" | "pii_task" | "no_authority";
+  | "invalid" | "too_large" | "unregistered" | "same_project" | "not_running" | "older_target" | "pii_turn" | "pii_task" | "no_authority" | "duplicate" | "outcome_unknown" | "mismatch";
 
 /** A refusal always names its reason, and for the person-fixable ones the action. The code is for tests and logs, the message for the caller. */
 export class HandoffRefusal extends Error {
@@ -18,7 +21,11 @@ export class HandoffRefusal extends Error {
 }
 
 /** `task` is the caller's OWN task this handoff comes from, so a `[pii]` one is refused and the target can name it in the follow-back. It never crosses as text. */
-export interface HandoffRequest { title: string; class: TaskClass; detail: string; paths: string[]; issue?: number; task?: number }
+export interface HandoffRequest { title: string; class: TaskClass; detail: string; paths: string[]; issue?: number; task?: number;
+  /** #1175: the sender's reason for filing a second task on a spec issue that already has an open one on the target's board. Absent means the target refuses a duplicate. */
+  duplicate_ok?: string;
+  /** #731: the key of this request. Absent means the origin mints one when the target understands keys; it crosses inside the request body only to a target that advertises `task_handoff_key`. */
+  handoffKey?: string }
 
 const hasControl = (text: string): boolean => /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(text);
 
@@ -71,11 +78,32 @@ export function parseHandoff(input: unknown): HandoffRequest & { project: string
     task = typeof rawTask === "string" && /^[1-9]\d{0,9}$/.test(rawTask) ? Number(rawTask) : rawTask as number;
     if (typeof task !== "number" || !Number.isSafeInteger(task) || task < 1 || task > HANDOFF_LIMITS.issue) throw new HandoffRefusal("invalid", "handoff task must be a positive task id of this project");
   }
-  const request = { project, title, class: cls as TaskClass, detail, paths, ...(issue === undefined ? {} : { issue }), ...(task === undefined ? {} : { task }) };
+  const duplicateOk = text(field("duplicate_ok"), "duplicate_ok", HANDOFF_LIMITS.duplicateOk, false).replace(/\s+/g, " ").trim();
+  if (field("duplicate_ok") !== undefined && field("duplicate_ok") !== null && field("duplicate_ok") !== "" && !duplicateOk) throw new HandoffRefusal("invalid", "handoff duplicate_ok needs a reason");
+  const rawKey = field("handoffKey");
+  if (rawKey !== undefined && rawKey !== null && rawKey !== "" && (typeof rawKey !== "string" || !HANDOFF_KEY.test(rawKey))) throw new HandoffRefusal("invalid", "handoff handoffKey must be a lowercase UUID v4");
+  const handoffKey = typeof rawKey === "string" && rawKey ? rawKey : undefined;
+  const request = { project, title, class: cls as TaskClass, detail, paths, ...(issue === undefined ? {} : { issue }), ...(task === undefined ? {} : { task }), ...(duplicateOk ? { duplicate_ok: duplicateOk } : {}), ...(handoffKey === undefined ? {} : { handoffKey }) };
   if (Buffer.byteLength(JSON.stringify(request), "utf8") > HANDOFF_LIMITS.bodyBytes) throw new HandoffRefusal("too_large", `handoff is over ${HANDOFF_LIMITS.bodyBytes} bytes`);
   return request;
 }
 
+/**
+ * #731: what a key stands for. The target keeps this with the key, so a replay of the same key answers with the existing task, and the same key with a different request is refused, never
+ * silently answered with a task the caller did not ask for. The key itself and the target are not part of it; the origin's own task id is.
+ */
+export function handoffRequestDigest(request: Pick<HandoffRequest, "title" | "class" | "detail" | "paths" | "issue" | "duplicate_ok">, originTask?: number): string {
+  return createHash("sha256").update(JSON.stringify([request.title, request.class, request.detail, request.paths, request.issue ?? null, request.duplicate_ok ?? null, originTask ?? null])).digest("hex");
+}
+
+/**
+ * #731 (H1): whether a control reply says the request may have reached the target without an answer coming back: the client's own timeout, or a connection that closed while the request was out.
+ * A refusal the target wrote, and a request that was never sent, are definite and are not this. Reads the client's fixed wording (`control-client.ts`), never the target's text.
+ */
+export function handoffOutcomeUnknown(reply: { ok?: unknown; error?: unknown }): boolean {
+  return reply.ok !== true && typeof reply.error === "string" && /^(no answer from the hub within \d+ s|hub connection closed)/.test(reply.error);
+}
+
 export interface RegisteredProject { id: string; root: string; stateDir: string }
 export interface TargetDescriptor { features?: readonly string[]; instanceId?: string; projectId?: string; cwd?: string }
 
@@ -93,6 +121,56 @@ export function resolveTarget(name: string, projects: readonly RegisteredProject
   return match;
 }
 
+/**
+ * #734 (agent-hub#1203 H8): a failed connection to a target hub, named by its cause. The control client throws an `Error` with a `code`: 4426 (the wire versions share no
+ * protocol), 4404 (the hub or instance answering is not the one asked for), or a connect code (`AHUB_CONNECT_TIMEOUT`, `AHUB_CONNECT_UNREACHABLE`) or a socket close code. Each cause has
+ * its own next step, and none is "run `ahub up`" unless the hub really is not running: a version skew is fixed by upgrading, an instance mismatch by asking the right hub.
+ * Pure: the error's `code` and nothing from its message is read, so a target's text never decides a branch.
+ */
+export function handoffConnectFailure(error: unknown, target: { id: string; root: string }): { code: HandoffRefusalCode; reach: "unreachable"; cause: string; message: string } {
+  const code = typeof (error as { code?: unknown })?.code === "number" || typeof (error as { code?: unknown })?.code === "string" ? (error as { code: number | string }).code : undefined;
+  if (code === 4426) return { code: "older_target", reach: "unreachable", cause: "wire version differs",
+    message: `the hub of ${target.id} speaks another wire version than this one: upgrade whichever is older (\`ahub upgrade\` in ${target.root}, and the global CLI with \`bun add -g @staix/agent-hub\`), then hand the task off again` };
+  if (code === 4404) return { code: "mismatch", reach: "unreachable", cause: "another hub or instance answered",
+    message: `the hub answering for ${target.root} is not the instance this project's registry names (it was restarted, or another project took its port): run \`ahub projects\` to see what is registered, and \`ahub up\` in ${target.root} if it is not running` };
+  if (code === "AHUB_CONNECT_TIMEOUT") return { code: "not_running", reach: "unreachable", cause: "no answer in time",
+    message: `the hub of ${target.id} did not answer in time: it may be busy or stuck; check \`ahub status\` in ${target.root}, then hand the task off again (handoffs are not queued)` };
+  return { code: "not_running", reach: "unreachable", cause: "not running",
+    message: `the hub of ${target.id} did not answer; run \`ahub up\` in ${target.root}, then hand the task off again (handoffs are not queued)` };
+}
+
+/** One word for where a handoff row's target stands, shown by `ahub task handoff --list`. `moved` is a project id the registry no longer holds: its root changed or it was removed, and the id is a hash of the root. */
+export type HandoffReach = { reach: "reachable" } | { reach: "unreachable"; cause: string } | { reach: "moved"; cause: string };
+export function handoffReach(input: { registered: boolean; descriptor?: TargetDescriptor | undefined; lastFailure?: string | undefined }): HandoffReach {
+  if (!input.registered) return { reach: "moved", cause: "project not registered (moved?): run `ahub projects`, and `ahub up` in its new root" };
+  if (!input.descriptor) return { reach: "unreachable", cause: input.lastFailure ?? "not running: run `ahub up` in its root" };
+  if (!input.descriptor.features?.includes("task_handoff")) return { reach: "unreachable", cause: "too old for handoffs: upgrade it with `ahub upgrade`" };
+  return input.lastFailure ? { reach: "unreachable", cause: input.lastFailure } : { reach: "reachable" };
+}
+
+/** A person-readable age ("45s", "12m", "3h", "5d") for a row last updated `ms` ago. A negative or non-finite age reads "-": a clock that moved is not a duration. */
+export function handoffAge(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return "-";
+  const s = Math.floor(ms / 1000);
+  if (s < 90) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 90) return `${m}m`;
+  const h = Math.floor(m / 60);
+  return h < 48 ? `${h}h` : `${Math.floor(h / 24)}d`;
+}
+
+/**
+ * #734 (H7): at most one log line per target and cause in each window, so a target that stays down for a day writes a line per window and not a line per notify or catch-up. The state is a
+ * plain map the caller owns (one per daemon), bounded by `max` keys: past it the oldest key is forgotten, which can only let one extra line through, never suppress a new cause.
+ */
+export function handoffLogGate(seen: Map<string, number>, key: string, now: number, windowMs: number, max = 256): boolean {
+  const last = seen.get(key);
+  if (last !== undefined && now - last < windowMs && now >= last) return false;
+  seen.delete(key); seen.set(key, now);
+  while (seen.size > max) seen.delete(seen.keys().next().value as string);
+  return true;
+}
+
 /** What the target's own status descriptor says. A daemon that is not running, or does not know the handoff, is refused with the person's action. */
 export function checkTarget(project: RegisteredProject, descriptor: TargetDescriptor | undefined): void {
   if (!descriptor) throw new HandoffRefusal("not_running", `the hub of ${project.id} is not running; run \`ahub up\` in ${project.root}, then hand the task off again (handoffs are not queued)`);
@@ -101,7 +179,7 @@ export function checkTarget(project: RegisteredProject, descriptor: TargetDescri
 }
 
 /** The states a target reports back, in the order a task can reach them. `declined` is the owner passing; the task then returns to the target's routing, so it is information, not an end. */
-export const HANDOFF_EVENTS = Object.freeze(["accepted", "in_review", "approved", "declined", "cancelled"] as const);
+export const HANDOFF_EVENTS = Object.freeze(["accepted", "in_review", "approved", "declined", "cancelled", "changes_requested", "reopened"] as const);
 export type HandoffEvent = (typeof HANDOFF_EVENTS)[number];
 
 /** Map a target's task history entry to the event the origin is told about, or undefined for every other entry. Reads only the event name and the task state, never a note. */
@@ -112,11 +190,33 @@ export function handoffEventFor(entryEvent: string, state: string): HandoffEvent
   if (entryEvent === "cancelled" && state === "cancelled") return "cancelled";
   if (entryEvent === "done" && state === "in_review") return "in_review";
   if (entryEvent === "approved" && state === "approved") return "approved";
+  // #733 (agent-hub#1203 H10): a reviewer's changes_requested, and the hub's return of that task to its owner, are states the origin used to hear nothing about. A withdrawn approval is the same
+  // verdict on an approved task: the row it reopens is picked up through the sequence.
+  if (entryEvent === "changes_requested" && state === "changes_requested") return "changes_requested";
+  if (entryEvent === "reopened" && state === "in_progress") return "reopened";
   // A class with no reviewer: the done itself approves (`in_progress -> approved`), so the origin hears "approved" for that entry, not "in review".
   if (entryEvent === "done" && state === "approved") return "approved";
   return undefined;
 }
 
+/**
+ * #733: whether the origin still asks a target about a handoff row. An open row always; an approved one for a grace period, because a reviewer can withdraw an approval and the origin only learns
+ * of it through the sequence; a cancelled one never. ponytail: the grace period is a fixed 7 days; a per-row "reopenable" fact from the target would end it, at the cost of one more field per state.
+ */
+export const HANDOFF_APPROVED_GRACE_MS = 7 * 24 * 3600_000;
+export function handoffCatchUpRow(row: { state: string; updatedAt: number }, now: number): boolean {
+  if (row.state === "cancelled") return false;
+  return row.state !== "approved" || now - row.updatedAt <= HANDOFF_APPROVED_GRACE_MS;
+}
+/** One request carries at most this many task ids: the target refuses a longer list (`handoffStatesFor`). */
+export const HANDOFF_STATES_CHUNK = 200;
+/** Split a project's task ids into requests of at most `HANDOFF_STATES_CHUNK`, in order, none dropped. */
+export function handoffChunks(ids: readonly number[]): number[][] {
+  const out: number[][] = [];
+  for (let i = 0; i < ids.length; i += HANDOFF_STATES_CHUNK) out.push(ids.slice(i, i + HANDOFF_STATES_CHUNK));
+  return out;
+}
+
 const SHA = /^[0-9a-f]{40}$/;
 /** One line, no free text from the target beyond a PR number and a head: `agent-hub task 123 approved: PR #7 at <sha>`. */
 export function followBackLine(remoteTask: number, event: HandoffEvent, evidence: { pr?: unknown; head?: unknown } = {}): string {
@@ -124,3 +224,42 @@ export function followBackLine(remoteTask: number, event: HandoffEvent, evidence
   const head = typeof evidence.head === "string" && SHA.test(evidence.head) ? ` at ${evidence.head}` : "";
   return `agent-hub task ${remoteTask} ${event.replace("_", " ")}${pr || head ? `:${pr}${head}` : ""}`;
 }
+
+export interface DuplicateRow { id: number; state: string; title: string; detail?: string; refs?: { repo?: string }; external?: { repo: string; issue: number } | undefined; sdlc?: { issue?: number; repo?: string } | undefined }
+
+/**
+ * #1175: the ids of tasks already open on THIS board for the spec issue a handoff names. Pure: the caller passes the board's rows (a `[pii]` row is the caller's to leave out, so no
+ * private task id is ever named to another project) and the project's own repository slug. A task counts when it is not closed and one of these names the issue: its lifecycle
+ * receipt, a bare `#N` or an `owner/repo#N` of this repository in its title, or the `spec issue: #N in this repository` line a handoff keeps in its detail. A reference qualified
+ * with another repository never counts, and a number that appears in a title as another kind of reference (a PR) is the one false positive: the sender's `duplicate_ok` answers it.
+ */
+export function duplicateIssueTasks(tasks: readonly DuplicateRow[], issue: number, repository?: string): number[] {
+  const slug = (value: string | undefined): string | undefined => value !== undefined && /^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9_.-]{1,100}$/.test(value) ? value.toLowerCase() : undefined;
+  // A project with no GitHub remote has a path, not a slug, for its repository: nothing can then be compared, so no row is foreign and no qualified reference matches.
+  const own = slug(repository);
+  const names = (text: string, bare: boolean): boolean => {
+    for (const match of text.matchAll(/(?<![A-Za-z0-9_./-])(?:([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#([1-9][0-9]*)\b|#([1-9][0-9]*)\b)/g)) {
+      const qualified = match[1];
+      if (Number(match[2] ?? match[3]) !== issue) continue;
+      if (qualified ? qualified.toLowerCase() === own : bare) return true;
+    }
+    return false;
+  };
+  return tasks.filter(task => {
+    if (task.state === "approved" || task.state === "cancelled") return false;
+    // The repository each identity belongs to: `sdlc.repo`, `external.repo` (an imported issue) and a slug `refs.repo` (a checkout path says nothing). One naming another repository
+    // than this project's keeps its `#N` out: an issue number is only an identity together with its repository. With no own slug nothing can be compared, so the number counts and `duplicate_ok` answers.
+    const foreign = (repo: string | undefined): boolean => own !== undefined && slug(repo) !== undefined && slug(repo) !== own;
+    if (task.external?.issue === issue && !foreign(task.external.repo)) return true;
+    if (task.sdlc?.issue !== undefined) return task.sdlc.issue === issue && !foreign(task.sdlc.repo) && !foreign(task.refs?.repo);
+    if (foreign(task.external?.repo) || foreign(task.refs?.repo)) return false;
+    const line = /(^|\n)spec issue: #([1-9][0-9]*) in this repository/.exec(task.detail ?? "");
+    return names(task.title, true) || line !== null && Number(line[2]) === issue;
+  }).map(task => task.id).sort((a, b) => a - b);
+}
+
+/** One refusal sentence that names the open tasks and both ways forward. The ids are this board's own; no title or text from a task is repeated. */
+export function duplicateRefusalText(issue: number, ids: readonly number[]): string {
+  const named = ids.slice(0, 6).map(id => `#${id}`).join(", ") + (ids.length > 6 ? ` and ${ids.length - 6} more` : "");
+  return `spec issue #${issue} already has open ${ids.length === 1 ? "task" : "tasks"} here: ${named}. Use ${ids.length === 1 ? "it" : "them"} (ask the conductor there), or hand off again with duplicate_ok: <reason> (--duplicate-ok <reason> in the CLI) if this is genuinely separate work`;
+}