@staix/agent-hub 0.29.0 → 0.31.0

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 };
+}

package/src/hub/worktree-shelf.ts

@@ -0,0 +1,246 @@
+import { execFile } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { basename, join, relative, sep } from "node:path";
+import { childEnv } from "./child-process.ts";
+import { hubGitArgv, hubGitEnv } from "./git.ts";
+import { HUB } from "./envelope.ts";
+import { realPath } from "./project.ts";
+import type { Task } from "./board.ts";
+
+/**
+ * #1057 worktree shelf. Which worktrees are finished is DERIVED at read time from facts and two person overrides, never stored as a flag.
+ * This module reads facts and computes the partition. It never deletes a worktree or a local branch: removal exists only in the person's
+ * CLI process (`worktree-tidy.ts`, a later change), and `test/worktree-shelf.test.ts` greps the daemon-reachable modules for any removal argv.
+ */
+
+export type PrState = "open" | "merged" | "closed" | "unknown";
+/** `settled` is what a PII-bound row says in a reply for a merged or closed PR: the reason is real on the host, but a reply carries no PR state of a private task. */
+export type SettledReason = "merged" | "closed" | "quiet" | "parked" | "settled";
+export type OverrideValue = "settled" | "active";
+export interface WorktreeOverride { path: string; value: OverrideValue; at: number }
+
+export interface WorktreeFact {
+  /** Absolute, host-only. A row shown to a person is displayed through `displayPath`. */
+  path: string;
+  branch: string | null;
+  head: string;
+  locked: boolean;
+  prunable: boolean;
+  /** The project's main checkout: never shelved. */
+  main: boolean;
+  /** A configured instance worktree (`.worktrees/<instance>`): never shelved. */
+  instance: boolean;
+  /** Max of the HEAD commit time, the worktree index mtime and the latest time someone other than the hub wrote to the bound task. 0 when none could be read. */
+  lastActiveAt: number;
+  /** False when the commit time or the index could not be read (a failed git call or a spent budget): such a row is never settled by a PR or by quiet time, because 'no newer work' is unknown. */
+  activityKnown?: boolean;
+  /** `private`: the bound task is a PII task. The binding still drives the partition and tidy's refusals on the host, but `row()` never puts its id, PR or state in a reply. */
+  task?: { id: number; state: string; pr?: number; repo?: string; private?: true };
+  pr: { state: PrState; changedAt?: number };
+}
+/** A row built for a reply. A PII-bound row carries `private: true` and `taskState: "private"` and no task id or PR. This is the one place a reply row is made, so redaction happens here (AGENTS.md), never at a call site. */
+export interface ShelfRow { path: string; branch: string | null; reason?: SettledReason; task?: number; taskState?: string; pr?: number; private?: true; /** The main checkout or a declared instance worktree: never shelved, so a panel offers no Park for it. */ fixed?: true; lastActiveAt: number }
+export interface Partition { live: ShelfRow[]; settled: ShelfRow[] }
+
+const DAY_MS = 86_400_000;
+const row = (fact: WorktreeFact, reason?: SettledReason): ShelfRow => ({
+  path: fact.path, branch: fact.branch, lastActiveAt: fact.lastActiveAt, ...(fact.main || fact.instance ? { fixed: true as const } : {}),
+  ...(reason ? { reason: fact.task?.private && (reason === "merged" || reason === "closed") ? "settled" as const : reason } : {}),
+  ...(fact.task?.private ? { private: true as const, taskState: "private" }
+    : { ...(fact.task ? { task: fact.task.id, taskState: fact.task.state } : {}), ...(fact.task?.pr !== undefined ? { pr: fact.task.pr } : {}) }),
+});
+
+/** An override counts only while no newer activity exists: `lastActiveAt <= at` (D2). Newer activity makes it inert. */
+export const overrideInForce = (override: WorktreeOverride | undefined, lastActiveAt: number): override is WorktreeOverride =>
+  !!override && lastActiveAt <= override.at;
+
+/**
+ * D3, pure. A row whose activity is unknown (`activityKnown === false`) is live: every settling rule compares with `lastActiveAt`, which is then not a fact.
+ * Rules in order: (1) the main checkout and instance worktrees are never shelved; (2) an effective override wins; (3) a merged or
+ * closed PR with `lastActiveAt <= changedAt` is settled; (4) `quietDays > 0` and a quiet span of at least that long is settled; (5) live.
+ * `now`, the facts and the overrides are arguments: no clock, no I/O.
+ */
+export function partition(facts: readonly WorktreeFact[], overrides: readonly WorktreeOverride[], now: number, quietDays: number): Partition {
+  const byPath = new Map(overrides.map(o => [o.path, o]));
+  const out: Partition = { live: [], settled: [] };
+  for (const fact of facts) {
+    if (fact.main || fact.instance || fact.activityKnown === false) { out.live.push(row(fact)); continue; }
+    const override = byPath.get(fact.path);
+    if (overrideInForce(override, fact.lastActiveAt)) {
+      if (override.value === "settled") out.settled.push(row(fact, "parked")); else out.live.push(row(fact));
+      continue;
+    }
+    if ((fact.pr.state === "merged" || fact.pr.state === "closed") && fact.pr.changedAt !== undefined && fact.lastActiveAt <= fact.pr.changedAt) {
+      out.settled.push(row(fact, fact.pr.state)); continue;
+    }
+    if (quietDays > 0 && fact.lastActiveAt > 0 && now - fact.lastActiveAt >= quietDays * DAY_MS) { out.settled.push(row(fact, "quiet")); continue; }
+    out.live.push(row(fact));
+  }
+  return out;
+}
+
+/** Project-relative inside the root (the root itself is `.`), otherwise the basename only: paths stay host-only, as in `snapshots.ts`. */
+export function displayPath(root: string, path: string): string {
+  if (path === root) return ".";
+  const rel = relative(root, path);
+  return rel && !rel.startsWith("..") && !rel.startsWith(sep) && rel !== path ? rel : basename(path);
+}
+
+/** Whether a path is the root or below it, so a row can be resolved against the project root and one outside it cannot. */
+export const shelfInsideRoot = (root: string, path: string): boolean => path === root || (!relative(root, path).startsWith("..") && !relative(root, path).startsWith(sep) && relative(root, path) !== path);
+
+/**
+ * The latest time anyone but the hub wrote to a task: its work, not its bookkeeping. The hub's own entries (the merge result, the owner notice,
+ * sweeps) follow the event they record, so counting them would put `lastActiveAt` after a merge's `changedAt` and a merged task could never settle (#1057 D1/D3).
+ */
+export const taskWorkAt = (task: Pick<Task, "history" | "created">): number =>
+  Math.max(task.created, ...task.history.filter(h => h.by !== HUB && Number.isFinite(h.at)).map(h => h.at));
+
+/** The task a worktree branch belongs to: the open task, else the most recently updated one, whose `refs.branch` equals the branch. */
+export function boundTask(tasks: readonly Pick<Task, "id" | "state" | "refs" | "sdlc" | "updated" | "created" | "history">[], branch: string | null): WorktreeFact["task"] & { workAt: number } | undefined {
+  if (!branch) return undefined;
+  const matching = tasks.filter(t => t.refs.branch === branch);
+  if (!matching.length) return undefined;
+  const closed = (state: string) => state === "approved" || state === "cancelled";
+  const pick = [...matching].sort((a, b) => Number(closed(a.state)) - Number(closed(b.state)) || b.updated - a.updated)[0]!;
+  const pr = pick.sdlc?.pr, repo = pick.sdlc?.repo;
+  return { id: pick.id, state: pick.state, ...(typeof pr === "number" ? { pr } : {}), ...(typeof repo === "string" && typeof pr === "number" ? { repo } : {}), workAt: taskWorkAt(pick) };
+}
+
+/**
+ * PR state from evidence already on the board (D1): only the guarded merge's own record says `merged`. A cancelled task says nothing about its PR (`Tasks.cancel`
+ * touches only the board, so the PR can still be open on GitHub), and a task with no record says nothing either: both are `unknown`. Only the explicit refresh
+ * action, which reads GitHub, may learn `closed` or `open` (a later change).
+ */
+export function prFromTask(task: Pick<Task, "state" | "sdlc" | "history"> | undefined, observed?: PrObserver): WorktreeFact["pr"] {
+  const merge = task?.sdlc?.merge;
+  if (merge && merge.state === "merged" && Number.isFinite(merge.at)) return { state: "merged", changedAt: merge.at };
+  // A PR state the person asked the hub to read (the explicit refresh action) is a stored fact, never fetched here: this module has no GitHub access (AC5).
+  const repo = task?.sdlc?.repo, pr = task?.sdlc?.pr;
+  const seen = typeof repo === "string" && typeof pr === "number" ? observed?.(repo, pr) : undefined;
+  if (seen) return { state: seen.state, ...(seen.changedAt !== undefined && seen.state !== "open" ? { changedAt: seen.changedAt } : {}) };
+  return { state: "unknown" };
+}
+/** The stored result of an explicit PR refresh for one repository and PR number, or undefined when none was read. */
+export type PrObserver = (repo: string, pr: number) => { state: "open" | "merged" | "closed"; changedAt?: number } | undefined;
+
+export interface RawWorktree { path: string; branch: string | null; head: string; locked: boolean; prunable: boolean }
+/** `git worktree list --porcelain -z`: one NUL-separated field per attribute, an empty field ends a record. Bounded. */
+export function parseWorktreeList(stdout: string, limit = 256): { rows: RawWorktree[]; complete: boolean } {
+  const rows: RawWorktree[] = [];
+  let current: Partial<RawWorktree> | undefined;
+  const flush = () => { if (current?.path) rows.push({ path: current.path, branch: current.branch ?? null, head: current.head ?? "", locked: !!current.locked, prunable: !!current.prunable }); current = undefined; };
+  for (const field of stdout.split("\0")) {
+    if (field === "") { flush(); continue; }
+    if (field.startsWith("worktree ")) { flush(); current = { path: field.slice(9) }; continue; }
+    if (!current) continue;
+    if (field.startsWith("HEAD ")) current.head = field.slice(5);
+    else if (field.startsWith("branch refs/heads/")) current.branch = field.slice("branch refs/heads/".length);
+    else if (field === "locked" || field.startsWith("locked ")) current.locked = true;
+    else if (field === "prunable" || field.startsWith("prunable ")) current.prunable = true;
+  }
+  flush();
+  return { rows: rows.slice(0, limit), complete: rows.length <= limit };
+}
+
+export interface ShelfGitPort {
+  /** Read-only git, bounded by `timeoutMs`, never blocking the event loop. `undefined` is a failed or timed-out read, never an empty answer. */
+  run(cwd: string, args: string[], timeoutMs: number): Promise<{ status: number | null; stdout: string } | undefined>;
+}
+/** One git call's ceiling, and the whole read's: a slow repository answers `complete: false` after this, never a stalled hub (D1's snapshot-budget pattern). */
+export const READ_TIMEOUT_MS = 5_000, TOTAL_BUDGET_MS = 3_000, READ_CONCURRENCY = 4;
+export const realShelfGit: ShelfGitPort = {
+  async run(cwd, args, timeoutMs) {
+    if (!shelfReadAllowed(args)) throw new Error("the worktree shelf runs read-only git commands only");
+    const argv = hubGitArgv(["-C", cwd, "-c", "gc.auto=0", "-c", "maintenance.auto=false", ...args]);
+    return await new Promise(resolve => {
+      execFile(argv[0]!, argv.slice(1), { encoding: "utf8", timeout: Math.max(1, Math.min(READ_TIMEOUT_MS, timeoutMs)), killSignal: "SIGKILL", maxBuffer: 1024 * 1024, env: hubGitEnv(childEnv(), { repositoryIsolation: true }) }, (error, stdout) => {
+        const code = (error as (Error & { code?: unknown }) | null)?.code;
+        // a non-zero exit is an answer (status), a spawn failure, timeout or overflow is not
+        resolve(error && typeof code !== "number" ? undefined : { status: typeof code === "number" ? code : 0, stdout: String(stdout ?? "") });
+      });
+    });
+  },
+};
+/**
+ * The only git argv shapes the shelf runs, all reads. `realShelfGit.run` refuses anything else before spawning, so no removal, branch, ref or
+ * prune argv can reach git from the daemon (AC4); the boundary test also greps the module text for them.
+ */
+export const SHELF_GIT_READS: readonly (readonly string[])[] = [
+  ["worktree", "list", "--porcelain", "-z"],
+  ["log", "-1", "--format=%ct", "HEAD"],
+  ["rev-parse", "--absolute-git-dir"],
+];
+export const shelfReadAllowed = (args: readonly string[]): boolean => SHELF_GIT_READS.some(shape => shape.length === args.length && shape.every((word, i) => word === args[i]));
+
+export interface ShelfInput {
+  root: string;
+  /** Called AFTER the git reads, so the board is read once and fresh, never held across an await. */
+  tasks: () => readonly Pick<Task, "id" | "state" | "refs" | "sdlc" | "updated" | "created" | "history">[];
+  /** Whether a task is a PII task (`Tasks.isPii`). Its binding is kept for the partition and the refusals and redacted in the reply row. A host that does not pass it treats no task as private. */
+  isPrivate?: (taskId: number) => boolean;
+  /** Resolved instance worktree paths (`.worktrees/<instance>`): never shelved. */
+  instancePaths: readonly string[];
+  /** Stored PR observations (D1); called after the git reads, in the same synchronous segment as `tasks`. */
+  observed?: PrObserver;
+  git?: ShelfGitPort;
+  now?: () => number;
+  budgetMs?: number;
+}
+export interface ShelfFacts { facts: WorktreeFact[]; complete: boolean; available: boolean }
+
+/** The worktree's own index mtime (D1: it covers uncommitted editing). `undefined` is unknown; a missing index file is a known 0. */
+async function indexMtime(git: ShelfGitPort, path: string, timeoutMs: number): Promise<number | undefined> {
+  const dir = await git.run(path, ["rev-parse", "--absolute-git-dir"], timeoutMs);
+  if (!dir || dir.status !== 0) return undefined;
+  try { const info = await stat(join(dir.stdout.trim(), "index")); return info.isFile() ? info.mtimeMs : 0; }
+  catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT" ? 0 : undefined; }
+}
+
+interface Probe { commitAt: number; touched: number; known: boolean }
+
+/**
+ * D1: facts per worktree. One `worktree list`, then a commit-time read and an index read per worktree, at most `READ_CONCURRENCY` at a time and all under one
+ * total budget. Asynchronous throughout: the daemon's event loop is never held. When the budget is spent, the rows not yet read are still listed, with unknown
+ * activity (live, never settled), and the result says `complete: false`. Never writes.
+ */
+export async function readWorktreeFacts(input: ShelfInput): Promise<ShelfFacts> {
+  const git = input.git ?? realShelfGit, now = input.now ?? Date.now, deadline = now() + (input.budgetMs ?? TOTAL_BUDGET_MS);
+  const left = () => Math.max(0, deadline - now());
+  let root: string;
+  try { root = realPath(input.root); } catch { return { facts: [], complete: false, available: false }; }
+  const listed = await git.run(root, ["worktree", "list", "--porcelain", "-z"], left());
+  if (!listed || listed.status !== 0) return { facts: [], complete: false, available: false };
+  const parsed = parseWorktreeList(listed.stdout);
+  const paths = parsed.rows.map(raw => { try { return realPath(raw.path); } catch { return raw.path; } }); // a prunable worktree's directory is gone: keep the registered path
+  const probes: (Probe | undefined)[] = parsed.rows.map(() => undefined);
+  let next = 0, cut = false;
+  const worker = async () => {
+    for (;;) {
+      const i = next++;
+      if (i >= paths.length) return;
+      if (left() <= 0) { cut = true; return; }
+      const stamp = await git.run(paths[i]!, ["log", "-1", "--format=%ct", "HEAD"], left());
+      const text = stamp && stamp.status === 0 ? stamp.stdout.trim() : "";
+      const touched = left() > 0 ? await indexMtime(git, paths[i]!, left()) : undefined;
+      if (!/^\d{1,12}$/.test(text) || touched === undefined) { probes[i] = { commitAt: 0, touched: 0, known: false }; cut = cut || left() <= 0; continue; }
+      probes[i] = { commitAt: Number(text) * 1000, touched, known: true };
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(READ_CONCURRENCY, paths.length) }, worker));
+  // From here to the return nothing is awaited: the board is read once, synchronously, so it is current for every row.
+  const tasks = input.tasks(), instances = new Set(input.instancePaths), facts: WorktreeFact[] = [];
+  let unread = false;
+  parsed.rows.forEach((raw, i) => {
+    const path = paths[i]!, probe = probes[i], task = boundTask(tasks, raw.branch), bound = task ? tasks.find(t => t.id === task.id) : undefined;
+    if (!probe?.known) unread = true;
+    facts.push({
+      path, branch: raw.branch, head: raw.head, locked: raw.locked, prunable: raw.prunable,
+      main: path === root, instance: instances.has(path),
+      lastActiveAt: Math.max(probe?.commitAt ?? 0, probe?.touched ?? 0, task?.workAt ?? 0), activityKnown: probe?.known === true,
+      ...(task ? { task: { id: task.id, state: task.state, ...(task.pr !== undefined ? { pr: task.pr } : {}), ...(task.repo !== undefined ? { repo: task.repo } : {}), ...(input.isPrivate?.(task.id) ? { private: true as const } : {}) } } : {}),
+      pr: prFromTask(bound, input.observed),
+    });
+  });
+  return { facts, complete: parsed.complete && !cut && !unread, available: true };
+}

