@staix/agent-hub 0.12.34 → 0.12.36

package/src/hub/snapshots.ts

@@ -216,6 +216,7 @@ export class Turns {
     // ponytail: rows of finished tasks stay (a few per file per task); prune by task state if hub.db ever grows.
     this.db.run("CREATE TABLE IF NOT EXISTS touches (task INTEGER NOT NULL, peer TEXT NOT NULL, path TEXT NOT NULL, at INTEGER NOT NULL, PRIMARY KEY (task, peer, path))");
     this.db.run("CREATE INDEX IF NOT EXISTS touches_path ON touches (path)"); // the PreToolUse hook looks up one path
+    this.db.run("CREATE TABLE IF NOT EXISTS turn_workspaces (turn TEXT PRIMARY KEY, root TEXT NOT NULL, start_tree TEXT, end_tree TEXT, changed TEXT NOT NULL DEFAULT '[]')");
     this.db.run("CREATE TABLE IF NOT EXISTS task_snapshots (task INTEGER NOT NULL, proposed_at INTEGER NOT NULL, start_tree TEXT, PRIMARY KEY (task, proposed_at))");
   }
   /** A proposal's original project snapshot; task ids may be reused after reset. Never repair a missing baseline later. */
@@ -231,27 +232,55 @@ export class Turns {
       throw error;
     }
   }
