@staix/agent-hub 0.28.0 → 0.30.0

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/hub-tools.ts

@@ -69,7 +69,7 @@ const plan = {
 } as const;
 
 // Accept may target a task from an older project profile; Tasks normalizes by the stored task profile.
-const acceptPlan = { ...plan, properties: { ...plan.properties, sections: list("document heading anchors, such as report.md#methods"), sources: list("citation ids, DOI or source URL ids"), claims: list("short claim ids to verify") } } as const;
+const acceptPlan = { ...plan, properties: { ...plan.properties, sections: list("document heading anchors, such as report.md#methods"), sources: list("registered src:<16 hex> source ids; list available ids with ahub source list"), claims: list("short claim ids to verify") } } as const;
 
 export interface HubTool {
   name: string;
@@ -122,7 +122,7 @@ export const TASK_TOOLS: HubTool[] = [
   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. 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_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs; no duplicate hub_send chat is needed. When re-filing work after review, set refs.commit to the new full SHA; summary text does not change the review head. 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, 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"]),
@@ -154,10 +154,16 @@ export const PLANNER_REVIEW_TOOLS: HubTool[] = [
   tool("hub_plan_review", "Record a planner review against the task planning revision and host-read issue edit time. Configured planner or person only; never accepts caller issue timestamps.", { id, revision: { type: "integer", minimum: 0 }, reason: { ...str, maxLength: 1000 }, ...costPlanProperties }, ["id", "revision", "reason"]),
   tool("hub_sdlc_costs", "Read bounded review and CI cost metrics for linked merged PRs. Planner/person only; metadata only, no board writes.", { repo: str }),
   tool("hub_sdlc_metrics", "Read SDLC metrics from board history: time from acceptance to plan, first review and merge, first-pass approval and rework rounds, first-pass CI and same-head reruns, stale-head re-reviews, stalls, and the control band tiers when sdlc.toml sets [bands]. Planner/person only; read-only, no model and no GitHub issue.", { since: str }),
-  tool("hub_backlog_return_untouched", "Return accepted but untouched work to the backlog with its history and planning retained. Refuses execution/branch/commit evidence; planner or person only.", { id, revision: { type: "integer", minimum: 0 }, reason: { ...str, maxLength: 1000 } }, ["id", "revision", "reason"]),
+  tool("hub_backlog_return_untouched", "Return accepted but untouched work to the backlog with its history and planning retained. Optional fields.reserved changes the reservation atomically before capacity is released; null clears it. Refuses execution/branch/commit evidence; planner or person only, and a person's reservation requires the person.", { id, revision: { type: "integer", minimum: 0 }, reason: { ...str, maxLength: 1000 }, fields: { type: "object", properties: { reserved: { type: ["string", "null"], minLength: 1, maxLength: 32 } }, additionalProperties: false } }, ["id", "revision", "reason"]),
 ];
 TASK_TOOLS.push(...PLANNER_REVIEW_TOOLS);
-export const TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));
+/** Only definitions declaring a hub-owned title slot publish this tool. It is absent from global schema lists; native approval names must exclude it too. */
+export const SESSION_TITLE_TOOL: HubTool = tool("hub_set_title", "Name your own session once the task is clear. Only an unnamed session accepts the first agent name; the person may replace it. Private contexts refuse the write. No task, branch or instance is renamed.", { title: { type: "string", description: "1-80 characters after doingText normalization (one line, controls removed, surrounding whitespace trimmed)" } }, ["title"]);
+export function sessionTitleTools(tools: HubTool[], allowed = false): HubTool[] {
+  const filtered = tools.filter(tool => tool.name !== SESSION_TITLE_TOOL.name);
+  return allowed ? [...filtered, SESSION_TITLE_TOOL] : filtered;
+}
+export const TASK_TOOL_NAMES = new Set([...TASK_TOOLS.map((t) => t.name), SESSION_TITLE_TOOL.name]);
 
 /** Separately published: serving a schema grants no authority, only the daemon's explicit role does. */
 export const CONDUCTOR_TOOLS: HubTool[] = [
@@ -246,7 +252,7 @@ export function profileTaskTools(profile: ProfileSelection = "dev", stages?: rea
       properties.receipt = { ...receipt, properties: fields };
     }
     if (customProfile && tool.name === "hub_task_propose") properties.class = { type: "string", enum: [...new Set([...Object.keys(data.classes), ...PROFILE_CLASS_NAMES.filter(v => projectProfile("dev").classes[v])])] };
-    if (customProfile && properties.plan && tool.name !== "hub_task_accept" && tool.name !== "hub_experiment_record") properties.plan = { ...plan, properties: { ...Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) } };
+    if (customProfile && properties.plan && tool.name !== "hub_task_accept" && tool.name !== "hub_experiment_record") properties.plan = { ...plan, properties: { ...Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "registered src:<16 hex> source ids; list available ids with ahub source list" : "short claim ids to verify")])) } };
     if (customProfile && tool.name === "hub_task_done" && data.name !== "dev") {
       const summaryProp = properties.summary as { type: string; description: string };
       properties.summary = {
@@ -258,7 +264,7 @@ export function profileTaskTools(profile: ProfileSelection = "dev", stages?: rea
     }
     if (customProfile && tool.name === "hub_backlog_split") {
       const parts = properties.parts as { items: { properties: Record<string, unknown> } };
-      const selectedPlan = { ...plan, properties: { ...Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) } };
+      const selectedPlan = { ...plan, properties: { ...Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "registered src:<16 hex> source ids; list available ids with ahub source list" : "short claim ids to verify")])) } };
       properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: selectedPlan } } };
     }
     if (criteria && properties.plan && tool.name !== "hub_experiment_record") {

package/src/hub/manager.ts

@@ -128,19 +128,27 @@ export function projectConsole(options: { registry: Registry; lifecycle: Lifecyc
         await bounded(lifecycle.stopProject(project, input.instanceId), 20_000);
         return { ok: true };
       }
+      // #1057: the worktree shelf's person actions. The refresh is the one that reads GitHub, so it gets the delivery reads' deadline in its own branch below.
+      const worktreeAction = ["worktree_override_set", "worktree_override_clear", "worktrees_refresh_prs"].includes(String(input.action));
       // The settings actions (#269) reach the project hub as an ordinary session's: this dashboard opens no settings session.
-      if (!["snapshot", "send", "pause", "resume", "permit", "propose", "assign", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "setting_reload", "config_edit_preview", "config_edit_apply", "start_peer", "sdlc_queue", "sdlc_release"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
+      if (!["snapshot", "send", "pause", "resume", "permit", "propose", "intake", "assign", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "setting_reload", "config_edit_preview", "config_edit_apply", "start_peer", "sdlc_queue", "sdlc_release"].includes(String(input.action)) && !worktreeAction) return { ok: false, error: "invalid dashboard action" };
       client = await ControlClient.connect(project.stateDir, { role: "console", projectId: project.id, projectRoot: project.root, instanceId: input.instanceId });
       const deliveryRead = input.action === "sdlc_queue" || input.action === "sdlc_release";
       let nominalMs = 10_000;
       if (input.action === "start_peer") nominalMs = MAX_COMMAND_MS + 5_000;
       else if (input.action === "backlog_split") nominalMs = BACKLOG_SPLIT_SCREEN_TIMEOUT_MS + HUB_DB_BUSY_TIMEOUT_MS + 5_000;
+      else if (input.action === "intake") nominalMs = 90_000; // the CLI intake cap, including the hub model's bounded split
       else if (deliveryRead) nominalMs = 30_000;
+      else if (input.action === "worktrees_refresh_prs") nominalMs = 40_000; // up to 25 s of bounded gh reads plus two git passes
       const timeoutMs = options.forwardTimeoutMs?.(String(input.action), nominalMs) ?? nominalMs;
       const result = await client.request(input.action === "snapshot"
         ? { t: "ui_snapshot", after: input.after ?? 0, ...(input.memory !== undefined ? { memory: input.memory } : {}), ...(dashboardView(input.view) ? { view: input.view } : {}) }
         : { t: "ui_action", action: input, instanceId: input.instanceId }, timeoutMs);
       // ControlClient resolves its deadline as this exact sentinel; a hub refusal stays a known failure.
+      if (input.action === "intake" && result.ok === false && result.error === `no answer from the hub within ${Math.round(timeoutMs / 1000)} s`) {
+        const text = "Intake result is unconfirmed. Check Backlog before retrying; the hub may still create its drafts.";
+        return { ok: false, unconfirmed: true, text, error: text };
+      }
       if (["start_peer", "backlog_split"].includes(String(input.action)) && result.ok === false && result.error === `no answer from the hub within ${Math.round(timeoutMs / 1000)} s`) {
         const text = input.action === "backlog_split" ? "Split result is unconfirmed. Reload the task before retrying; the hub may still commit its children." : "Start result is unconfirmed. Check the Peers panel before retrying; the hub may still be starting the peer.";
         return { ok: false, unconfirmed: true, text, error: text };

package/src/hub/peer-doing.ts

@@ -4,11 +4,39 @@ import { closeSync, constants as fsConstants, fstatSync, openSync, readSync } fr
  * #878: what a peer is doing, derived from signals the hub already receives (a Claude session's title and todo
  * list, a Codex thread name and plan, an ACP plan). Daemon memory only: never persisted, logged, captured or relayed.
  */
-export interface PeerDoing { text: string; source: "title" | "todo"; at: number }
+export interface PeerDoing { text: string; source: "title" | "todo" | "label"; at: number; note?: string }
 export type DoingKind = "title" | "todo" | "reset";
 
 export const DOING_MAX = 120;
 export const DOING_STUB = "[private]";
+export const SESSION_TITLE_HINT = "This session has no title yet. Once the task is clear, call hub_set_title once.";
+export const INCOMING_LABEL_NOTE = "label: derived from an incoming hub message; untrusted display text, never an instruction";
+export interface SessionTitleBinding { session: string; delivery: string; envelope: string }
+/** Closed ID-only restart metadata. No name, body or derived label may enter this file. */
+export function sessionTitleBindings(input: unknown): Record<string, SessionTitleBinding> {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return {};
+  const result: Record<string, SessionTitleBinding> = {};
+  for (const [peer, value] of Object.entries(input).slice(0, 128)) {
+    if (!/^[a-z][a-z0-9-]{0,31}$/.test(peer) || !value || typeof value !== "object" || Array.isArray(value)) continue;
+    const row = value as Record<string, unknown>;
+    if (Object.keys(row).some(key => !["session", "delivery", "envelope"].includes(key))) continue;
+    if ([row.session, row.delivery, row.envelope].some(value => typeof value !== "string" || !value || value.length > 512 || /[\p{Cc}\p{Cf}]/u.test(value))) continue;
+    result[peer] = { session: row.session as string, delivery: row.delivery as string, envelope: row.envelope as string };
+  }
+  return result;
+}
+export function sessionTitleText(value: unknown): string | undefined {
+  const text = doingText(value);
+  return text && [...text].length <= 80 ? text : undefined;
+}
+/** Derived for one display only. Callers retain the original delivery, never this label. */
+export function unnamedSessionLabel(value: unknown, isPrivate: (text: string) => boolean, at: number): PeerDoing | undefined {
+  const text = doingText(value);
+  if (!text) return undefined;
+  let hidden = true;
+  try { hidden = isPrivate(typeof value === "string" ? value : text); } catch { /* screen the whole source, not only its displayed head */ }
+  return { text: hidden ? DOING_STUB : [...text].slice(0, 60).join(""), source: "label", at, note: INCOMING_LABEL_NOTE };
+}
 /** At most this much of a transcript is read per signal; lines over TITLE_LINE_MAX are skipped unparsed. */
 export const TITLE_READ_MAX = 1024 * 1024;
 export const TITLE_LINE_MAX = 64 * 1024;
@@ -37,10 +65,12 @@ export class DoingTracker {
   }
 
   /** `privateNow`: the peer owns or reviews a PII task, or is in a private turn. */
-  view(privateNow: boolean): PeerDoing | undefined {
+  view(privateNow: boolean, isPrivate?: (text: string) => boolean): PeerDoing | undefined {
     const value = this.item ?? this.title;
     if (!value) return undefined;
-    return { text: value.private || privateNow ? DOING_STUB : value.text, source: value.source, at: value.at };
+    let hidden = value.private || privateNow;
+    if (!hidden && isPrivate) try { hidden = isPrivate(value.text); } catch { hidden = true; }
+    return { text: hidden ? DOING_STUB : value.text, source: value.source, at: value.at };
   }
 }
 

package/src/hub/peers.ts

@@ -2,6 +2,7 @@ import type { Envelope, EnvelopeOpts, PeerId, PeerState } from "./envelope.ts";
 import type { PermissionMode } from "./permission-mode.ts";
 import type { StartForm } from "../adapters/registry-types.ts";
 import type { DoingKind } from "./peer-doing.ts";
+export type SessionTitleResult = { ok: true } | { ok: false; reason: "already_named" | "invalid"; error?: string; mayHaveApplied?: true };
 import type { CapabilityManifest } from "./capabilities.ts";
 
 export interface DeliveryReceipt {
@@ -61,6 +62,12 @@ export interface PeerAdapter {
   captureResume?(): Promise<Record<string, unknown>>;
   /** Native session binding; absence or undefined is unbound, never inferred from a different reader. */
   readonly nativeSession?: string;
+  /** Verified native name, or the local session's own field. Empty means verified unnamed; undefined is unknown. */
+  readonly sessionTitle?: string;
+  /** Opaque title-session identity, separate from context/provenance's nativeSession authority. */
+  readonly titleSession?: string;
+  /** Native adapters check the live name at the actual write. The host guard is checked immediately before effects. */
+  setSessionTitle?(title: string, onlyIfUnnamed: boolean, current?: () => boolean): Promise<SessionTitleResult>;
   /** 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. */

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; /** #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; }
+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 have the task worktree made for it: it makes its own, or (a hub sandbox, #270) the hub makes it (#1115) where it can. 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";
@@ -343,6 +343,12 @@ export function ownerRoleOfClass(cls: TaskClass): "planner" | "implementer" | "r
   return cls === "review" ? "reviewer" : cls === "plan" ? "planner" : "implementer";
 }
 
+/**
+ * #1129: the classes whose owner changes the repository, so a hub-sandboxed owner needs the hub's task worktree and commit (#1115) whether or not the task declares
+ * `needs_worktree`. `test`, `summarize`, `triage`, `review` and `plan` read and report: they get none. One definition, so routing and `Tasks` cannot disagree.
+ */
+export const writesRepository = (cls: TaskClass): boolean => cls === "implement" || cls === "bulk_edit";
+
 /** Why a planner was chosen: the person named it, rotation reached it, the task's recorded planner is kept, or there is none (PII, no holder). */
 export type PlannerReason = "rotation" | "named" | "kept" | "none";
 
@@ -493,7 +499,8 @@ export function assign(
       // #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"}`);
+      // #1129: write-class work needs one whether or not it declares it, because a hub-sandboxed owner cannot commit and the hub commits in its worktree. Unknown capability is not a refusal.
+      if ((task.signals.includes("needs_worktree") || writesRepository(task.class)) && 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/runtime-capture-prune.ts

@@ -246,7 +246,10 @@ function knownLayout(root: string, directories: readonly string[], files: readon
   }
 }
 function captureLayout(root: string): void {
-  knownLayout(root, ["src", "plugins", "templates", ".claude-plugin"], ["package.json", "README.md", "LICENSE", "CHANGELOG.md"], ["node_modules"]);
+  knownLayout(root, ["src", "plugins", "templates", ".claude-plugin"], ["package.json", "README.md", "LICENSE", "CHANGELOG.md"], ["node_modules", "scripts"]);
+  // #1120: captures made before the release checker was carried have no scripts directory; when present it holds exactly the checker.
+  // The name is repeated here on purpose: a pruner copied into a capture runs beside that capture's own verifier and imports nothing but verifyPackage from it. test/runtime-capture-checker.test.ts pins this name to RELEASE_CHECKER.
+  if (optionalInfo(join(root, "scripts"))) knownLayout(join(root, "scripts"), [], ["check-docs.mjs"]);
   const modules = join(root, "node_modules");
   if (optionalInfo(modules)) {
     knownLayout(modules, ["@staix"], []); const scope = join(modules, "@staix"); knownLayout(scope, ["agent-mem"], []);

package/src/hub/sdlc-release-authorization.ts

@@ -2,7 +2,7 @@ import { releaseTrackedClean } from "./release-worktree.ts";
 import { createHash, randomUUID } from "node:crypto";
 import { USER, type PeerId } from "./envelope.ts";
 import { hubGitEnv, hubGitSync } from "./git.ts";
-import { readDocEvidence, type DocEvidence, type ReleaseGit, type ReleaseReadiness } from "./sdlc-release.ts";
+import { readDocEvidenceDetailed, type DocEvidence, type ReleaseGit, type ReleaseReadiness } from "./sdlc-release.ts";
 import type { SdlcGh } from "./sdlc.ts";
 import type { ReleaseGuardRequest, ReleasePushUpdate } from "../cli/sdlc-release-guard.ts";
 
@@ -17,6 +17,8 @@ export interface ReleaseAuthorization { schemaVersion: 1; id: string; by: PeerId
 export interface ReleaseAuthorizationPorts {
   git?: ReleaseGit;
   docs?: (root: string) => Promise<DocEvidence | undefined>;
+  /** Test seam: the checker program the default reader spawns (#1120). Never set from configuration. */
+  checker?: string;
   gh?: SdlcGh;
   now?: () => number;
   current?: () => boolean;
@@ -46,6 +48,13 @@ export class ReleaseAuthorizations {
   private latest?: Entry;
   constructor(private readonly root: string, private readonly ports: ReleaseAuthorizationPorts) {}
   private current(): void { if (this.ports.current?.() === false) throw new ReleaseAuthorizationError("release authorization unavailable during lifecycle transition"); }
+  /** #1120: a checker that is missing or failed is its own refusal; only evidence that is read and not fresh is "stale documentation". An injected reader keeps its undefined meaning (no evidence). */
+  private async docs(commit: string, version: string): Promise<ReleaseDocsVerdict | undefined> {
+    if (this.ports.docs) return docsVerdict(await this.ports.docs(this.root), commit, version);
+    const read = await readDocEvidenceDetailed(this.root, undefined, this.ports.checker);
+    if ("unavailable" in read) throw new ReleaseAuthorizationError(`release authorization needs the documentation checker: ${read.unavailable}`);
+    return docsVerdict(read.evidence, commit, version);
+  }
   private actor(by: PeerId): void {
     if (by !== USER && (typeof by !== "string" || !by.trim() || this.ports.conductor?.() !== by)) throw new ReleaseAuthorizationError("only the person or the configured conductor may authorize a release");
   }
@@ -95,8 +104,8 @@ export class ReleaseAuthorizations {
     this.current();
     const git = this.git(), commit = this.commit(git, "HEAD"), origin = this.origin(git);
     if (commit !== expectedCommit || this.version(git, commit) !== version) throw new ReleaseAuthorizationError("candidate commit or version differs from the person's request");
-    const docs = docsVerdict(await (this.ports.docs ?? readDocEvidence)(this.root), commit, version);
-    if (!docs) throw new ReleaseAuthorizationError("release authorization requires fresh committed documentation evidence");
+    const docs = await this.docs(commit, version);
+    if (!docs) throw new ReleaseAuthorizationError("release authorization requires fresh committed documentation evidence: run `node scripts/check-docs.mjs --committed` in the candidate checkout, restamp the stale documents in a committed change, then authorize again");
     this.current(); this.actor(by);
     if (this.commit(git, "HEAD") !== commit || this.version(git, commit) !== version || this.origin(git).hash !== origin.hash) throw new ReleaseAuthorizationError("release candidate changed during authorization");
     this.current(); this.actor(by);
@@ -127,7 +136,7 @@ export class ReleaseAuthorizations {
         if (!releaseTrackedClean(this.root, git)) throw new ReleaseAuthorizationError("npm publish requires a clean tracked worktree");
         const commit = this.commit(git, "HEAD"), version = this.version(git, commit);
         const receipt = this.matched(git, version, commit);
-        const docs = docsVerdict(await (this.ports.docs ?? readDocEvidence)(this.root), commit, version);
+        const docs = await this.docs(commit, version);
         this.current();
         if (!docs || docs.digest !== receipt.docs.digest || this.commit(git, "HEAD") !== commit || !releaseTrackedClean(this.root, git)) throw new ReleaseAuthorizationError("publish checkout or documentation evidence changed");
         return { ok: true, receipts: [this.matched(git, version, commit)] };

package/src/hub/sdlc-release.ts

@@ -1,6 +1,7 @@
 import type { Task } from "./board.ts";
 import type { Release } from "./planning.ts";
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { childEnv, stopOwnedProcess } from "./child-process.ts";
 import { hubGitSync } from "./git.ts";
@@ -23,7 +24,7 @@ const sdlcGh: SdlcGh = async (...args) => {
 export interface DocEvidence { schemaVersion: 1; head?: string; version?: string; documents: { path?: string; state: "fresh" | "stale" | "nonancestor" | "unknown"; verifiedAgainst?: string; commits?: number; dirty?: boolean }[]; errors: number; fresh: boolean; }
 export interface ReleaseReadiness { /** #481 AC12: interval, approval-to-release lead time and hotfix rate over shipped releases, filled by Tasks.releaseReadiness. */ releaseMetrics?: ReturnType<typeof releaseMetrics>; repo: string; head?: string; version?: string; tag?: string; tagCommit?: string; commits: string[]; mergedPrs: { pr: number; commit: string }[]; documents?: DocEvidence; liveIssues: { id: number; state: "open" | "closed" | "unknown" }[]; blockers: string[]; sourceReady: boolean; native: "unverified"; ready: false; }
 export type ReleaseGit = (args: string[]) => { code: number; stdout: string };
-export interface ReleaseReaders { gh?: SdlcGh; git?: ReleaseGit; docs?: (root: string, timeoutMs: number) => Promise<DocEvidence | undefined>; }
+export interface ReleaseReaders { gh?: SdlcGh; git?: ReleaseGit; docs?: (root: string, timeoutMs: number) => Promise<DocEvidence | undefined>; /** Test seam (#1120): the checker program the default docs reader spawns. */ checker?: string; }
 const SHA = /^[0-9a-f]{40}$/;
 const VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
@@ -34,21 +35,31 @@ function tagMatches(target: unknown, commit: string): boolean {
   return typeof oid === "string" && SHA.test(oid) && oid === commit;
 }
 /** Package-owned checker only; no caller-supplied program or document text is executed. */
-export function readDocEvidence(root: string, timeoutMs = 10_000): Promise<DocEvidence | undefined> {
+/** #1120: why no evidence could be read, apart from evidence that says the documents are stale. */
+export type DocEvidenceRead = { evidence: DocEvidence } | { unavailable: string };
+const CHECKER_PATH = fileURLToPath(new URL("../../scripts/check-docs.mjs", import.meta.url));
+const CHECKER_MISSING = "the documentation checker scripts/check-docs.mjs is missing from the running hub, which predates the fix that carries it into captured runtimes; record consent from a hub started from a checkout or a release that carries the checker (docs/sdlc.md, release preparation)";
+const CHECKER_FAILED = "the documentation checker in the running hub did not finish with readable evidence (it timed out, crashed or printed unreadable output); run `node scripts/check-docs.mjs --json --committed` in the candidate checkout to see why, then retry";
+export async function readDocEvidence(root: string, timeoutMs = 10_000): Promise<DocEvidence | undefined> {
+  const read = await readDocEvidenceDetailed(root, timeoutMs);
+  return "evidence" in read ? read.evidence : undefined;
+}
+export function readDocEvidenceDetailed(root: string, timeoutMs = 10_000, checker = CHECKER_PATH): Promise<DocEvidenceRead> {
+  if (!existsSync(checker)) return Promise.resolve({ unavailable: CHECKER_MISSING });
   return new Promise(resolve => {
-    const child = spawn(process.execPath, [fileURLToPath(new URL("../../scripts/check-docs.mjs", import.meta.url)), root, "--json", "--committed"], { cwd: root, env: childEnv(), detached: true, stdio: ["ignore", "pipe", "ignore"] });
+    const child = spawn(process.execPath, [checker, root, "--json", "--committed"], { cwd: root, env: childEnv(), detached: true, stdio: ["ignore", "pipe", "ignore"] });
     let output = "", invalid = false;
     const stop = () => { invalid = true; void stopOwnedProcess(child, { group: true }).catch(() => {}); };
     const timer = setTimeout(stop, Math.max(1, Math.min(10_000, timeoutMs)));
     child.stdout?.setEncoding("utf8"); child.stdout?.on("data", chunk => { output += chunk; if (Buffer.byteLength(output) > 256 * 1024) { output = ""; stop(); } });
-    child.once("error", () => { invalid = true; clearTimeout(timer); resolve(undefined); });
+    child.once("error", () => { invalid = true; clearTimeout(timer); resolve({ unavailable: CHECKER_FAILED }); });
     child.once("close", (code, signal) => {
-      clearTimeout(timer); if (invalid || signal || (code !== 0 && code !== 1)) return resolve(undefined);
+      clearTimeout(timer); if (invalid || signal || (code !== 0 && code !== 1)) return resolve({ unavailable: CHECKER_FAILED });
       try {
         const data = JSON.parse(output);
-        if (data.schemaVersion !== 1 || !Array.isArray(data.documents) || data.documents.length > 128 || !Number.isSafeInteger(data.errors) || data.errors < 0 || typeof data.fresh !== "boolean" || (data.head !== undefined && !SHA.test(data.head)) || (data.version !== undefined && !VERSION.test(data.version)) || data.documents.some((d: {state?:string}) => !["fresh","stale","nonancestor","unknown"].includes(d.state ?? ""))) return resolve(undefined);
-        resolve(data);
-      } catch { resolve(undefined); }
+        if (data.schemaVersion !== 1 || !Array.isArray(data.documents) || data.documents.length > 128 || !Number.isSafeInteger(data.errors) || data.errors < 0 || typeof data.fresh !== "boolean" || (data.head !== undefined && !SHA.test(data.head)) || (data.version !== undefined && !VERSION.test(data.version)) || data.documents.some((d: {state?:string}) => !["fresh","stale","nonancestor","unknown"].includes(d.state ?? ""))) return resolve({ unavailable: CHECKER_FAILED });
+        resolve({ evidence: data });
+      } catch { resolve({ unavailable: CHECKER_FAILED }); }
     });
   });
 }
@@ -101,8 +112,10 @@ export async function readReleaseReadiness(root: string, repo: string, liveIssue
       } catch { report.blockers.push("merged PR coverage unknown or truncated"); break; }
     }
   }
-  const left = deadline - performance.now(); report.documents = left > 0 ? await (readers.docs ?? readDocEvidence)(root,Math.min(10_000,left)) : undefined;
-  if (!report.documents || report.documents.head !== head || !report.documents.fresh || report.documents.errors || report.documents.documents.some(d => d.state !== "fresh")) report.blockers.push("documentation freshness or ancestry is unknown or stale");
+  const left = deadline - performance.now(); report.documents = left > 0 ? await (readers.docs ?? ((dir, ms) => readDocEvidenceDetailed(dir, ms, readers.checker).then(read => "evidence" in read ? read.evidence : undefined)))(root,Math.min(10_000,left)) : undefined;
+  const checkerMissing = !readers.docs && !existsSync(readers.checker ?? CHECKER_PATH); // #1120: a hub without the checker says so instead of calling the documents stale
+  if (checkerMissing) report.blockers.push("documentation checker unavailable in the running hub: " + CHECKER_MISSING);
+  else if (!report.documents || report.documents.head !== head || !report.documents.fresh || report.documents.errors || report.documents.documents.some(d => d.state !== "fresh")) report.blockers.push("documentation freshness or ancestry is unknown or stale");
   if (!liveIssues.length) report.blockers.push("native verification ledger unspecified");
   for (const id of liveIssues) {
     const reply = await gh(["issue","view",String(id),"--repo",repo,"--json","number,state"]); let state: "open"|"closed"|"unknown" = "unknown";

package/src/hub/sdlc.ts

@@ -1,5 +1,6 @@
 import { parseIssueLabels, parseRedFirst, testIntegrityBlockers, type RedFirstReceipt, type TestIntegrity } from "./test-integrity.ts";
 import { planConformanceBlockers, type PlanConformance } from "./plan-conformance.ts";
+import { controlWriteSpan } from "./control-write-trace.ts";
 import { DEFAULT_MAX_NITS, findingsForHead, findingHead, findingTally, type ReviewFindingSet, type ReviewFindingTally } from "./review-findings.ts";
 import type { CostPlan } from "./cost-governance.ts";
 import { bandsConfig, type BandsConfig } from "./sdlc-metrics.ts";
@@ -427,7 +428,7 @@ export function touchingPrs(prs: { pr: number; paths: string[] }[]): { before: n
 
 export type SdlcGh = (args: string[], timeoutMs?: number, cwd?: string, maxOutputBytes?: number) => Promise<{ code: number; stdout: string }>;
 /** Fixed argv and bounded output and time; diagnostics never expose credentials or remote text. Reads, except the one guarded `gh pr merge` that `sdlc-merge.ts` builds (#786). */
-export const sdlcGh: SdlcGh = (args, timeoutMs = 10_000, cwd, maxOutputBytes = 256 * 1024) => new Promise((resolve) => {
+export const sdlcGh: SdlcGh = (args, timeoutMs = 10_000, cwd, maxOutputBytes = 256 * 1024) => controlWriteSpan("external", () => new Promise<{ code: number; stdout: string }>((resolve) => {
   const outputLimit = Number.isSafeInteger(maxOutputBytes) ? Math.min(2 * 1024 * 1024, Math.max(1, maxOutputBytes)) : 256 * 1024;
   let child: ReturnType<typeof spawn>;
   try {
@@ -440,7 +441,7 @@ export const sdlcGh: SdlcGh = (args, timeoutMs = 10_000, cwd, maxOutputBytes = 2
   child.stdout?.on("data", chunk => { if (failed) return; stdout += chunk.toString(); if (Buffer.byteLength(stdout) > outputLimit) { stdout = ""; stop(); } });
   child.once("error", () => { failed = true; clearTimeout(timer); resolve({ code: 1, stdout: "" }); });
   child.once("close", code => { clearTimeout(timer); resolve({ code: failed ? 1 : code ?? 1, stdout: failed ? "" : stdout }); });
-});
+}));
 
 /** Read-only, fixed argv: the issue's edit times, never its body. */
 export async function readSpecEdit(repoName: string, issue: number, run: SdlcGh = sdlcGh): Promise<SpecEdit | undefined> {
@@ -506,6 +507,18 @@ export async function readSdlcPr(receipt: SdlcReceipt, run: SdlcGh = sdlcGh, wit
   } catch { return undefined; }
 }
 
+/** Read only the current PR head when broader PR evidence is unavailable. */
+export async function readSdlcPrHead(receipt: SdlcReceipt, run: SdlcGh = sdlcGh): Promise<string | undefined> {
+  if (!repo(receipt.repo) || !id(receipt.pr)) return undefined;
+  try {
+    const result = await run(["pr", "view", String(receipt.pr), "--repo", receipt.repo, "--json", "headRefOid"], 10_000, undefined, 1024);
+    if (result.code !== 0 || Buffer.byteLength(result.stdout) > 1024) return undefined;
+    const value: unknown = JSON.parse(result.stdout);
+    const head = (value as { headRefOid?: unknown } | null)?.headRefOid;
+    return sha(head) ? head : undefined;
+  } catch { return undefined; }
+}
+
 export interface PlanIssueMetadata {
   repo: string;
   issue: number;

package/src/hub/settings.ts

@@ -85,6 +85,9 @@ export const SETTINGS: readonly SettingDef[] = [
   { 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"] },
+  // #1057: the worktree shelf. Both only choose what the shelf shows and when it raises one inbox alert; neither deletes anything, so they are safe and live.
+  { key: "worktrees.quiet_days", group: "Switches", label: "Worktrees: shelve one idle this many days (0 never)", type: "integer", min: 0, max: 3650, store: "config", applies: "live", risk: "safe", path: ["worktrees", "quiet_days"] },
+  { key: "worktrees.alert_over", group: "Switches", label: "Worktrees: inbox alert above this many settled (0 never)", type: "integer", min: 0, max: 100000, store: "config", applies: "live", risk: "safe", path: ["worktrees", "alert_over"] },
   { key: "coordination", group: "Switches", label: "Coordination of overlapping owners", type: "enum", values: ["advisory", "turn-free"], store: "config", applies: "next use", risk: "safe", path: ["coordination"] },
 ];