package/src/memory/capture.ts

@@ -1,6 +1,7 @@
+import { reviewCaptureExcluded } from "../hub/memory-policy.ts";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { defaultCapturePeer } from "../adapters/definitions/native-identity-defaults.ts";
-import { BOUNDED_TASK_TOOLS, CAPABILITY_TOOLS, HANDOFF_TOOLS, STUDY_TOOLS } from "../hub/hub-tools.ts";
+import { BOUNDED_TASK_TOOLS, CAPABILITY_TOOLS, HANDOFF_TOOLS, QUESTION_TOOLS, STUDY_TOOLS } from "../hub/hub-tools.ts";
 import { MEMORY_READ_TOOLS } from "../hub/read-tools.ts";
 import { isDenied } from "../local/deny.ts";
 import type { MemoryClient } from "./client.ts";
@@ -38,7 +39,9 @@ export class Capture {
   }
 
   observe(call: { tool: string; args: string; output: string; id: string; paths: string[]; sourceId?: string }): void {
-    if (!this.sessionId || ((MEMORY_READ_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || BOUNDED_TASK_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || CAPABILITY_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || STUDY_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || HANDOFF_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, ""))) || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_memory_correct") || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_source_read" || this.opts.skip?.includes(call.tool)) return;
+    if (!this.sessionId || reviewCaptureExcluded(call.tool, call.args) || ((MEMORY_READ_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || BOUNDED_TASK_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || CAPABILITY_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || STUDY_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, "")) || HANDOFF_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, ""))) || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_memory_correct") || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_source_read" || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_set_title" || call.tool.replace(/^mcp__[^ ]+__/, "") === "hub_evidence_record" || this.opts.skip?.includes(call.tool)) return;
+    // #1053: a question and its answer are the person's and the peer's words: never memory evidence, whatever the call's paths say.
+    if (QUESTION_TOOLS.has(call.tool.replace(/^mcp__[^ ]+__/, ""))) return;
     // Anything that names a denylisted path is kept out of memory entirely, input and output alike.
     if (call.paths.some((p) => isDenied(p, this.opts.deny) || p.split(/\s+/).some((word) => isDenied(word, this.opts.deny)))) return;
     // ponytail: legacy callers without a host sourceId dedupe native ids within a summary interval; all live LocalPeer calls supply invocation identity. Require that port for other hosts.