-  begin(id: string, peer: string, startTree: string | undefined): void {
-    this.db.query("INSERT OR REPLACE INTO turns (id, peer, started, start_tree) VALUES (?, ?, ?, ?)").run(id, peer, Date.now(), startTree ?? null);
+  begin(id: string, peer: string, startTree: string | undefined, workspace?: string): void {
+    this.db.transaction(() => {
+      this.db.query("INSERT OR REPLACE INTO turns (id, peer, started, start_tree) VALUES (?, ?, ?, ?)").run(id, peer, Date.now(), workspace === undefined ? startTree ?? null : null);
+      this.db.query("DELETE FROM turn_workspaces WHERE turn = ?").run(id);
+      if (workspace !== undefined) this.db.query("INSERT INTO turn_workspaces (turn, root, start_tree) VALUES (?, ?, ?)").run(id, workspace, startTree ?? null);
+    })();
+  }
+  /** Only new extra-instance turns carry this evidence; absence preserves legacy external-peer workspace semantics. */
+  workspace(id: string): string | undefined {
+    try {
+      const row = this.db.query("SELECT root FROM turn_workspaces WHERE turn = ?").get(id) as { root: string } | null;
+      if (row && (typeof row.root !== "string" || !row.root)) throw new Error("invalid turn workspace evidence");
+      return row?.root;
+    } catch (error) {
+      if (/no such table/.test((error as Error).message)) return undefined;
+      throw error;
+    }
+  }
+  private snapshotFields<T extends { id: string; start_tree: string | null; end_tree: string | null; changed: string }>(row: T): T {
+    if (this.workspace(row.id) === undefined) return row;
+    const fields = this.db.query("SELECT start_tree, end_tree, changed FROM turn_workspaces WHERE turn = ?").get(row.id) as { start_tree: string | null; end_tree: string | null; changed: string };
+    return { ...row, ...fields };
   }
   /** The first native turn of a hub turn: reverting the conversation drops it and every later one. */
   native(id: string, native: string): void {
     this.db.query("UPDATE turns SET native = ? WHERE id = ? AND native IS NULL").run(native, id);
   }
   end(id: string, endTree: string | undefined, changed: string[], keep: number): void {
-    this.db.query("UPDATE turns SET ended = ?, end_tree = ?, changed = ? WHERE id = ?").run(Date.now(), endTree ?? null, JSON.stringify(changed), id);
+    this.db.transaction(() => {
+      const scoped = this.workspace(id) !== undefined;
+      // Older CLIs do not know workspace receipts. Leave their canonical-checkout snapshot view unknown.
+      this.db.query("UPDATE turns SET ended = ?, end_tree = ?, changed = ? WHERE id = ?").run(Date.now(), scoped ? null : endTree ?? null, scoped ? "[]" : JSON.stringify(changed), id);
+      if (scoped) this.db.query("UPDATE turn_workspaces SET end_tree = ?, changed = ? WHERE turn = ?").run(endTree ?? null, JSON.stringify(changed), id);
+    })();
     const peer = (this.db.query("SELECT peer FROM turns WHERE id = ?").get(id) as { peer: string } | null)?.peer;
     if (peer) this.db.query("DELETE FROM turns WHERE peer = ? AND id NOT IN (SELECT id FROM turns WHERE peer = ? ORDER BY started DESC, rowid DESC LIMIT ?)").run(peer, peer, keep);
+    this.db.run("DELETE FROM turn_workspaces WHERE turn NOT IN (SELECT id FROM turns)");
   }
   list(peer?: string, limit = 20): TurnRecord[] {
     const rows = (peer
       ? this.db.query("SELECT * FROM turns WHERE peer = ? ORDER BY started DESC, rowid DESC LIMIT ?").all(peer, limit)
       : this.db.query("SELECT * FROM turns ORDER BY started DESC, rowid DESC LIMIT ?").all(limit)) as (Omit<TurnRecord, "changed"> & { changed: string })[];
-    return rows.map((r) => ({ ...r, changed: JSON.parse(r.changed) as string[] }));
+    return rows.map(row => this.snapshotFields(row)).map((r) => ({ ...r, changed: JSON.parse(r.changed) as string[] }));
   }
   get(id: string): TurnRecord | undefined {
     const r = this.db.query("SELECT * FROM turns WHERE id = ?").get(id) as (Omit<TurnRecord, "changed"> & { changed: string }) | null;
-    return r ? { ...r, changed: JSON.parse(r.changed) as string[] } : undefined;
+    if (!r) return undefined;
+    const record = this.snapshotFields(r);
+    return { ...record, changed: JSON.parse(record.changed) as string[] };
   }
   /**
    * Other peers' turns that overlapped this one in time: their changes are in this turn's diff too. `unknown` lists
@@ -263,21 +292,23 @@ export class Turns {
   // before" time in Turns.end if that ever matters.
   overlapping(turn: TurnRecord, keep: number): { paths: string[]; unknown: string[] } {
     const rows = this.db.query("SELECT id, changed, ended, start_tree, end_tree FROM turns WHERE id != ? AND peer != ? AND started < ? AND (ended IS NULL OR ended > ?)").all(turn.id, turn.peer, turn.ended ?? Date.now(), turn.started) as { id: string; changed: string; ended: number | null; start_tree: string | null; end_tree: string | null }[];
-    const known = rows.filter((r) => r.ended !== null && r.start_tree !== null && r.end_tree !== null);
+    const scopedRows = rows.map(row => this.snapshotFields(row));
+    const known = scopedRows.filter((r) => r.ended !== null && r.start_tree !== null && r.end_tree !== null);
     const pruned = (this.db.query("SELECT peer, MIN(started) AS oldest FROM turns WHERE peer != ? GROUP BY peer HAVING COUNT(*) >= ?").all(turn.peer, keep) as { peer: string; oldest: number }[])
       .filter((p) => p.oldest > turn.started)
       .map((p) => `${p.peer} (its turns from then were pruned)`);
-    return { paths: [...new Set(known.flatMap((r) => JSON.parse(r.changed) as string[]))], unknown: [...rows.filter((r) => !known.includes(r)).map((r) => r.id), ...pruned] };
+    return { paths: [...new Set(known.flatMap((r) => JSON.parse(r.changed) as string[]))], unknown: [...scopedRows.filter((r) => !known.includes(r)).map((r) => r.id), ...pruned] };
   }
 
   /** Other peers' completed, snapshotted turns that overlapped this turn and changed at least one of the same files. */
   concurrentWith(turn: TurnRecord): TurnRecord[] {
     if (turn.ended === null || turn.start_tree === null || turn.end_tree === null || !turn.changed.length) return [];
     const rows = this.db.query(`SELECT * FROM turns WHERE id != ? AND peer != ? AND started < ? AND ended > ?
-      AND start_tree IS NOT NULL AND end_tree IS NOT NULL ORDER BY started, rowid`)
+      ORDER BY started, rowid`)
       .all(turn.id, turn.peer, turn.ended, turn.started) as (Omit<TurnRecord, "changed"> & { changed: string })[];
     const changed = new Set(turn.changed);
-    return rows.map((r) => ({ ...r, changed: JSON.parse(r.changed) as string[] }))
+    return rows.map(row => this.snapshotFields(row)).filter(row => row.start_tree !== null && row.end_tree !== null)
+      .map((r) => ({ ...r, changed: JSON.parse(r.changed) as string[] }))
       .filter((other) => other.changed.some((path) => changed.has(path)));
   }
 

package/src/hub/start-mode.ts

@@ -1,4 +1,4 @@
-import { definitionOf, SUPPORTED_PEERS, START_MODE_PEERS as REGISTRY_START_MODE_PEERS } from "../adapters/registry.ts";
+import { definitionOf, SUPPORTED_PEERS, START_MODE_PEERS as REGISTRY_START_MODE_PEERS, type KindMap } from "../adapters/registry.ts";
 
 /**
  * #269: how a peer comes up when the hub starts it: its own TUI in a terminal, or headless. A person who types
@@ -20,22 +20,25 @@ export const isStartablePeer = (value: unknown): value is StartablePeer => typeo
 
 export type PeerStartConfig = Record<string, { start_mode?: StartMode }>;
 /** The checked per-peer start modes; only peers with both forms may be configured. */
-export function peerStartConfig(value: unknown): PeerStartConfig {
+export function peerStartConfig(value: unknown, instances?: KindMap): PeerStartConfig {
   if (value === undefined) return {};
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("peers must be an object of per-peer settings");
   const result: PeerStartConfig = {};
   for (const [peer, block] of Object.entries(value)) {
-    if (!(REGISTRY_START_MODE_PEERS as readonly string[]).includes(peer)) throw new Error(`peers.${peer}: only ${REGISTRY_START_MODE_PEERS.join(" and ")} have a start mode`);
+    const extra = definitionOf(peer, instances)?.kind !== peer && !!definitionOf(peer, instances);
+    if (!(REGISTRY_START_MODE_PEERS as readonly string[]).includes(peer) && !extra) throw new Error(`peers.${peer}: only ${REGISTRY_START_MODE_PEERS.join(" and ")} have a start mode`);
     if (!block || typeof block !== "object" || Array.isArray(block)) throw new Error(`peers.${peer} must be an object`);
     const mode = (block as { start_mode?: unknown }).start_mode;
     if (mode !== undefined && !(START_MODES as readonly unknown[]).includes(mode)) throw new Error(`peers.${peer}.start_mode must be tui or headless`);
+    if (extra && mode !== undefined && mode !== "headless") throw new Error(`peers.${peer}.start_mode: extra instances require headless mode in I2`);
     result[peer] = mode === undefined ? {} : { start_mode: mode as StartMode };
   }
   return result;
 }
 
 /** The mode a start of `peer` takes when nothing more specific was asked: `tui` wherever the peer has one. */
-export function startModeOf(peers: PeerStartConfig | undefined, peer: string): StartMode {
+export function startModeOf(peers: PeerStartConfig | undefined, peer: string, instances?: KindMap): StartMode {
+  if (definitionOf(peer, instances)?.kind !== peer && definitionOf(peer, instances)) return peers?.[peer]?.start_mode ?? "headless";
   if ((REGISTRY_START_MODE_PEERS as readonly string[]).includes(peer)) return peers?.[peer]?.start_mode ?? definitionOf(peer)?.start.defaultForm ?? "tui";
   return definitionOf(peer)?.start.defaultForm ?? "headless";
 }

package/src/hub/status-roster.ts

@@ -0,0 +1,18 @@
+// No imports: native CLI entries load this from inside the adapter registry's import graph (#484).
+/** A peer's membership from a `status` reply: undefined when the hub sends no roster (older than #484), never read as off. */
+export function rosterInStatus(status: unknown, peer: string): boolean | undefined {
+  const rows = (status as { roster?: unknown } | undefined)?.roster;
+  if (!Array.isArray(rows)) return undefined;
+  const row = rows.find((r: unknown) => !!r && typeof r === "object" && (r as { peer?: unknown }).peer === peer) as { on?: unknown } | undefined;
+  return typeof row?.on === "boolean" ? row.on : undefined;
+}
+
+/**
+ * The plugin bundle the running daemon verifies Jcode's project MCP entry against. The launcher writes this path rather
+ * than its own copy: the CLI on PATH and the daemon can come from different installs, and the daemon compares the whole
+ * entry. undefined for a hub that sends none or a path that is not that bundle (an older hub, a malformed reply).
+ */
+export function bundleInStatus(status: unknown): string | undefined {
+  const value = (status as { pluginBundle?: unknown } | undefined)?.pluginBundle;
+  return typeof value === "string" && value.startsWith("/") && /[\\/]plugins[\\/]agent-hub[\\/]server\.js$/.test(value) ? value : undefined;
+}

package/src/hub/task-sweep.ts

@@ -58,3 +58,146 @@ export function nextSweep(task: Task, config: TaskSweepConfig, now: number, read
   if (previous && (previous.step === 3 || now - previous.at < config.ladder_min * 60_000)) return undefined;
   return { kind, activity, step: previous ? (previous.step + 1) as 2 | 3 : 1, at: now };
 }
+
+export interface GroomingItem {
+  kind: "text-dependency" | "overlap" | "duplicate" | "over-wip" | "stale" | "superseded" | "blocked" | "closed-issue";
+  task: number;
+  related?: number[];
+  code?: string;
+  personCommand?: string;
+}
+export interface PlannerGroomingOptions {
+  repository: string;
+  limits: Record<string, number>;
+  wip: Record<string, number>;
+  states: Record<string, string>;
+  blockers?: readonly { task: number; code: string }[];
+  issues?: ReadonlyMap<string, { repo: string; issue: number; state: "OPEN" | "CLOSED"; editedAt: string; lastEditedAt?: string | null }>;
+  reviewedIssues?: ReadonlyMap<number, { editedAt: string }>;
+  acceptedIssues?: ReadonlyMap<number, { repo: string; issue: number; lastEditedAt: string | null }>;
+}
+const GROOMING_TASK_LIMIT = 500, GROOMING_ITEM_LIMIT = 256;
+const GROOMING_CODES = new Set(["tests", "spec", "roster", "pull-only", "not-attached", "excluded", "owner-admission", "offline", "paused", "failing", "pii", "policy", "cancelled", "unavailable", "runner", "approvals", "quota", "dependency"]);
+const groomingRepo = (value: unknown): string | undefined => {
+  if (typeof value !== "string") return undefined;
+  if (value.startsWith("path:/") && value.length <= 4096 && !/\p{Cc}/u.test(value)) return value;
+  return /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value) && !value.startsWith("-") ? value.toLowerCase() : undefined;
+};
+const groomingOwn = <T>(values: Record<string, T>, key: string): T | undefined => Object.hasOwn(values, key) ? values[key] : undefined;
+function groomingPath(value: string): string | undefined {
+  if (!value || value.length > 1000 || /\p{Cc}/u.test(value)) return;
+  const parts: string[] = [];
+  for (const part of value.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") { if (!parts.length) return; parts.pop(); }
+    else parts.push(part);
+  }
+  return parts.length ? (value.startsWith("/") ? "/" : "") + parts.join("/") : value.startsWith("/") ? "/" : ".";
+}
+
+/** Read-only ids/codes projection. Callers retain authority, privacy screening and the current metadata snapshot. */
+export function plannerGrooming(tasks: readonly Task[], options: PlannerGroomingOptions): { items: GroomingItem[]; unknown: number[]; truncated: boolean } {
+  const items: GroomingItem[] = [], unknown = new Set<number>(), seen = new Set<string>();
+  let truncated = tasks.length > GROOMING_TASK_LIMIT;
+  const repository = groomingRepo(options.repository);
+  // ponytail: bounded O(500²) snapshot; add revision-keyed paging/indexing before supporting larger complete boards.
+  const snapshot = tasks.slice(0, GROOMING_TASK_LIMIT).filter(task => task.state !== "approved" && (task.state !== "cancelled" || task.history.some(entry => entry.supersededBy))).sort((a, b) => a.id - b.id);
+  const add = (item: GroomingItem) => {
+    const key = JSON.stringify(item);
+    if (seen.has(key)) return;
+    seen.add(key);
+    if (items.length >= GROOMING_ITEM_LIMIT) { truncated = true; return; }
+    items.push(item);
+  };
+  const repositories = new Map<number, string>();
+  const scoped = snapshot.flatMap(task => {
+    const scopes = [task.refs.repo, task.external?.repo, task.sdlc?.repo].filter(value => value !== undefined);
+    const normalized = scopes.map(groomingRepo);
+    if (normalized.some(value => !value) || new Set(normalized).size > 1 || (!repository && !normalized.length)) { unknown.add(task.id); return []; }
+    // ponytail: without project-root/Git identity, unqualified absolute paths cannot be attributed safely.
+    // A future hardened repository resolver (#169) may prove their scope instead of leaving it unknown.
+    if (!normalized.length && [...(task.refs.paths ?? []), ...(task.plan?.paths ?? [])].some(path => path.startsWith("/"))) { unknown.add(task.id); return []; }
+    repositories.set(task.id, (normalized[0] ?? repository)!);
+    return [task];
+  });
+  const ids = new Set(scoped.map(task => task.id));
+  const issueIds = new Map<number, Set<number>>();
+  for (const task of scoped) {
+    const taskRepository = repositories.get(task.id)!;
+    const replacements = new Set<number>();
+    for (const entry of task.history) {
+      if (!entry.supersededBy) continue;
+      const match = /^#([1-9][0-9]*)$/.exec(entry.supersededBy);
+      const id = match ? Number(match[1]) : NaN;
+      if (Number.isSafeInteger(id) && id !== task.id && ids.has(id) && repositories.get(id) === taskRepository) replacements.add(id);
+      else unknown.add(task.id);
+    }
+    if (replacements.size) add({ kind: "superseded", task: task.id, related: [...replacements].sort((a, b) => a - b) });
+    if (task.state === "cancelled") continue; // Closed rows contribute supersession evidence only.
+    const issues = new Set<number>();
+    for (const issue of [task.external?.issue, task.sdlc?.issue]) {
+      if (issue === undefined) continue;
+      if (Number.isSafeInteger(issue) && issue > 0) issues.add(issue); else unknown.add(task.id);
+    }
+    // A bare title reference is an issue. Bare detail numbers remain board task references.
+    for (const match of task.title.matchAll(/(?<![A-Za-z0-9_./-])(?:https:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)\/issues\/([1-9][0-9]*)\b|([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#([1-9][0-9]*)\b|#([1-9][0-9]*)\b)/g)) {
+      const scope = match[1] ?? match[3], issue = Number(match[2] ?? match[4] ?? match[5]);
+      if (scope && groomingRepo(scope) !== taskRepository) { unknown.add(task.id); continue; }
+      if (Number.isSafeInteger(issue)) issues.add(issue); else unknown.add(task.id);
+    }
+    issueIds.set(task.id, issues);
+    const missing = new Set<number>();
+    for (const match of task.detail.matchAll(/^\s*(?:after|waits for)\s+#([1-9][0-9]*)\b/gim)) {
+      const id = Number(match[1]);
+      if (id !== task.id && Number.isSafeInteger(id) && !(task.deps ?? []).includes(id)) {
+        if (ids.has(id)) missing.add(id); else unknown.add(task.id);
+      }
+    }
+    if (missing.size) add({ kind: "text-dependency", task: task.id, related: [...missing].sort((a, b) => a - b) });
+    const owner = task.owner ?? task.reserved;
+    if (owner) {
+      const count = groomingOwn(options.wip, owner), limit = groomingOwn(options.limits, owner), state = groomingOwn(options.states, owner);
+      if (count === undefined || limit === undefined || !Number.isSafeInteger(count) || count < 0 || !Number.isSafeInteger(limit) || limit < 0) unknown.add(task.id);
+      else if (task.owner && count > limit) add({ kind: "over-wip", task: task.id, personCommand: `ahub task unassign ${task.id}` });
+      if (state === "offline" || state === "paused") add({ kind: "blocked", task: task.id, code: state });
+      else if (state === undefined) unknown.add(task.id);
+    }
+    for (const issue of issues) {
+      const metadata = options.issues?.get(`${taskRepository}#${issue}`);
+      if (!metadata || groomingRepo(metadata.repo) !== taskRepository || metadata.issue !== issue || !["OPEN", "CLOSED"].includes(metadata.state) || !Number.isFinite(Date.parse(metadata.editedAt))) { unknown.add(task.id); continue; }
+      if (metadata.state === "CLOSED") add({ kind: "closed-issue", task: task.id });
+      const reviewed = options.reviewedIssues?.get(task.id), accepted = options.acceptedIssues?.get(task.id);
+      if (reviewed) {
+        if (!Number.isFinite(Date.parse(reviewed.editedAt))) unknown.add(task.id);
+        else if (Date.parse(metadata.editedAt) > Date.parse(reviewed.editedAt)) add({ kind: "stale", task: task.id });
+      }
+      if (accepted) {
+        const stamp = (value: unknown): value is string | null => value === null || typeof value === "string" && Number.isFinite(Date.parse(value));
+        // An old metadata snapshot has no lastEditedAt: its createdAt fallback cannot prove S1's null body stamp.
+        if (groomingRepo(accepted.repo) !== taskRepository || accepted.issue !== issue || !stamp(accepted.lastEditedAt)
+          || !Object.hasOwn(metadata, "lastEditedAt") || !stamp(metadata.lastEditedAt)) unknown.add(task.id);
+        else if (accepted.lastEditedAt !== metadata.lastEditedAt) add({ kind: "stale", task: task.id });
+      }
+      if (!reviewed && !accepted) unknown.add(task.id);
+    }
+  }
+  const places = (task: Task) => ({ paths: new Set([...(task.refs.paths ?? []), ...(task.plan?.paths ?? [])].map(groomingPath).filter((path): path is string => path !== undefined)), symbols: new Set(task.plan?.symbols ?? []) });
+  const open = scoped.filter(task => task.state !== "cancelled");
+  const positions = new Map(open.map(task => [task.id, places(task)]));
+  const overlaps = (left: string, right: string): boolean => left === right || left === "." || right === "."
+    || left.startsWith(right.endsWith("/") ? right : right + "/") || right.startsWith(left.endsWith("/") ? left : left + "/");
+  for (let left = 0; left < open.length; left++) for (const right of open.slice(left + 1)) {
+    const task = open[left]!;
+    if (repositories.get(task.id) !== repositories.get(right.id)) continue;
+    const a = positions.get(task.id)!, b = positions.get(right.id)!;
+    if ([...a.paths].some(path => [...b.paths].some(other => overlaps(path, other))) || [...a.symbols].some(symbol => b.symbols.has(symbol))) add({ kind: "overlap", task: task.id, related: [right.id] });
+    if ([...issueIds.get(task.id)!].some(issue => issueIds.get(right.id)!.has(issue))) add({ kind: "duplicate", task: task.id, related: [right.id] });
+  }
+  for (const blocker of (options.blockers ?? []).slice(0, GROOMING_TASK_LIMIT)) {
+    if (!positions.has(blocker.task)) continue;
+    if (GROOMING_CODES.has(blocker.code)) add({ kind: "blocked", task: blocker.task, code: blocker.code });
+    else unknown.add(blocker.task);
+  }
+  if ((options.blockers?.length ?? 0) > GROOMING_TASK_LIMIT) truncated = true;
+  return { items, unknown: [...unknown].sort((a, b) => a - b), truncated };
+}