@staix/agent-hub 0.27.0 → 0.28.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/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.