package/src/pet/config.ts

@@ -8,7 +8,14 @@ const PALETTES: Record<string, PetPalette> = { a: "blue", b: "teal", c: "violet"
 export function petPalette(value: unknown): PetPalette | undefined {
   return typeof value === "string" ? PALETTES[value.toLowerCase()] : undefined;
 }
-export interface PetConfig { enabled: boolean; blink: boolean; bell: boolean; character?: CharacterId; size?: PetSize; glyphs?: PetGlyphs; palette?: PetPalette; notice?: string; window?: boolean }
+export const PET_WINDOW_RETIRED_NOTICE = "The floating pet window moved to acon Mini; run acon ui and open Mini.";
+/** Source compatibility only. Removed window data is never a terminal option or a settings capability. */
+export function stripLegacyPetWindow(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value) || !Object.hasOwn(value, "window")) return value;
+  const { window: _retired, ...terminal } = value as Record<string, unknown>;
+  return terminal;
+}
+export interface PetConfig { enabled: boolean; blink: boolean; bell: boolean; character?: CharacterId; size?: PetSize; glyphs?: PetGlyphs; palette?: PetPalette; notice?: string }
 /** Console-local presentation only; it merges pet.palette into config.local.json and grants no authority. */
 export function savePetPalette(cwd: string, value: string): string {
   const palette = petPalette(value);
@@ -35,34 +42,39 @@ export function savePetPalette(cwd: string, value: string): string {
 /** Console-local presentation only; this reader never writes config or grants authority. */
 export function loadPetConfig(cwd: string): PetConfig {
   let value: unknown;
-  let enabled = true;
+  let enabled = true, retiredWindow = false;
   for (const name of ["config.json", "config.local.json"]) {
     try {
       const file = JSON.parse(readFileSync(join(cwd, ".agenthub", name), "utf8"));
-      // A window-only local opt-in does not undo inherited pet:false presentation.
-      if (file.pet === false) enabled = false;
-      else if (file.pet !== undefined && !(file.pet && typeof file.pet === "object" && !Array.isArray(file.pet) && Object.keys(file.pet).length === 1 && Object.hasOwn(file.pet, "window"))) enabled = true;
-      if (file.pet !== undefined) value = value && typeof value === "object" && file.pet && typeof file.pet === "object" ? { ...value, ...file.pet } : file.pet;
+      const pet = stripLegacyPetWindow(file.pet);
+      if (pet !== file.pet) {
+        retiredWindow = true;
+        // A retired-only block contributes no terminal override, including no enablement over inherited pet:false.
+        if (pet && typeof pet === "object" && !Object.keys(pet).length) continue;
+      }
+      if (pet === false) enabled = false;
+      else if (pet !== undefined) enabled = true;
+      if (pet !== undefined) value = value && typeof value === "object" && pet && typeof pet === "object" ? { ...value, ...pet } : pet;
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
     }
   }
-  if (value === false) return { enabled: false, blink: true, bell: false };
+  const notice = (other?: string) => [retiredWindow ? PET_WINDOW_RETIRED_NOTICE : undefined, other].filter(Boolean).join(" ");
+  if (value === false) return { enabled: false, blink: true, bell: false, ...(retiredWindow ? { notice: notice() } : {}) };
   const defaults = { enabled: true, blink: true, bell: false };
-  if (value === undefined) return defaults;
-  if (!value || typeof value !== "object" || Array.isArray(value)) return { ...defaults, notice: "Unknown pet configuration; using stai line defaults." };
+  if (value === undefined) return { ...defaults, ...(retiredWindow ? { notice: notice() } : {}) };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return { ...defaults, notice: notice("Unknown pet configuration; using stai line defaults.") };
   const row = value as Record<string, unknown>;
-  const invalid = Object.keys(row).some(key => !["character", "size", "glyphs", "blink", "bell", "palette", "window"].includes(key)) ||
+  const invalid = Object.keys(row).some(key => !["character", "size", "glyphs", "blink", "bell", "palette"].includes(key)) ||
     row.character !== undefined && !characterId(row.character) || row.size !== undefined && !["line", "mini", "full"].includes(row.size as string) ||
     row.glyphs !== undefined && (typeof row.glyphs !== "string" || !["auto", "ascii", "blocks"].includes(row.glyphs)) ||
     row.palette !== undefined && !petPalette(row.palette) ||
-    row.blink !== undefined && typeof row.blink !== "boolean" || row.bell !== undefined && typeof row.bell !== "boolean" || row.window !== undefined && typeof row.window !== "boolean";
+    row.blink !== undefined && typeof row.blink !== "boolean" || row.bell !== undefined && typeof row.bell !== "boolean";
   const palette = petPalette(row.palette);
   return { enabled, blink: typeof row.blink === "boolean" ? row.blink : true, bell: typeof row.bell === "boolean" ? row.bell : false,
-    ...(typeof row.window === "boolean" ? { window: row.window } : {}),
     ...(characterId(row.character) && row.character !== "stai" ? { character: row.character } : {}),
     ...(row.size === "mini" || row.size === "full" ? { size: row.size } : {}),
     ...(row.glyphs === "ascii" || row.glyphs === "blocks" ? { glyphs: row.glyphs } : {}),
     ...(palette && palette !== "teal" ? { palette } : {}),
-    ...(invalid ? { notice: "Unknown pet option; using stai line defaults for that option." } : {}) };
+    ...(invalid || retiredWindow ? { notice: notice(invalid ? "Unknown pet option; using stai line defaults for that option." : undefined) } : {}) };
 }

package/src/pi/extension.ts

@@ -23,6 +23,8 @@ let shellSeq = 0;
 let forcedFailure = "";
 let turnGeneration = 0;
 let sessionId = "";
+let titleRevision = 0;
+let titleEpoch = "";
 let pendingPromptId: string | undefined;
 let activePromptId: string | undefined;
 let settlement: Promise<void> | undefined;
@@ -93,11 +95,36 @@ async function poll(pi: ExtensionAPI): Promise<void> {
             await post("/ack", { id: command.id, ok: false, error: "Pi prompt insertion did not synchronously claim a native turn", refusal: { kind: "prompt_uncertain", promptId: command.id, sessionId, generation: turnGeneration } });
             continue;
           }
+        } else if (command.type === "set_session_title") {
+          const refuse = (cause: string, error: string) => post("/ack", { id: command.id, ok: true, result: { ok: false, reason: "invalid", cause, error, sessionId, titleEpoch, titleRevision } });
+          const nativeId = runtimeCtx?.sessionManager?.getHeader?.()?.id;
+          if (command.sessionId !== sessionId || nativeId !== sessionId || command.titleEpoch !== undefined && command.titleEpoch !== titleEpoch) {
+            await refuse("session", "Pi native session changed before the title write; check ahub status and reconnect the current session before retrying."); continue;
+          }
+          if (command.generation !== turnGeneration) {
+            await refuse("generation", "Pi native turn changed before the title write; wait for the current turn and check ahub status before retrying."); continue;
+          }
+          if (typeof command.title !== "string" || !command.title.trim() || [...command.title].length > 80 || typeof command.onlyIfUnnamed !== "boolean") {
+            await refuse("arguments", "Pi title command arguments are invalid; use a 1-80 character normalized title and a conditional-write flag before retrying."); continue;
+          }
+          if (typeof pi.getSessionName !== "function" || typeof pi.setSessionName !== "function") {
+            await refuse("native_unavailable", "Pi native title API is unavailable; restart Pi with the supported hub extension and check ahub status before retrying."); continue;
+          }
+          // The native read and synchronous write share one JS turn: a manual rename always wins against the agent.
+          const before = pi.getSessionName() ?? "";
+          if (command.onlyIfUnnamed && before) {
+            await post("/ack", { id: command.id, ok: true, result: { ok: false, reason: "already_named", error: "This session already has a title; keep it or ask the person to rename it with ahub title.", sessionId, titleEpoch, titleRevision, sessionName: before } }); continue;
+          }
+          pi.setSessionName(command.title);
+          const sessionName = pi.getSessionName() ?? "";
+          await post("/ack", { id: command.id, ok: true, result: { ok: sessionName === command.title, ...(sessionName === command.title ? {} : { reason: "invalid", cause: "native_readback", mayHaveApplied: true, error: "Pi native title readback did not confirm the write; the title may have been applied; check ahub status before retrying." }), sessionId, titleEpoch, titleRevision, sessionName } });
+          continue;
         } else if (command.type === "get_session_state") {
           const entries = runtimeCtx.sessionManager.getEntries();
           await post("/ack", { id: command.id, ok: true, result: {
             sessionId: runtimeCtx.sessionManager.getHeader()?.id,
             sessionFile: runtimeCtx.sessionManager.getSessionFile(),
+            ...(typeof pi.getSessionName === "function" ? { sessionName: pi.getSessionName() ?? "", titleEpoch, titleRevision } : {}),
             idle: runtimeCtx.isIdle() === true,
             empty: entries.every((entry: any) => ["model_change", "thinking_level_change"].includes(entry.type)),
           } });
@@ -120,7 +147,14 @@ async function poll(pi: ExtensionAPI): Promise<void> {
           }
         }
         await post("/ack", { id: command.id, ok: true });
