@staix/agent-hub 0.29.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;
@@ -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/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"] },
 ];
 

package/src/hub/tasks.ts

@@ -3319,6 +3319,8 @@ export class Tasks {
 
   async propose(by: PeerId, input: { title?: string; detail?: string; class?: string; role?: unknown; refs?: TaskRefs; plan?: TaskPlan; owner?: PeerId; after?: unknown; urgent?: unknown; needs_network?: unknown; needs_worktree?: unknown; backlog?: unknown; draft?: unknown; goal?: unknown }, external?: GitHubSource, created?: () => void, fence?: () => string | undefined): Promise<Task> {
     const requestCheck = this.requestCheck(by, fence);
+    const plan = cleanPlan(input.plan, this.d.profileData ?? this.d.profile ?? "dev");
+    this.validatePlanSources(plan);
     requireLocalTaskPeer(input.owner);
     external = external ? { ...external } : undefined;
     if (external && (!this.personOrConductor(by) || input.backlog !== true)) throw new PreEffectToolRefusal("external intake requires person-owned backlog staging");
@@ -3355,7 +3357,6 @@ export class Tasks {
     let baseGiven: TaskClass | undefined;
     try { if (given !== undefined) baseGiven = profileClass(given, this.d.profileData ?? profile); } catch (error) { throw new PreEffectToolRefusal((error as Error).message); }
     const text = { title, detail: String(input.detail ?? "").slice(0, 8000), refs: cleanRefs(input.refs) };
-    const plan = cleanPlan(input.plan, this.d.profileData ?? profile);
     // The plan reaches other owners, so a PII pattern in it makes the task a PII task like one in the detail would.
     const screenDetail = [text.detail, text.refs.repo, external?.repo, external?.url].filter(value => value !== undefined && value !== "").join("\n");
     const signals = this.signalsFor({ ...text, detail: [screenDetail, planText(plan)].join("\n"), plan });
@@ -3431,10 +3432,14 @@ export class Tasks {
     }
   }
 
-  async returnUntouchedToBacklog(by: PeerId, input: { id: number; revision: number; reason: string }): Promise<Task> {
+  async returnUntouchedToBacklog(by: PeerId, input: { id: number; revision: number; reason: string; fields?: unknown }): Promise<Task> {
     this.plannerWriteAuthority(by);
     if (!Number.isSafeInteger(input.id) || input.id < 1 || !Number.isSafeInteger(input.revision) || input.revision < 0
       || typeof input.reason !== "string" || !input.reason.trim() || input.reason.length > 1000) throw new PreEffectToolRefusal("untouched return needs an id, revision and bounded reason");
+    let parsed: PlanningFields;
+    try { parsed = planningPatch(input.fields); } catch (error) { throw new PreEffectToolRefusal(`${(error as Error).message}; use fields.reserved with an agent peer id or null, or omit fields`); }
+    if (Object.keys(parsed).some(key => key !== "reserved")) throw new PreEffectToolRefusal("untouched return fields may contain only reserved; remove every other field, or omit fields");
+    const patch: Pick<PlanningFields, "reserved"> = Object.hasOwn(parsed, "reserved") ? { reserved: parsed.reserved } : {};
     const validate = () => {
       const task = this.need(input.id, false, true);
       this.plannerWriteAuthority(by, task);
@@ -3442,6 +3447,14 @@ export class Tasks {
       if (by !== USER && task.pinned) throw new PreEffectToolRefusal("pinned work requires the person");
       const release = task.release == null ? undefined : this.d.board.release(task.release);
       if (release && (["shipped", "dropped"].includes(release.state) || by !== USER && release.state === "frozen")) throw new PreEffectToolRefusal("settled or frozen release scope cannot return");
+      if (Object.hasOwn(patch, "reserved")) {
+        if (by !== USER && this.hasPersonReservation(task)) throw new PreEffectToolRefusal("a person's reservation is retained; ask the person to change it");
+        const reserved = patch.reserved, definitionOf = this.d.adapterCatalog?.definitionOf ?? builtinDefinitionOf;
+        if (reserved && !definitionOf(reserved, this.d.instances?.()) && !this.d.bus.knownPeers().includes(reserved) && !this.d.routing().classes[task.class]?.peers.includes(reserved)) throw new PreEffectToolRefusal("reserved owner is not a supported or configured peer; choose a peer from ahub status");
+        if (reserved && !this.d.bus.isRostered(reserved)) throw new PreEffectToolRefusal("reserved owner is off roster; choose a rostered peer from ahub status or ask the person to update the roster");
+        if (reserved && this.excluded(task).includes(reserved)) throw new PreEffectToolRefusal(`${reserved} is excluded from this task (it declined it or was escalated away from it for good); a reservation for it can never be honoured. Only a person's ahub task assign lifts the exclusion`);
+        if (reserved) this.requireCapabilities(task, reserved);
+      }
       return task;
     };
     const task = validate(), flow = task.history.length;
@@ -3450,14 +3463,14 @@ export class Tasks {
     const confirmed = validate();
     if (confirmed.history.length !== flow) throw new PreEffectToolRefusal("task changed during untouched return");
     const capacity = this.capacityBefore(confirmed);
-    const returned = this.d.board.update(confirmed.id, by, "backlog returned untouched", { state: "backlog", owner: null, reviewer: null }, input.reason.trim(), { ...(withheld ? { withheld: true } : {}) }, flow);
+    const returned = this.d.board.update(confirmed.id, by, "backlog returned untouched", { state: "backlog", owner: null, reviewer: null, ...patch }, input.reason.trim(), { ...(withheld ? { withheld: true } : {}) }, flow);
     this.writePlannerNotices(returned, capacity);
     this.offered.delete(confirmed.id);
     this.cohorts.leave(confirmed.id);
     this.withdrawRoleRequest(confirmed, returned, "owner");
     this.withdrawRoleRequest(confirmed, returned, "reviewer");
     this.incomingBacklog.add(confirmed.id);
-    this.planningRecorded({ by, task: confirmed.id, fields: ["return"], revision: confirmed.planningRevision ?? 0 });
+    this.planningRecorded({ by, task: confirmed.id, fields: ["return", ...Object.keys(patch)], revision: returned.planningRevision ?? 0 });
     await this.releaseHeld(confirmed.owner); // its owner's slot is free (#655)
     return returned;
   }
@@ -5776,6 +5789,8 @@ export class Tasks {
     const metadata = acceptRefs(refs);
     const task = this.need(id, false, true);
     this.mine(task, by, "owner", true);
+    const proposedPlan = plan == null ? undefined : cleanPlan(plan, (task.profile ?? "dev") === (this.d.profile ?? "dev") ? this.d.profileData ?? task.profile ?? "dev" : task.profile ?? "dev");
+    this.validatePlanSources(proposedPlan && Object.keys(proposedPlan).length ? proposedPlan : task.plan);
     this.acceptanceCapacity(task, 0, "check"); // #1080: an urgent task may still take unaccepted offers; `accept` does that, after its gates
     if (metadata && !this.isPii(task) && (!this.nameable(metadata.repo!) || looksSecret(metadata.repo!) || this.aboutPrivatePath("", metadata.repo!, task))) throw new PreEffectToolRefusal("this repository metadata is private or sensitive and is not kept");
     const draft = metadata ? { ...task, refs: { ...task.refs, ...metadata } } : task;
@@ -5890,6 +5905,12 @@ export class Tasks {
     throw new PreEffectToolRefusal(`planner WIP capacity for ${owner}: limit ${limit}; open tasks ${ids(open)} (${parts.join("; ")})${pending ? `; pending claims ${pending}` : ""}; ${next}`);
   }
 
+  private validatePlanSources(plan: TaskPlan = {}): void {
+    for (const id of plan.sources ?? []) if (!this.d.intake?.sourceKnown(id)) {
+      throw new PreEffectToolRefusal(`unknown source ${id}; list registered ids with ahub source list`);
+    }
+  }
+
   /**
    * With a plan, the owners of overlapping tasks get it as a ride-along line, and an overlap only the plan reveals is
    * announced like one found at assignment (issue #31).
@@ -5901,6 +5922,11 @@ export class Tasks {
     this.mine(task, by, "owner", true);
     this.ready(task, true);
     if (task.state !== "proposed" && task.state !== "changes_requested" && task.state !== "in_progress") throw new PreEffectToolRefusal(`task #${task.id} is ${task.state}: cannot move to in_progress`);
+    // Models send null or {} for an optional field they leave empty: neither replaces a plan.
+    const given = plan == null ? undefined : cleanPlan(plan, (task.profile ?? "dev") === (this.d.profile ?? "dev") ? this.d.profileData ?? task.profile ?? "dev" : task.profile ?? "dev");
+    // File-list intent still replaces the old lists; omitted budget keys retain the planner-reviewed scope.
+    const cleaned = given && Object.keys(given).length ? { ...cleanCostPlan(task.plan ?? {}), ...given } : undefined;
+    this.validatePlanSources(cleaned ?? task.plan);
     this.studyDispatchCheck(task, task.owner ?? undefined);
     this.declaredNeedCheck(task, task.owner ?? by); // the owner's capability, also when the console user accepts on its behalf (`mine` admits USER)
     this.acceptanceCapacity(task, 0, "check");
@@ -5911,10 +5937,6 @@ export class Tasks {
       this.reviewedAdmissions.delete(task.id);
       if (!readback || readback.flow !== task.history.length || readback.owner !== task.owner) throw new PreEffectToolRefusal("current plan-review readback required before acceptance");
     }
-    // Models send null or {} for an optional field they leave empty: neither replaces a plan.
-    const given = plan == null ? undefined : cleanPlan(plan, (task.profile ?? "dev") === (this.d.profile ?? "dev") ? this.d.profileData ?? task.profile ?? "dev" : task.profile ?? "dev");
-    // File-list intent still replaces the old lists; omitted budget keys retain the planner-reviewed scope.
-    const cleaned = given && Object.keys(given).length ? { ...cleanCostPlan(task.plan ?? {}), ...given } : undefined;
     if (this.d.sdlc?.config().mode === "enforce" && task.sdlc?.planReview && !task.sdlc.planReview.scope
       && given && Object.keys(cleanCostPlan(given)).length) throw new PreEffectToolRefusal("legacy plan cost scope is unspecified; record a scoped planner review before acceptance");
     if (this.d.sdlc?.config().mode === "enforce" && task.sdlc?.planReview?.scope

package/src/hub/ui.ts

@@ -149,7 +149,9 @@ export function startDashboard(options: DashboardOptions) {
           return reject(403, "live-test dashboard cannot write person-attributed content; use peer tools");
         }
         if (input.action === "sdlc_queue" || input.action === "sdlc_release") server.timeout(req, 35);
+        else if (input.action === "worktrees_refresh_prs") server.timeout(req, 45); // #1057: bounded gh reads (25 s) and two git passes
         else if (input.action === "backlog_split") server.timeout(req, Math.ceil((BACKLOG_SPLIT_SCREEN_TIMEOUT_MS + HUB_DB_BUSY_TIMEOUT_MS + 5_000) / 1000) + 5);
+        else if (input.action === "intake") server.timeout(req, 95); // the CLI's 90 s intake cap plus the HTTP response margin
         return json(await options.action(input, sessionOf(cookie)));
       } catch {
         // Exceptions may quote private task text or backend details. Never echo them to the page.

package/src/hub/worktree-prs.ts

@@ -0,0 +1,100 @@
+import { readSdlcPr, type SdlcGh } from "./sdlc.ts";
+import type { PrObserver, WorktreeFact } from "./worktree-shelf.ts";
+
+/**
+ * #1057 D1: the explicit "refresh PR states" action. It is the ONLY code that lets the worktree shelf learn a PR state from GitHub, through `readSdlcPr`
+ * (the same readback the guarded merge uses), and it runs only when a person asks. A panel refresh, `ahub worktrees` and the inbox alert never reach it, so
+ * they make no GitHub call (AC5): `worktree-shelf.ts` imports nothing from here and holds no GitHub access.
+ *
+ * What it reads is kept in memory, keyed by repository and PR number, and offered back to the shelf as a `PrObserver`.
+ * ponytail: the observations live in the daemon's memory, so a restart forgets them and those rows read `unknown` again until the next refresh; the upgrade is a
+ * `worktree_pr` table beside `worktree_override`, which is not worth a schema change before live use shows people refresh often.
+ */
+export const REFRESH_MAX_PRS = 8, REFRESH_CALL_MS = 8_000, REFRESH_TOTAL_MS = 25_000, OBSERVATIONS_MAX = 512;
+
+/**
+ * When GitHub says a PR that is no longer open was merged or closed, in ms. A second, narrow read (`pr view <n> --json mergedAt,closedAt`) that only a refresh makes and
+ * only for a PR `readSdlcPr` found merged or closed, so the shared readback the guarded merge and the queue use is unchanged. A missing, malformed or non-finite time is undefined,
+ * never 0: a merged PR with no change time is `unknown` to the partition, not settled.
+ */
+export async function readPrChangeTime(repo: string, pr: number, state: "merged" | "closed", gh: SdlcGh): Promise<number | undefined> {
+  // An owner and a name, each starting with a letter or digit: `..`, `.x` and `-x` are never a repository, so a hostile slug cannot reach gh as a path or a flag.
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9_.][A-Za-z0-9_.-]*$/.test(repo) || repo.split("/").some(part => part === "." || part === "..") || !Number.isSafeInteger(pr) || pr < 1) return undefined;
+  try {
+    const view = await gh(["pr", "view", String(pr), "--repo", repo, "--json", "mergedAt,closedAt"], 8_000, undefined, 4096);
+    if (view.code !== 0) return undefined;
+    const value = JSON.parse(view.stdout) as { mergedAt?: unknown; closedAt?: unknown } | null;
+    const text = state === "merged" ? value?.mergedAt ?? value?.closedAt : value?.closedAt;
+    const at = typeof text === "string" && text.length <= 40 ? Date.parse(text) : NaN;
+    return Number.isFinite(at) && at > 0 ? at : undefined;
+  } catch { return undefined; }
+}
+
+export interface PrObservation { state: "open" | "merged" | "closed"; changedAt?: number; at: number }
+export interface RefreshResult {
+  /** PRs read and stored. */
+  read: number;
+  /** PRs GitHub could not answer for (unreadable, no access, a gh failure): their state stays what it was. */
+  failed: number;
+  /** PRs not asked about because the cap or the time budget was reached. */
+  skipped: number;
+}
+
+/** A bounded, insertion-ordered map of what the last refreshes read. */
+export class PrObservations {
+  private readonly seen = new Map<string, PrObservation>();
+  record(repo: string, pr: number, observation: PrObservation): void {
+    const key = `${repo}#${pr}`;
+    this.seen.delete(key); this.seen.set(key, observation);
+    while (this.seen.size > OBSERVATIONS_MAX) this.seen.delete(this.seen.keys().next().value!);
+  }
+  /** The shelf's view of it: state and change time only. */
+  observer: PrObserver = (repo, pr) => {
+    const found = this.seen.get(`${repo}#${pr}`);
+    return found ? { state: found.state, ...(found.changedAt !== undefined ? { changedAt: found.changedAt } : {}) } : undefined;
+  };
+  /** When the newest observation was read, or undefined when none was. */
+  get lastAt(): number | undefined { let at: number | undefined; for (const value of this.seen.values()) at = Math.max(at ?? 0, value.at); return at; }
+  get size(): number { return this.seen.size; }
+}
+
+/** The PRs a refresh would ask about: bound tasks with a repository and a PR that the board does not already show as merged, oldest activity first. */
+export function refreshTargets(facts: readonly WorktreeFact[], limit = REFRESH_MAX_PRS): { repo: string; pr: number }[] {
+  const seen = new Set<string>(), out: { repo: string; pr: number }[] = [];
+  const candidates = facts.filter(f => !f.main && !f.instance && f.task?.repo !== undefined && f.task.pr !== undefined && f.pr.state !== "merged")
+    .sort((a, b) => a.lastActiveAt - b.lastActiveAt);
+  for (const fact of candidates) {
+    const key = `${fact.task!.repo}#${fact.task!.pr}`;
+    if (seen.has(key)) continue;
+    seen.add(key); out.push({ repo: fact.task!.repo!, pr: fact.task!.pr! });
+  }
+  return out.slice(0, limit);
+}
+
+/**
+ * Read each target once, one at a time, under one total budget. `gh` is the host's runner (`sdlcGh` bound to the project), never an argument a request supplies.
+ * `readSdlcPr` validates the repository and PR number itself and builds a fixed read-only argv. Every failure is counted and the old state stands.
+ */
+export async function refreshPrStates(
+  targets: readonly { repo: string; pr: number }[],
+  gh: SdlcGh,
+  store: PrObservations,
+  options: { now?: () => number; totalMs?: number; callMs?: number; max?: number } = {},
+): Promise<RefreshResult> {
+  const now = options.now ?? Date.now, started = now(), total = options.totalMs ?? REFRESH_TOTAL_MS, perCall = options.callMs ?? REFRESH_CALL_MS;
+  const left = () => Math.max(0, started + total - now());
+  const bounded: SdlcGh = async (args, timeoutMs, cwd, maxOutputBytes) => left() <= 0 ? { code: 1, stdout: "" } : gh(args, Math.max(1, Math.min(timeoutMs ?? perCall, perCall, left())), cwd, maxOutputBytes);
+  const asked = targets.slice(0, options.max ?? REFRESH_MAX_PRS);
+  let read = 0, failed = 0, done = 0;
+  for (const target of asked) {
+    if (left() <= 0) break;
+    done++;
+    const evidence = await readSdlcPr({ stage: "pr", repo: target.repo, pr: target.pr }, bounded).catch(() => undefined);
+    if (!evidence) { failed++; continue; }
+    const state = evidence.state === "MERGED" ? "merged" : evidence.state === "CLOSED" ? "closed" : "open";
+    const changedAt = state === "open" ? undefined : await readPrChangeTime(target.repo, target.pr, state, bounded);
+    store.record(target.repo, target.pr, { state, ...(changedAt !== undefined ? { changedAt } : {}), at: now() });
+    read++;
+  }
+  return { read, failed, skipped: targets.length - done };
+}