@staix/agent-hub 0.27.0 → 0.29.0

package/src/hub/terminal-open.ts

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { personEnv } from "./child-process.ts";
-import { openStartTerminal, orcaExecutable, shellQuote, startTerminalWorktree, type CommandRunner } from "../cli/terminal-recovery.ts";
+import { openStartTerminal, orcaExecutable, resolveStartTerminalWorktree, shellQuote, startTerminalCandidate, type CommandRunner } from "../cli/terminal-recovery.ts";
 
 /** #269: where a terminal for a hub-made start comes from, or why there is none. */
 export type TerminalOpened = { ok: true; via: string } | { ok: false; why: string; detail?: string };
@@ -18,14 +18,15 @@ const PLACEHOLDER = /\{(command|title|cwd)\}/g;
 
 /**
  * The providers, in order: the machine-local `terminal.open` command template, then Orca (the path recovery uses)
- * when this project has an Orca worktree. `run` replaces the Orca CLI in tests.
+ * when Orca is in play for this project. `available` only says Orca could be used; `open` asks Orca for the worktree
+ * whose root is this project's root and refuses when there is none (#1089). `run` replaces the Orca CLI in tests.
  */
 export function terminalOpener(opts: { template: string[]; cwd: string; stateDir: string; env?: NodeJS.ProcessEnv; run?: CommandRunner }): TerminalOpener {
   const env = opts.env ?? process.env;
-  const worktree = () => startTerminalWorktree(opts.cwd, opts.stateDir, env);
+  const orcaInPlay = () => startTerminalCandidate(opts.cwd, opts.stateDir, env);
   const available = (): TerminalOpened => {
     if (opts.template.length) return { ok: true, via: "terminal.open" };
-    if (!worktree()) return { ok: false, why: "no terminal.open command is configured and this project has no Orca worktree on record" };
+    if (!orcaInPlay()) return { ok: false, why: "no terminal.open command is configured and this project has no Orca worktree on record" };
     if (!opts.run && !Bun.which(orcaExecutable())) return { ok: false, why: `the ${orcaExecutable()} command is not on PATH` };
     return { ok: true, via: "orca" };
   };
@@ -38,7 +39,11 @@ export function terminalOpener(opts: { template: string[]; cwd: string; stateDir
       const command = argv.map(shellQuote).join(" ");
       try {
         if (can.via === "orca") {
-          await openStartTerminal(worktree()!, command, title, opts.run ? { runner: opts.run } : undefined);
+          // The worktree comes from Orca by this project's root, never from the environment of whatever terminal started this hub (#1089).
+          const orca = opts.run ? { runner: opts.run } : undefined;
+          const target = await resolveStartTerminalWorktree(opts.cwd, orca);
+          if (!target.ok) return target;
+          await openStartTerminal(target.worktreeId, command, title, orca);
           return can;
         }
         // One pass with a function: a placeholder inside a substituted value (a project path that contains "{cwd}")

package/src/hub/tool-request.ts

@@ -0,0 +1,131 @@
+import { createHash, randomUUID } from "node:crypto";
+import { canonical } from "./capabilities.ts";
+
+export const TOOL_WRITE_FEATURE = "tool_write_idempotency";
+const RETENTION_MS = 15 * 60 * 1000;
+const MAX_ENTRIES = 512;
+const MAX_REPLY_BYTES = 64 * 1024;
+const MAX_PAYLOAD_BYTES = 1024 * 1024;
+const MAX_FUTURE_MS = 30_000;
+type Reply = Record<string, unknown>;
+
+/** Writes with uncertain transport outcomes; delivery completion uses its journal rather than the replay registry. */
+export function toolWriteOperation(msg: Record<string, unknown>): "hub_task_propose" | "hub_review" | "hub_delivery_done" | undefined {
+  if (msg.t === "delivery_complete") return "hub_delivery_done";
+  if (msg.t === "task") {
+    // Match the control dispatcher's legacy operation coercion, so accepted writes cannot bypass replay protection.
+    let operation: string;
+    try { operation = String(msg.op); } catch { return undefined; }
+    if (operation === "hub_task_propose" || operation === "hub_review") return operation;
+  }
+  return undefined;
+}
+
+export function newToolRequestId(instanceId: string, now = Date.now()): string {
+  if (!/^[A-Za-z0-9._-]{1,128}$/.test(instanceId) || !Number.isSafeInteger(now) || now < 1) throw new Error("tool request identity is unavailable");
+  return `v1/${instanceId}/${now}/${randomUUID()}`;
+}
+
+function settlingRead(msg: Record<string, unknown>): { read: string; absent: string } {
+  const args = msg.args && typeof msg.args === "object" && !Array.isArray(msg.args) ? msg.args as Record<string, unknown> : {};
+  const id = typeof args.id === "number" ? args.id : typeof args.id === "string" && /^\s*\d+\s*$/.test(args.id) ? Number(args.id) : undefined;
+  const delivery = typeof msg.deliveryId === "string" && /^(?:[a-f0-9]{32}|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$/.test(msg.deliveryId) ? msg.deliveryId : "<delivery-id>";
+  if (toolWriteOperation(msg) === "hub_delivery_done") return { read: `ahub queue show ${delivery} (person or conductor)`, absent: "completion is absent" };
+  if (toolWriteOperation(msg) === "hub_review" && Number.isSafeInteger(id) && id! > 0) return { read: `hub_task_show {id: ${id}}`, absent: "this verdict is absent" };
+  return { read: "hub_task_list (then hub_task_show for the matching task)", absent: "the task is absent" };
+}
+function safeRequestId(requestId: unknown): string | undefined {
+  return typeof requestId === "string" && requestId.length <= 256 && !/[\p{Cc}\p{Cf}]/u.test(requestId) ? requestId : undefined;
+}
+export function toolWriteUnknownReply(msg: Record<string, unknown>, requestId?: string, cause?: string): Reply {
+  const token = safeRequestId(requestId), settlement = settlingRead(msg);
+  const replay = token && toolWriteOperation(msg) !== "hub_delivery_done" ? `, reusing request_id ${JSON.stringify(token)}` : "";
+  return { ok: false, outcome: "unknown", ...(token ? { requestId: token } : {}),
+    error: `Write outcome unknown${cause ? `: ${cause}` : ". The hub may have applied the write"}. Read ${settlement.read}; call again only if ${settlement.absent}${replay}.` };
+}
+export function toolWriteRefusedReply(msg: Record<string, unknown>, requestId: unknown, cause: string): Reply {
+  const token = safeRequestId(requestId);
+  return { ok: false, outcome: "refused", ...(token ? { requestId: token } : {}),
+    error: `Write request refused: ${cause}. This attempt did not run. Read ${settlingRead(msg).read} before another write.` };
+}
+
+interface Entry { bucket: string; scope: string; payload: string; issuedAt: number; settled: boolean; reply: Promise<Reply> }
+interface Request { id: unknown; scope: string; bucket?: string; payload: unknown; current: (reply?: Reply) => boolean }
+
+/** One daemon epoch. Expired ids are rejected, not forgotten and reapplied. */
+export class ToolWriteRegistry {
+  private readonly entries = new Map<string, Entry>();
+  private watermark = 0;
+  private readonly clock: () => number;
+  private readonly maxEntries: number;
+  private readonly retentionMs: number;
+  private readonly maxReplyBytes: number;
+  constructor(private readonly instanceId: string, options: { now?: () => number; maxEntries?: number; retentionMs?: number; maxReplyBytes?: number } = {}) {
+    this.clock = options.now ?? Date.now;
+    this.maxEntries = options.maxEntries ?? MAX_ENTRIES;
+    this.retentionMs = options.retentionMs ?? RETENTION_MS;
+    this.maxReplyBytes = options.maxReplyBytes ?? MAX_REPLY_BYTES;
+    if (!/^[A-Za-z0-9._-]{1,128}$/.test(instanceId) || ![this.maxEntries, this.retentionMs, this.maxReplyBytes].every(value => Number.isSafeInteger(value) && value > 0)) throw new Error("invalid tool replay registry bounds");
+  }
+
+  async run(request: Request, work: () => Promise<Reply>): Promise<Reply> {
+    const refuse = (cause: string) => toolWriteRefusedReply(this.message(request.payload), request.id, cause);
+    const unavailable = (cause: string) => toolWriteUnknownReply(this.message(request.payload), typeof request.id === "string" ? request.id : undefined, cause);
+    const current = (reply?: Reply) => { try { return request.current(reply === undefined ? undefined : structuredClone(reply)) === true; } catch { return false; } };
+    if (!current()) return refuse("current caller authority or privacy is unavailable");
+    const observed = this.clock();
+    if (!Number.isSafeInteger(observed) || observed < 1) return refuse("the replay clock is unavailable");
+    const now = this.watermark = Math.max(this.watermark, observed);
+    const parts = typeof request.id === "string" && request.id.length <= 256 ? request.id.split("/") : [];
+    const issuedAt = Number(parts[2]);
+    if (parts.length !== 4 || parts[0] !== "v1" || parts[1] !== this.instanceId || !/^[1-9][0-9]{0,15}$/.test(parts[2] ?? "")
+      || !Number.isSafeInteger(issuedAt) || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(parts[3] ?? "")) return refuse("the request ID is invalid or belongs to another daemon instance; inspect its original outcome");
+    let payload: string, scope: string, bucket: string;
+    try {
+      if (typeof request.scope !== "string" || request.scope.length > 4096) throw new Error("invalid scope");
+      const bucketKey = request.bucket ?? request.scope;
+      if (typeof bucketKey !== "string" || bucketKey.length > 4096) throw new Error("invalid bucket");
+      scope = createHash("sha256").update(request.scope).digest("hex");
+      bucket = createHash("sha256").update(bucketKey).digest("hex");
+      const encoded = JSON.stringify(request.payload);
+      if (!encoded || Buffer.byteLength(encoded) > MAX_PAYLOAD_BYTES) throw new Error("request too large");
+      const value: unknown = JSON.parse(encoded);
+      const stack = [{ value, depth: 0 }]; let nodes = 0;
+      while (stack.length) {
+        const row = stack.pop()!;
+        if (++nodes > 20_000 || row.depth > 32) throw new Error("request too complex");
+        if (row.value && typeof row.value === "object") for (const child of Object.values(row.value)) stack.push({ value: child, depth: row.depth + 1 });
+      }
+      payload = createHash("sha256").update(canonical(value)).digest("hex");
+    } catch { return refuse("the request is too large or malformed for replay protection"); }
+    // Pending writes never age out: losing their key could apply an unfinished write twice.
+    for (const [id, entry] of this.entries) if (entry.settled && now - entry.issuedAt >= this.retentionMs) this.entries.delete(id);
+    const existing = this.entries.get(request.id as string);
+    if (existing) {
+      if (existing.scope !== scope || existing.bucket !== bucket || existing.payload !== payload) return refuse("the request ID was already used by another authority or for different arguments");
+      const reply = await existing.reply;
+      return current(reply) ? structuredClone(reply) : unavailable("caller authority or privacy changed before replay");
+    }
+    if (now - issuedAt >= this.retentionMs || issuedAt > now + MAX_FUTURE_MS) return refuse("the request ID is expired or its timestamp is outside the replay window; inspect its original outcome");
+    // ponytail: 512 calls per actor/scope per 15 min and 64 KiB per reply; a durable outcome ledger is the upgrade path for higher sustained write volume.
+    if ([...this.entries.values()].filter(entry => entry.bucket === bucket).length >= this.maxEntries) return refuse("this actor's replay window is full; inspect its outstanding writes and wait for that window to drain");
+    const entry: Entry = { bucket, scope, payload, issuedAt, settled: false, reply: Promise.resolve({}) };
+    this.entries.set(request.id as string, entry);
+    entry.reply = Promise.resolve().then(async () => {
+      if (!current()) return refuse("caller authority or privacy changed before execution");
+      try {
+        const result = await work();
+        const { rid: _rid, ...body } = result;
+        const encoded = JSON.stringify({ ...body, requestId: request.id });
+        if (Buffer.byteLength(encoded) > this.maxReplyBytes) return unavailable("the write result exceeds the bounded replay record; inspect the write directly");
+        return JSON.parse(encoded) as Reply;
+      } catch { return unavailable("the write raised an unexpected failure and may already have applied"); }
+    }).finally(() => { entry.settled = true; });
+    const reply = await entry.reply;
+    return current(reply) ? structuredClone(reply) : unavailable("caller authority or privacy changed before the result");
+  }
+
+  private message(payload: unknown): Record<string, unknown> {
+    return payload && typeof payload === "object" && !Array.isArray(payload) ? payload as Record<string, unknown> : {};
+  }
+}

package/src/local/deny.ts

@@ -77,6 +77,54 @@ const hooksUnder = (parent: string): string => {
   return depth > MAX_ANCHOR_DEPTH ? `^.*/${hfsFoldedName("hooks")}(/|$)` : `^${"/[^/]+".repeat(depth)}/${hfsFoldedName("hooks")}(/|$)`;
 };
 
+/**
+ * #1123: a sandboxed command may not move what a branch, HEAD or a linked worktree points at. `refs/**` (branches, tags, `refs/stash`), `packed-refs*`, `HEAD*` (its lock too) and
+ * `worktrees/**` (a linked worktree's admin dir: its HEAD, index, logs) are refused directly under every plain `.git` and under each external git dir (the common dir and a linked
+ * worktree's own, whatever they are named). The hub's own git runs outside the sandbox and is unaffected, so #1115's hub commit still lands.
+ *
+ * Every name must sit DIRECTLY under its git dir. An unanchored `refs` or `worktrees` filter would also match an ANCESTOR of the project with that name, and a project under
+ * `~/worktrees/` would lose every `.git` write (the #520 `hooks` lesson). So each rule is adjacent by construction: one literal for `.git` + a short name, or, for the long names
+ * (`worktrees`, `packed-refs`, where `.git` + name would pass the 1024-byte literal limit), a front half and a back half that must both match, or a depth anchor for an external dir.
+ * A submodule's git dir (`.git/modules/<name>`, nested ones, and `.git/worktrees/<wt>/modules/<name>` for a linked worktree) is covered the same way (`subDirs`, the discovered
+ * ones: a git dir that is not discovered is refused whole by the #518/#520 rules), per the person's "deny .git writes" decision: nothing is listed as a residual.
+ */
+const refDepth = (d: string): number => d.split("/").filter(Boolean).length;
+/**
+ * `^(/[^/]+){depth}/<name>(/|$)`: `name` as the entry directly under `d`, the depth written out because seatbelt ignores `{n}`. The folded names cost (measured, bytes of regex): `refs` 334,
+ * `worktrees` 669, so past the depth where the path plus the name would near 1024 it falls back to the unanchored name, which over-refuses only under an ancestor with that name and
+ * never under-protects.
+ */
+const refUnder = (d: string, name: string): string => {
+  const depth = refDepth(d), cost = Buffer.byteLength(hfsFoldedName(name)) + depth * 6 + 8;
+  return cost > 1000 ? `^.*/${hfsFoldedName(name)}(/|$)` : `^${"/[^/]+".repeat(depth)}/${hfsFoldedName(name)}(/|$)`;
+};
+function gitRefRules(gitDirs: string[], subDirs: string[] = []): string[] {
+  const git = hfsFoldedName(".git");
+  const re = (s: string) => `(regex ${sbplString(s)})`;
+  const name = (n: string) => hfsFoldedName(n);
+  // A linked worktree's own submodule git dirs (`worktrees/<wt>/modules/**`) are governed by the #518/#520 rules, not these.
+  const plainSub = `(require-not ${re(`^.*/${git}/worktrees/[^/]+/modules(/|$)`)})`;
+  const plain = [
+    // `.git` (335 bytes) + `HEAD` or `refs` (334) fit one literal: adjacent by construction. `HEAD.lock` goes with `HEAD`.
+    re(`^.*/${git}/${name("HEAD")}(\\.lock)?$`),
+    re(`^.*/${git}/${name("refs")}(/|$)`),
+    // `.git` + `packed-refs` (803) and `.git` + `worktrees` (669) do not fit one literal. The front literal pins the start of the name right under a `.git`, and for `worktrees` the
+    // back literal pins its end; `packed` alone covers `packed-refs` and its lock/new files, which is the intent.
+    re(`^.*/${git}/${name("packed")}`),
+    `(require-all ${re(`^.*/${git}/${name("work")}`)} ${re(`^.*${name("trees")}(/|$)`)} ${plainSub})`,
+  ];
+  const external = [...gitDirs, ...subDirs].flatMap((d) => {
+    const own = sbplString(d), direct = re(`^${sbplEscape(d)}/[^/]+$`);
+    return [
+      `(require-all ${direct} ${re(`^.*/${name("HEAD")}(\\.lock)?$`)})`,
+      `(require-all ${direct} ${re(`^.*/${name("packed")}`)})`,
+      `(require-all (subpath ${own}) ${re(refUnder(d, "refs"))})`,
+      `(require-all (subpath ${own}) ${re(refUnder(d, "worktrees"))} (require-not ${re(`^${sbplEscape(d)}/worktrees/[^/]+/modules(/|$)`)}))`,
+    ];
+  });
+  return [...plain, ...external];
+}
+
 export function hubWriteRegexes(root: string, gitDirs: string[] = [], moduleGit: readonly { root: string; entries: string[]; dirs?: string[] }[] = [], worktreesRoot?: string): string[] {
   const git = hfsFoldedName(".git");
   const re = (s: string) => `(regex ${sbplString(s)})`;
@@ -157,6 +205,7 @@ export function hubWriteRegexes(root: string, gitDirs: string[] = [], moduleGit:
     `(require-all ${re(`^.*/${git}/[^/]+$`)} ${CONFIG_WORKTREE_NAME.map(re).join(" ")})`,
     re(`^.*/${git}/${hfsFoldedName("hooks")}(/|$)`),
     `(require-all ${re(`^.*/${git}/.*$`)} ${re(`^.*/${hfsFoldedName("commondir")}$`)})`,
+    ...gitRefRules(gitDirs, allDirs),
     ...modules,
     ...siblings,
     ...external,

package/src/local/tools.ts

@@ -117,7 +117,7 @@ export const TOOL_SCHEMAS = [
   fn("write", "Create or overwrite a file inside the project. Needs the user's approval.", { path: str, content: str }, ["path", "content"]),
   fn("edit", "Replace one exact, unique occurrence of `old` with `new` in a file. Needs the user's approval.", { path: str, old: str, new: str }, ["path", "old", "new"]),
   fn("bash", "Run a shell command in the project directory, sandboxed: no writes outside the project, no credential reads, no network unless the hub enables it. Follows hub permission policy: proven bounded read-only commands may run automatically in ask-when-needed; other commands ask.", { command: str, timeout_s: { type: "integer", minimum: 1, maximum: 600 } }, ["command"]),
-  fn("git", "Run git in the project. status, diff, log, show, ls-files, blame, rev-parse run freely; add, commit, restore, checkout, switch, stash, mv, rm, branch, merge, rebase, cherry-pick, revert, tag need approval; everything else (push, fetch, config, remote ...) is refused.", { args: { type: "array", items: str, minItems: 1 } }, ["args"]),
+  fn("git", "Run git in the project. status, diff, log, show, ls-files, blame, rev-parse run freely; add, commit, restore, checkout, switch, stash, mv, rm, branch, merge, rebase, cherry-pick, revert, tag need approval; everything else (push, fetch, config, remote ...) is refused. The sandbox does not let you move a branch, tag or HEAD anywhere (commit, branch, tag, stash, switch, merge, rebase and reset fail, submodules included), nor stage with add inside a linked worktree: edit files, and the hub commits and pushes them when you call hub_task_done.", { args: { type: "array", items: str, minItems: 1 } }, ["args"]),
   fn("hub_send", "Send a message to the other agents now, before your turn ends. Conclusions only. Your final answer is shared anyway; use this for something that cannot wait.", { text: str, to: { type: "array", items: str } }, ["text"]),
 ];
 
@@ -235,7 +235,9 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         // Sandboxed like bash: flags such as --output or an editor cannot write outside the project or reach the network.
         const res = await sandboxedExec(["git", "--no-pager", ...args], { cwd: ctx.cwd, profile: ctx.sandboxProfile, readOnlyData: !!ctx.readOnly?.length, ...(ctx.sandboxEnv ? { env: ctx.sandboxEnv } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
         try { ctx.onProcessExit?.(res.code); } catch { /* optional status observer never changes a tool result */ }
-        return `${res.output}\n(exit ${res.code})`;
+        // #1123: the profile refuses writes to refs, HEAD, packed-refs and a linked worktree's admin dir, so a commit, branch, tag, stash or switch cannot succeed here. Say so, with the next step.
+        const refused = res.code !== 0 && /(?:\.git\/(?:refs|HEAD|packed-refs|worktrees)\b|cannot lock ref|index\.lock)[^\n]*(?:Operation not permitted|not permitted)/i.test(res.output);
+        return `${res.output}${refused ? "\nnote: the sandbox does not let you move a branch, tag or HEAD, or stage inside a linked worktree (#1123). Leave your edits in the working tree and finish with hub_task_done. For implementation work the hub stages, commits and pushes them for you; for work that changes no files, or a private task, there is nothing for it to commit, so do not try to commit it yourself." : ""}\n(exit ${res.code})`;
       }
       case "doc_read": {
         if (!ctx.docRead) return "error: doc_read is not enabled for this project (local.doc_read in .agenthub/config.local.json)";

package/src/memory/brief.ts

@@ -1,4 +1,5 @@
 import { buildIntentBrief, type IntentBriefOptions, type IntentBriefSource } from "@staix/agent-mem";
+import { controlWriteSpan } from "../hub/control-write-trace.ts";
 import type { PeerId } from "../hub/envelope.ts";
 import type { MemoryClient } from "./client.ts";
 
@@ -70,6 +71,10 @@ export class Briefs {
   ) {}
 
   async forTask(peer: PeerId, task: BriefTask, priority: readonly NativeItem[] = []): Promise<string | undefined> {
+    return controlWriteSpan("memory", () => this.forTaskBody(peer, task, priority));
+  }
+
+  private async forTaskBody(peer: PeerId, task: BriefTask, priority: readonly NativeItem[]): Promise<string | undefined> {
     // A brief snapshots its configured cap once, before either optional source is selected.
     const maximum = typeof this.maxItems === "function" ? this.maxItems() : this.maxItems;
     let corpusRevision: string | undefined;

package/src/memory/client.ts

@@ -1,5 +1,6 @@
 import packageJson from "../../package.json";
 import { createHash } from "node:crypto";
+import { controlWriteSpan } from "../hub/control-write-trace.ts";
 import { CaptureStore, SearchIndex, looksSecret, memoryBase, readCaptureConfig, type CaptureOptions as StoreCaptureOptions, type MemoryStore, type CandidateStore, type View } from "@staix/agent-mem";
 
 export interface CaptureEvent {
@@ -54,8 +55,10 @@ export class MemoryClient {
   }
   close(): void { this.closed = true; this.releaseCapture(); }
   private run<T>(work: (o: MemoryClientOptions) => T): T | undefined {
-    try { if (!this.options || this.closed) return undefined; this.options.check(); return work(this.options); }
-    catch { this.releaseCapture(); this.options?.log?.("amem operation unavailable"); return undefined; }
+    return controlWriteSpan("memory", () => {
+      try { if (!this.options || this.closed) return undefined; this.options.check(); return work(this.options); }
+      catch { this.releaseCapture(); this.options?.log?.("amem operation unavailable"); return undefined; }
+    });
   }
   private rows(o: MemoryClientOptions): View[] {
     const store = o.store;

package/src/ui/office-model.ts

@@ -163,6 +163,11 @@ export interface OfficeScene {
   links: OfficeLink[];
   /** Sticky desk assignment; pass the whole scene back as `previous` so slots survive churn. */
   slots: Record<string, number>;
+  /**
+   * Public card data for tasks a desk bubble names that the rendering limits (8 per room, 2 on an overfull desk) left out of
+   * every `cards` list. Zero geometry: the dashboard never draws it, acon Space maps it. Same allowlisted fields as `cards`.
+   */
+  attributedCards: OfficeCard[];
   /** Task id -> placement ("room:todo" | "room:work" | "room:review" | "shelf:done" | "desk:<peer>" | "counted:unknown"). */
   placed: Record<string, string>;
   arcs: OfficeArc[];
@@ -359,6 +364,17 @@ export function officeModel(snapshot: OfficeSnapshotInput, previous: OfficeScene
       : state === "in_progress" || state === "changes_requested" ? (owner && shownSet.has(owner) ? `desk:${owner}` : "room:work")
       : state === "backlog" ? "counted:backlog" : "counted:unknown";
   }
+  // A bubble's attributed task may sit past the rendering cut; keep its public card so a consumer that draws more cards than the page can.
+  const drawn = new Set<number>([...desks.flatMap((desk) => desk.cards), ...rooms.flatMap((room) => room.cards)].map((entry) => entry.id));
+  const taskById = new Map<number, OfficeTaskInput>(tasks.map((task) => [task.id, task]));
+  const attributedCards: OfficeCard[] = [];
+  for (const desk of desks) {
+    const id = /^#(\d+) /.exec(desk.bubble)?.[1];
+    const task = id === undefined ? undefined : taskById.get(Number(id));
+    if (!task || drawn.has(task.id)) continue;
+    drawn.add(task.id);
+    attributedCards.push(card(task, 0, 0, 0, 0));
+  }
   const transitions: OfficeTransitions = { desksAdded: [], desksRemoved: [], cardsMoved: [] };
   if (previous) {
     const prevPlaced = previous.placed ?? {};
@@ -440,7 +456,7 @@ export function officeModel(snapshot: OfficeSnapshotInput, previous: OfficeScene
     cols,
     width: Math.max(desksWidth, ...rooms.map(room => room.x + room.w), 1),
     height: Math.max(desksBottom, ...rooms.map(room => room.y + room.h), 1),
-    desks, extraPeers, rooms, counts, transitions, slots, placed,
+    desks, extraPeers, rooms, counts, transitions, slots, placed, attributedCards,
     links,
     arcs: keptArcs, alerts: keptAlerts, latched, settle, at, eventTime, lastSeq,
   };

package/src/ui/office-space.ts

@@ -70,7 +70,7 @@ export function officeSpace(model: OfficeScene, project: { id: string; label?: s
   };
   const cards: SpaceScene["cards"] = [];
   const seen = new Set<number>();
-  for (const card of [...model.desks.flatMap((d) => d.cards), ...model.rooms.flatMap((r) => r.cards)]) {
+  for (const card of [...model.desks.flatMap((d) => d.cards), ...model.rooms.flatMap((r) => r.cards), ...(model.attributedCards ?? [])]) {
     if (seen.has(card.id)) continue;
     seen.add(card.id);
     const zone = zoneOf(model.placed[String(card.id)]);

package/templates/config.json

@@ -32,6 +32,7 @@
   "tasks": { "release_after_min": 30 },
   "checks": { "timeout_s": 600 },
   "snapshots": { "enabled": true, "keep": 20 },
+  "specs": { "enabled": true, "review": "report", "roots": [], "stamps_file": "" },
   "review": { "adaptive": false, "min_reviews": 5 },
   "recovery": { "auto_resume_after_crash": false },
   "capabilities": {},

package/templates/profiles/dev.json

@@ -22,6 +22,7 @@
   "review_checklist": [
     "Map the changed signatures and call sites to {target}, and name each one that does not match.",
     "{check}",
+    "Name each new or changed error, refusal or failure message that lacks its cause (what failed and why) or its next step (the command, setting or target that fixes it); where secrets, ids or paths must stay out, it names the cause class and how to check it.",
     "List what is unmet in hub_review's unmet, one item each."
   ]
 }

package/templates/profiles/general.json

@@ -26,6 +26,7 @@
   "review_checklist": [
     "Assess the deliverables against {target}, and name each one that does not match.",
     "{check}",
+    "Name each new or changed error, refusal or failure message that lacks its cause (what failed and why) or its next step (the command, setting or target that fixes it); where secrets, ids or paths must stay out, it names the cause class and how to check it.",
     "List what is unmet in hub_review's unmet, one item each."
   ]
 }

package/templates/profiles/research.json

@@ -57,6 +57,7 @@
   "review_checklist": [
     "Assess scope, provenance and unsupported claims against {target}, and name each one that does not match.",
     "{check}",
+    "Name each new or changed error, refusal or failure message that lacks its cause (what failed and why) or its next step (the command, setting or target that fixes it); where secrets, ids or paths must stay out, it names the cause class and how to check it.",
     "List what is unmet in hub_review's unmet, one item each."
   ]
 }

package/templates/profiles/writing.json

@@ -28,6 +28,7 @@
   "review_checklist": [
     "Assess scope, provenance and unsupported claims against {target}, and name each one that does not match.",
     "{check}",
+    "Name each new or changed error, refusal or failure message that lacks its cause (what failed and why) or its next step (the command, setting or target that fixes it); where secrets, ids or paths must stay out, it names the cause class and how to check it.",
     "List what is unmet in hub_review's unmet, one item each."
   ]
 }

package/templates/specs.block.md

@@ -0,0 +1,5 @@
+## Design specs
+
+- Design specs are Markdown files with `id` and `type` frontmatter whose `paths` name the files they govern. The hub names the specs covering a task when you propose or accept it, and `hub_specs` answers on request.
+- Read a covering spec when your change touches a boundary, contract, invariant or decision it states. Follow it, or reconcile the contradiction; never silently diverge.
+- When your change alters one of those, update the owning spec in the same change. Never edit `verified-against`; a person stamps it.