-      } catch (error) { if (pendingPromptId === command.id) pendingPromptId = undefined; await post("/ack", { id: command.id, ok: false, error: (error as Error).message }); }
+      } catch (error) {
+        if (command.type === "set_session_title") {
+          await post("/ack", { id: command.id, ok: true, result: { ok: false, reason: "invalid", cause: "native_failed", mayHaveApplied: true, error: "Pi native title API failed without confirming the write; the title may have been applied; check ahub status before retrying.", sessionId, titleEpoch, titleRevision } });
+          continue;
+        }
+        if (pendingPromptId === command.id) pendingPromptId = undefined;
+        await post("/ack", { id: command.id, ok: false, error: (error as Error).message });
+      }
     } catch { await new Promise((resolve) => setTimeout(resolve, 250)); }
   }
 }
@@ -142,8 +176,9 @@ export default function(pi: ExtensionAPI): void {
     shutdown = ctx.shutdown;
     const state = ctx.sessionManager.getHeader();
     sessionId = String(state?.id ?? "");
+    titleRevision = 0; titleEpoch = crypto.randomUUID();
     try {
-      const claimed = await post("/event", { type: "session_start", ownerToken, pid: process.pid, signature: processSignature(process.pid), sessionId: state?.id, sessionFile: ctx.sessionManager.getSessionFile(), approvalTurnAbort: typeof ctx.abort === "function", fencedPrompt: true });
+      const claimed = await post("/event", { type: "session_start", ownerToken, pid: process.pid, signature: processSignature(process.pid), ...(typeof pi.getSessionName === "function" ? { sessionName: pi.getSessionName() ?? "", titleEpoch, titleRevision } : {}), sessionId: state?.id, sessionFile: ctx.sessionManager.getSessionFile(), approvalTurnAbort: typeof ctx.abort === "function", fencedPrompt: true });
       if (claimed?.ok === false) { ctx.shutdown?.(); return; }
     } catch (error) { ctx.shutdown?.(); throw error; }
     if (!pollStarted) { pollStarted = true; void poll(pi); }
@@ -168,8 +203,13 @@ export default function(pi: ExtensionAPI): void {
     lastActivity = now;
     try { await post("/event", { type: "activity" }); } catch { /* shutdown owns bridge cleanup */ }
   });
+  pi.on("session_info_changed", async () => {
+    if (runtimeCtx?.sessionManager?.getHeader?.()?.id !== sessionId || typeof pi.getSessionName !== "function") return;
+    try { await post("/event", { type: "session_title", sessionId, titleEpoch, titleRevision: ++titleRevision, sessionName: pi.getSessionName() ?? "" }); }
+    catch { /* title observation must not disrupt the native session */ }
+  });
   // Native retries/continuations emit more starts before the one logical agent_settled.
-  pi.on("agent_start", async () => { toolSteps = 0; forcedFailure = ""; turnGeneration++; activePromptId = pendingPromptId ?? activePromptId; pendingPromptId = undefined; await post("/event", { type: "agent_start", generation: turnGeneration, ...(activePromptId ? { promptId: activePromptId } : {}) }); });
+  pi.on("agent_start", async () => { toolSteps = 0; forcedFailure = ""; turnGeneration++; activePromptId = pendingPromptId ?? activePromptId; pendingPromptId = undefined; await post("/event", { type: "agent_start", sessionId, ...(typeof pi.getSessionName === "function" ? { sessionName: pi.getSessionName() ?? "", titleEpoch, titleRevision } : {}), generation: turnGeneration, ...(activePromptId ? { promptId: activePromptId } : {}) }); });
   pi.on("model_select", async (_event: any, ctx: any) => { if (ctx.model?.provider && ctx.model.provider !== "agent-hub-local") ctx.shutdown?.(); });
   pi.on("before_agent_start", async (event: any, ctx: any) => {
     if (ctx.model?.provider && ctx.model.provider !== "agent-hub-local") { ctx.abort?.(); return { systemPrompt: event.systemPrompt }; }