@staix/agent-hub 0.12.23 → 0.12.24

package/src/hub/text-projection.ts

@@ -0,0 +1,126 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, mkdirSync, mkdtempSync, openSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { extname, isAbsolute, join, resolve } from "node:path";
+
+import { homedir, tmpdir } from "node:os";
+import { sbplString } from "../local/deny.ts";
+import { spawnSync } from "node:child_process";
+import { realPath } from "./project.ts";
+import { profile, sandboxAvailable } from "../local/sandbox.ts";
+export type ProjectionConfig = Record<string, string[]>;
+export const MAX_PROJECTION_INPUT = 16 * 1024 * 1024;
+const MAX_INPUT = MAX_PROJECTION_INPUT, MAX_TEXT = 256 * 1024;
+/** Only machine-local config chooses programs; no implicit shell or command-string parsing. */
+export function projectionConfig(raw: unknown): ProjectionConfig {
+  if (raw === undefined) return {};
+  if (!raw || typeof raw !== "object" || Array.isArray(raw) || Object.keys(raw).length > 16) throw new Error("text_projection must be a bounded extension-to-argv map");
+  const out: ProjectionConfig = Object.create(null);
+  for (const [ext, argv] of Object.entries(raw)) {
+    if (!/^\.[a-z0-9]{1,16}$/.test(ext) || !Array.isArray(argv) || !argv.length || argv.length > 16 || argv.some(arg => typeof arg !== "string" || !arg || arg.length > 2000 || /[\x00-\x1f\x7f]/.test(arg)) || argv.filter(arg => arg === "{input}").length !== 1 || argv[0] === "{input}") throw new Error("text_projection entries require a bounded argv with one separate {input} argument");
+    out[ext] = [...argv];
+  }
+  return out;
+}
+export interface ProjectedText { inputHash: string; rawHash: string; rawBlob: string; configHash: string; text: string }
+const hash = (data: string | Buffer) => createHash("sha256").update(data).digest("hex");
+function commandFingerprint(cwd: string, argv: string[]): string {
+  const parts = [JSON.stringify(argv)];
+  for (const [index, arg] of argv.entries()) {
+    if (index !== 0 && !/\.(?:sh|py|js|ts|rb)$/.test(arg)) continue;
+    const choices = isAbsolute(arg) ? [arg] : index === 0 && !arg.includes("/") ? (process.env.PATH ?? "/usr/bin:/bin").split(":").slice(0, 32).map(dir => join(dir, arg)) : [resolve(cwd, arg)];
+    for (const file of choices) try { const st = statSync(file); if (!st.isFile()) continue; parts.push(file, String(st.size), String(st.mtimeMs), String(st.ctimeMs)); break; } catch { /* another PATH entry */ }
+  }
+  return hash(parts.join("\\n"));
+}
+function boundedCache(file: string): string {
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile() || st.nlink !== 1 || st.size > MAX_TEXT * 2) throw new Error("invalid cache file");
+    const bytes = Buffer.alloc(st.size); let got = 0;
+    while (got < bytes.length) { const n = readSync(fd, bytes, got, bytes.length - got, got); if (!n) break; got += n; }
+    if (got !== st.size) throw new Error("cache changed");
+    return bytes.toString("utf8");
+  } finally { closeSync(fd); }
+}
+/** Projections are presentation evidence, never proof of who wrote the original bytes. */
+export class TextProjections {
+  private readonly sandbox: string;
+  private readonly warned = new Set<string>();
+  constructor(private readonly options: { cwd: string; stateDir: string; config: ProjectionConfig; deny?: string[]; readAllow?: string[]; log?: (line: string) => void }) {
+    this.sandbox = Object.keys(options.config).length ? profile(options.cwd, false, options.readAllow, options.deny, ["."]) : "";
+  }
+  private warn(ext: string): void {
+    if (this.warned.has(ext)) return;
+    this.warned.add(ext); this.options.log?.("text projection " + ext + " unavailable; retained original facts behavior");
+  }
+  get enabled(): boolean { return Object.keys(this.options.config).length > 0; }
+  handles(file: string): boolean { return !!this.options.config[extname(file).toLowerCase()]; }
+  project(file: string): ProjectedText | undefined {
+    const ext = extname(file).toLowerCase(), argv = this.options.config[ext];
+    if (!argv) return undefined;
+    let fd: number | undefined;
+    try {
+      const root = realPath(this.options.cwd), input = realPath(file);
+      if (!input.startsWith(root + "/")) throw new Error("input outside project");
+      fd = openSync(input, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+      const before = fstatSync(fd);
+      if (!before.isFile() || before.size > MAX_INPUT) throw new Error("input cap");
+      const bytes = Buffer.alloc(before.size); let got = 0;
+      while (got < bytes.length) { const n = readSync(fd, bytes, got, bytes.length - got, got); if (!n) break; got += n; }
+      const after = fstatSync(fd);
+      if (got !== before.size || before.size !== after.size || before.mtimeMs !== after.mtimeMs) throw new Error("input changed");
+      return this.convert(ext, bytes, () => {
+        const final = fstatSync(fd!);
+        if (final.size !== before.size || final.mtimeMs !== before.mtimeMs) throw new Error("input changed during conversion");
+      });
+    } catch { this.warn(ext); return undefined; }
+    finally { if (fd !== undefined) closeSync(fd); }
+  }
+  /** Historic raw bytes; optional deadline uses performance.now(), shared across the preview. No current file read. */
+  projectBytes(file: string, bytes: Buffer, deadline?: number): ProjectedText | undefined {
+    const ext = extname(file).toLowerCase();
+    if (!this.options.config[ext]) return undefined;
+    try {
+      const root = realPath(this.options.cwd), input = resolve(root, file);
+      if (!input.startsWith(root + "/") || !Buffer.isBuffer(bytes) || bytes.length > MAX_INPUT) throw new Error("snapshot input cap or path");
+      return this.convert(ext, Buffer.from(bytes), undefined, deadline);
+    } catch { this.warn(ext); return undefined; }
+  }
+  private convert(ext: string, bytes: Buffer, verify?: () => void, deadline?: number): ProjectedText | undefined {
+    const argv = this.options.config[ext];
+    if (!argv) return undefined;
+    let scratch: string | undefined;
+    try {
+      if (deadline !== undefined && (!Number.isFinite(deadline) || deadline <= performance.now())) throw new Error("projection deadline");
+      const rawHash = createHash("sha1").update(bytes).digest("hex"), rawBlob = createHash("sha1").update("blob " + bytes.length + "\0").update(bytes).digest("hex");
+      const inputHash = hash(bytes), configHash = commandFingerprint(this.options.cwd, argv), key = hash(inputHash + "\n" + configHash + "\n" + ext);
+      const cacheDir = join(this.options.stateDir, "text-projections"), cache = join(cacheDir, key + ".json");
+      try {
+        const cached = boundedCache(cache);
+        if (Buffer.byteLength(cached) <= MAX_TEXT * 2) {
+          const value = JSON.parse(cached) as ProjectedText;
+          if (value.inputHash === inputHash && value.rawHash === rawHash && value.rawBlob === rawBlob && value.configHash === configHash && typeof value.text === "string" && Buffer.byteLength(value.text) <= MAX_TEXT) return value;
+        }
+      } catch { /* missing/invalid cache is not evidence */ }
+      if (!sandboxAvailable()) throw new Error("sandbox unavailable");
+      scratch = realPath(mkdtempSync(join(tmpdir(), "ahub-projection-input-"))); const snapshot = join(scratch, "input" + ext);
+      writeFileSync(snapshot, bytes, { mode: 0o400 });
+      const result = spawnSync(process.execPath, [join(import.meta.dir, "projection-exec.ts")], {
+        cwd: this.options.cwd, timeout: deadline === undefined ? 8000 : Math.ceil(Math.max(1, Math.min(8000, deadline - performance.now()))), maxBuffer: MAX_TEXT * 2, encoding: "utf8",
+        input: JSON.stringify({ cwd: this.options.cwd, sandbox: this.sandbox + "\n(allow file-read* (literal " + sbplString(snapshot) + "))", argv: argv.map(arg => arg === "{input}" ? snapshot : arg), ...(deadline === undefined ? {} : { timeoutMs: Math.max(1, Math.min(5000, deadline - performance.now() - 100)) }) }),
+        env: { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: homedir(), LANG: "en_US.UTF-8", TERM: "dumb" },
+      });
+      if (result.error || result.status !== 0) throw new Error("conversion failed");
+      const converted = JSON.parse(result.stdout) as { ok?: boolean; text?: string };
+      if (converted.ok !== true || typeof converted.text !== "string" || Buffer.byteLength(converted.text) > MAX_TEXT || converted.text.includes("\0")) throw new Error("conversion failed");
+      verify?.();
+      const value = { inputHash, rawHash, rawBlob, configHash, text: converted.text };
+      mkdirSync(cacheDir, { recursive: true });
+      const temporary = cache + "." + crypto.randomUUID() + ".tmp";
+      writeFileSync(temporary, JSON.stringify(value), { mode: 0o600 }); renameSync(temporary, cache);
+      return value;
+    } catch { this.warn(ext); return undefined; }
+    finally { if (scratch) rmSync(scratch, { recursive: true, force: true }); }
+  }
+}

package/src/hub/tooling.ts

@@ -0,0 +1,159 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { accessSync, constants, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join, relative, resolve, isAbsolute } from "node:path";
+import { realPath } from "./project.ts";
+
+/**
+ * #248: which add-ons a peer works with, from a closed list. Names and versions only, read from the machine's plugin
+ * inventory and launch settings (Claude Code's installed plugins and `enabledPlugins`, Codex's `config.toml`) and from
+ * the executables on PATH; never a plugin's content, settings values, hooks or paths.
+ * ponytail: the inventory is the machine's, not the session's: a session started with its own `--settings` or plugin
+ * flags can differ. Reading the launch record of each `ahub claude` / `ahub codex` would make it exact.
+ */
+export const ADDONS = ["claude-mem", "ponytail", "ripwire", "open-code-review", "codex-plugin", "dot-admit"] as const;
+export type AddonName = (typeof ADDONS)[number];
+export interface Addon { name: AddonName; version: string | null }
+
+/** Plugin names (before the `@marketplace`) that stand for an add-on. */
+// Maps, not objects: a plugin named `constructor` or `toString` must find nothing, not an inherited property.
+const PLUGINS = new Map<string, AddonName>([["claude-mem", "claude-mem"], ["ponytail", "ponytail"], ["open-code-review", "open-code-review"]]);
+/** Claude Code only: the Codex plugin is a Claude plugin named `codex` from the `openai-codex` marketplace. */
+const CLAUDE_ONLY = new Map<string, AddonName>([["codex@openai-codex", "codex-plugin"]]);
+/**
+ * Executables any peer with a shell can run, and how each is told apart from another program of the same name: the
+ * first one on PATH is asked for its version (bounded, no stdin), so Graphviz's `dot` is never resource admission.
+ */
+const BINARIES: Record<string, { name: AddonName; version?: RegExp }> = { ripwire: { name: "ripwire" }, dot: { name: "dot-admit", version: /^dot version (\S+)/ } };
+/** By resolved path and modification time: one version call per binary per process. */
+const identities = new Map<string, Promise<string | null | false>>();
+const PROBE_MS = 2000, PROBE_BYTES = 4096;
+
+/** `env` supplies CLAUDE_CONFIG_DIR and CODEX_HOME, the runtimes' own config roots (the hub's environment by default). */
+export interface ToolingSources { home?: string; cwd?: string; path?: string; env?: Record<string, string | undefined> }
+
+const json = (file: string): Record<string, unknown> | undefined => {
+  try { const v = JSON.parse(readFileSync(file, "utf8")); return v && typeof v === "object" ? v as Record<string, unknown> : undefined; } catch { return undefined; }
+};
+/** A version string as data, never anything longer or stranger. */
+const version = (v: unknown): string | null => typeof v === "string" && /^[0-9A-Za-z.+_-]{1,40}$/.test(v) ? v : null;
+
+function claudePlugins(root: string, cwd: string | undefined): Addon[] {
+  const enabled = new Map<string, boolean>();
+  for (const file of [join(root, "settings.json"), ...(cwd ? [join(cwd, ".claude", "settings.json"), join(cwd, ".claude", "settings.local.json")] : [])]) {
+    const map = json(file)?.enabledPlugins;
+    if (map && typeof map === "object") for (const [key, on] of Object.entries(map)) enabled.set(key, on === true);
+  }
+  const installed = (json(join(root, "plugins", "installed_plugins.json"))?.plugins ?? {}) as Record<string, { scope?: string; projectPath?: string; version?: unknown }[]>;
+  const out: Addon[] = [];
+  for (const [key, on] of enabled) {
+    if (!on) continue;
+    const name = CLAUDE_ONLY.get(key) ?? PLUGINS.get(key.split("@")[0]!);
+    const entries = Array.isArray(installed[key]) ? installed[key]! : [];
+    // An install for another project is not this one's.
+    const entry = entries.find((e) => e?.scope === "user") ?? entries.find((e) => e?.projectPath === cwd);
+    if (name && entry) out.push({ name, version: version(entry.version) });
+  }
+  return out;
+}
+
+function codexPlugins(root: string): Addon[] {
+  let text: string;
+  try { text = readFileSync(join(root, "config.toml"), "utf8"); } catch { return []; }
+  const found = new Map<string, string>(); // plugin name -> marketplace
+  // `[plugins."name@market"]` with no `enabled = false` below it, and plugins whose hooks Codex was told to trust.
+  for (const m of text.matchAll(/^\[plugins\."([^"@]+)@([^"]+)"\]\s*\n((?:(?!\[)[^\n]*\n?)*)/gm)) if (!/^\s*enabled\s*=\s*false\b/m.test(m[3] ?? "")) found.set(m[1]!, m[2]!);
+  for (const m of text.matchAll(/^\[hooks\.state\."([^"@]+)@([^":]+):/gm)) found.set(m[1]!, m[2]!);
+  const out: Addon[] = [];
+  for (const [plugin, market] of found) {
+    const name = PLUGINS.get(plugin);
+    if (!name) continue;
+    let versions: string[] = [];
+    try { versions = readdirSync(join(root, "plugins", "cache", market, plugin)); } catch { /* no cache: version unknown */ }
+    out.push({ name, version: versions.length === 1 ? version(versions[0]) : null });
+  }
+  return out;
+}
+
+/** Never throws: a path that cannot be resolved (a project directory that went away) is compared as given. */
+const real = (path: string): string => { try { return realPath(path); } catch { return resolve(path); } };
+const within = (file: string, dir: string): boolean => { const r = relative(dir, file); return r === "" || (!r.startsWith("..") && !isAbsolute(r)); };
+
+/** The first executable of that name on PATH, relative and empty entries resolved from the peer's working directory. */
+function onPath(name: string, path: string, cwd: string): string | undefined {
+  for (const dir of path.split(delimiter)) {
+    const file = resolve(cwd, dir || ".", name);
+    // A shell runs the first executable regular file; a directory of that name is skipped like a missing one.
+    try { if (statSync(file).isFile()) { accessSync(file, constants.X_OK); return file; } } catch { /* not here */ }
+  }
+  return undefined;
+}
+/**
+ * The version an executable reports when it is the expected program, `null` when that is unknown, `false` when it is
+ * another program or does not answer within PROBE_MS. Asynchronous with a hard deadline: a program that ignores SIGTERM
+ * is killed outright and never waited on, so it can never hold up the hub.
+ */
+function identify(file: string, pattern: RegExp, env: Record<string, string>): Promise<string | null | false> {
+  let key = file;
+  try { key = `${file}:${statSync(file).mtimeMs}`; } catch { /* unreadable: ask anyway */ }
+  let found = identities.get(key);
+  if (!found) {
+    found = new Promise<string | null | false>((resolve) => {
+      let out = "", settled = false, child: ChildProcess | undefined;
+      // Its own process group, killed as one when the answer is in or the deadline passes: a descendant that kept the
+      // pipe open would otherwise outlive the probe and hold up whoever waits on it.
+      const finish = (answer: string | null | false) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        try { if (child?.pid) process.kill(-child.pid, "SIGKILL"); } catch { /* the group is gone */ }
+        child?.stdout?.destroy();
+        resolve(answer);
+      };
+      const timer = setTimeout(() => finish(false), PROBE_MS);
+      try {
+        // Only PATH (its absolute entries outside the project, so an env-shebang interpreter still resolves), HOME and
+        // the C locale reach the probed program: no gateway keys, Access values or agent markers.
+        child = spawn(file, ["--version"], { detached: true, stdio: ["ignore", "pipe", "ignore"], env });
+        child.unref();
+        // A version line is short: a program that keeps writing is not the one asked for, and is not read further.
+        child.stdout?.on("data", (chunk: Buffer) => { out += chunk.toString("utf8"); if (out.length > PROBE_BYTES) finish(false); });
+        child.on("error", () => finish(false));
+        // The version line is written before the program exits; a moment for the pipe to deliver it.
+        child.on("exit", () => setTimeout(() => { const m = pattern.exec(out.trim()); finish(m ? version(m[1]) : false); }, 50));
+      } catch { finish(false); }
+    });
+    identities.set(key, found);
+  }
+  return found;
+}
+
+/** The add-ons a peer works with, sorted by name. Unreadable sources contribute nothing; they never throw. */
+export async function detectTooling(peer: string, src: ToolingSources = {}): Promise<Addon[]> {
+  const home = src.home ?? homedir();
+  const found = new Map<AddonName, Addon>();
+  const add = (a: Addon) => { if (!found.has(a.name) || (found.get(a.name)!.version === null && a.version !== null)) found.set(a.name, a); };
+  const env = src.env ?? process.env;
+  if (peer === "claude") claudePlugins(env.CLAUDE_CONFIG_DIR?.trim() || join(home, ".claude"), src.cwd).forEach(add);
+  if (peer === "codex") codexPlugins(env.CODEX_HOME?.trim() || join(home, ".codex")).forEach(add);
+  const path = src.path ?? process.env.PATH ?? "";
+  for (const [bin, spec] of Object.entries(BINARIES)) {
+    const file = onPath(bin, path, src.cwd ?? process.cwd());
+    if (!file) continue;
+    // A program inside the project is the repository's, not an installed tool: it is never run to identify it (opening a
+    // checkout must not execute its files), so it does not count where its identity has to be checked.
+    const inProject = src.cwd !== undefined && within(real(file), real(src.cwd));
+    const probeEnv = { PATH: path.split(delimiter).filter((d) => isAbsolute(d) && !(src.cwd !== undefined && within(real(d), real(src.cwd)))).join(delimiter) || "/usr/bin:/bin", HOME: home, LANG: "C", LC_ALL: "C" };
+    const v = spec.version ? (inProject ? false : await identify(file, spec.version, probeEnv)) : null;
+    if (v !== false) add({ name: spec.name, version: v });
+  }
+  return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** `on` when any of the peers has the add-on, `off` when every peer's fingerprint is known and none has it, else unknown. */
+export function addonState(name: AddonName, fingerprints: (Addon[] | undefined)[]): "on" | "off" | "unknown" {
+  if (fingerprints.some((f) => f?.some((a) => a.name === name))) return "on";
+  return fingerprints.length && fingerprints.every((f) => f !== undefined) ? "off" : "unknown";
+}
+
+export const isAddon = (name: string): name is AddonName => (ADDONS as readonly string[]).includes(name);

package/src/hub/ui.ts

@@ -1,5 +1,13 @@
+import { BACKLOG_SPLIT_SCREEN_TIMEOUT_MS } from "./planning.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
+import { boardColumns } from "../ui/task-board.ts";
+import { PEER_PALETTE, peerPaletteCss } from "../ui/peer-palette.ts";
 import { PEER_START_RETRY_MS } from "./start-mode.ts";
 import { taskProgress } from "../ui/task-progress.ts";
+import { officeModel } from "../ui/office-model.ts";
+import { needs } from "../ui/needs.ts";
+import { CHARACTERS } from "../pet/characters.ts";
+import { petPixels } from "../pet/pixels.ts";
 import { createHash, randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
 
@@ -28,8 +36,12 @@ export function startDashboard(options: DashboardOptions) {
   const sessions = new Map<string, { expires: number; settingsUntil?: number }>();
   // Inject the same pure public-board model used by the console before computing CSP hashes.
   const html = readFileSync(new URL("../ui/index.html", import.meta.url), "utf8")
+    .replace("/* BOARD_MODEL */", () => `const boardColumns = ${boardColumns.toString()}; const peerPalette = ${JSON.stringify(PEER_PALETTE)};`)
+    .replace("/* PEER_PALETTE_CSS */", () => peerPaletteCss())
     .replace("/* TASK_PROGRESS_MODEL */", () => `const taskProgress = ${taskProgress.toString()};`)
-    .replace("/* PEER_START_RETRY_MS */", () => `const PEER_START_RETRY_MS = ${PEER_START_RETRY_MS};`);
+    .replace("/* PEER_START_RETRY_MS */", () => `const PEER_START_RETRY_MS = ${PEER_START_RETRY_MS};`)
+    .replace("/* OFFICE_MODEL */", () => `const officeModel = ${officeModel.toString()};`)
+    .replace("/* PET_MODEL */", () => `const needs = ${needs.toString()}; const petCharacters = ${JSON.stringify(Object.fromEntries(Object.entries(CHARACTERS).map(([id, character]) => [id, { name: character.name, accent: character.accent, frames: { blocks: Object.fromEntries(Object.entries(character.frames.blocks).map(([pose, sizes]) => [pose, { full: sizes.full }])) } }])))}; const petPixels = ${petPixels.toString()};`);
   const hashes = (tag: string) => [...html.matchAll(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`, "g"))]
     .map((m) => `'sha256-${createHash("sha256").update(m[1]!).digest("base64")}'`).join(" ");
   const headers = {
@@ -53,7 +65,7 @@ export function startDashboard(options: DashboardOptions) {
     hostname: "127.0.0.1",
     port: 0,
     maxRequestBodySize: 32 * 1024,
-    async fetch(req): Promise<Response> {
+    async fetch(req, server): Promise<Response> {
       if (req.headers.get("host") !== host) return reject(403, "forbidden host");
       const requestOrigin = req.headers.get("origin");
       if (requestOrigin !== null && requestOrigin !== origin) return reject(403, "forbidden origin");
@@ -121,6 +133,8 @@ export function startDashboard(options: DashboardOptions) {
         }
       }
       try {
+        if (input.action === "sdlc_queue" || input.action === "sdlc_release") server.timeout(req, 35);
+        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);
         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/workflow.ts

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import type { Task } from "./board.ts";
+import type { SdlcConfig } from "./sdlc.ts";
+
+export interface PhaseReceipt {
+  id: string;
+  head?: string;
+  tasks: { id: number; after: number[] }[];
+  criteria: { id: string; required: boolean; result: "verified" | "failed" | "unverified"; refs: string[] }[];
+}
+const taskId = (n: unknown): n is number => Number.isSafeInteger(n) && typeof n === "number" && n > 0;
+const name = (s: unknown): s is string => typeof s === "string" && /^[a-z][a-z0-9-]{0,47}$/.test(s);
+const hash = (s: unknown): s is string => typeof s === "string" && /^[0-9a-f]{40}$/.test(s);
+const fields = (v: unknown, keys: string[], label: string): Record<string, unknown> => {
+  if (!v || typeof v !== "object" || Array.isArray(v) || Object.keys(v).some(k => !keys.includes(k))) throw new Error(`${label}: invalid fields`);
+  return v as Record<string, unknown>;
+};
+export function phaseReceipt(value: unknown): PhaseReceipt {
+  const serialized = JSON.stringify(value);
+  if (typeof serialized !== "string") throw new Error("phase: invalid fields");
+  if (Buffer.byteLength(serialized) > 32768) throw new Error("phase: receipt exceeds 32 KiB");
+  const p = fields(value, ["id", "head", "tasks", "criteria"], "phase");
+  if (!name(p.id) || (p.head !== undefined && !hash(p.head))) throw new Error("phase: expected bounded id and full head SHA");
+  if (!Array.isArray(p.tasks) || p.tasks.length > 64 || !Array.isArray(p.criteria) || !p.criteria.length || p.criteria.length > 32) throw new Error("phase: at most 64 tasks and 1..32 criteria");
+  const tasks = p.tasks.map(raw => {
+    const t = fields(raw, ["id", "after"], "phase task");
+    if (!taskId(t.id) || !Array.isArray(t.after) || t.after.length > 16 || !t.after.every(taskId) || new Set(t.after).size !== t.after.length || t.after.includes(t.id)) throw new Error("phase task: invalid id or predecessors");
+    return { id: t.id, after: [...t.after] as number[] };
+  });
+  const criteria = p.criteria.map(raw => {
+    const c = fields(raw, ["id", "required", "result", "refs"], "phase criterion");
+    if (!name(c.id) || typeof c.required !== "boolean" || !["verified", "failed", "unverified"].includes(String(c.result)) || !Array.isArray(c.refs) || c.refs.length > 8 || new Set(c.refs).size !== c.refs.length || c.refs.some(ref => typeof ref !== "string" || !/^(sha256:[0-9a-f]{64}|(artifact|check|source):[A-Za-z0-9._/-]{1,160}@[0-9a-f]{64})$/.test(ref)) || (c.result === "verified" && !c.refs.length)) throw new Error("phase criterion: invalid outcome or hashed evidence refs");
+    return { id: c.id, required: c.required, result: c.result as PhaseReceipt["criteria"][number]["result"], refs: [...c.refs] as string[] };
+  });
+  if (new Set(tasks.map(t => t.id)).size !== tasks.length || new Set(criteria.map(c => c.id)).size !== criteria.length) throw new Error("phase: duplicate task or criterion");
+  return { id: p.id, ...(p.head ? { head: p.head as string } : {}), tasks, criteria };
+}
+export type TaskLookup = (id: number) => Task | null | undefined;
+/** An import names existing Tasks.after edges, it never edits dependencies or ownership. */
+export function validatePhaseLinks(parent: Task, phase: PhaseReceipt, get: TaskLookup, isPrivate: (t: Task) => boolean): void {
+  const seen = new Set<number>(), active = new Set<number>();
+  const visit = (id: number): void => {
+    if (id === parent.id) throw new Error("phase: parent cannot be its own prerequisite or child");
+    if (active.has(id)) throw new Error("phase: dependency cycle");
+    if (seen.has(id)) return;
+    if (seen.size >= 256) throw new Error("phase: dependency closure exceeds 256 tasks");
+    const task = get(id); if (!task) throw new Error("phase: referenced task missing");
+    if (!isPrivate(parent) && isPrivate(task)) throw new Error("phase: ordinary parent cannot reference private work");
+    seen.add(id); active.add(id);
+    for (const predecessor of task.deps ?? []) visit(predecessor);
+    active.delete(id);
+  };
+  for (const link of phase.tasks) {
+    visit(link.id);
+    const actual = get(link.id)!.deps ?? [];
+    if (actual.length !== link.after.length || actual.some(id => !link.after.includes(id))) throw new Error("phase: predecessor ids must match current Tasks.after edges");
+  }
+}
+export interface PhaseView { workflow: "gsd-lite"; id?: string; ready: boolean; blockers: string[]; tasks?: { id: number; after: number[]; state: string }[]; criteria?: PhaseReceipt["criteria"]; }
+export function phaseView(config: SdlcConfig, parent: Task, get: TaskLookup, isPrivate: (t: Task) => boolean): PhaseView | undefined {
+  if (config.workflow !== "gsd-lite") return;
+  const blockers: string[] = [], phase = parent.sdlc?.phase;
+  if (isPrivate(parent)) return { workflow: "gsd-lite", ready: false, blockers: ["private phase evidence unknown"] };
+  if (!phase) return { workflow: "gsd-lite", ready: false, blockers: ["phase checklist missing"] };
+  try { validatePhaseLinks(parent, phase, get, isPrivate); } catch { return { workflow: "gsd-lite", id: phase.id, ready: false, blockers: ["phase dependency evidence changed or unavailable"] }; }
+  for (const criterion of phase.criteria) if (criterion.required && criterion.result !== "verified") blockers.push(`phase criterion ${criterion.id}: ${criterion.result}`);
+  const tasks = phase.tasks.map(link => ({ id: link.id, after: [...(get(link.id)?.deps ?? [])], state: get(link.id)?.state ?? "unknown" }));
+  if (tasks.some(task => task.state !== "approved")) blockers.push("phase child tasks not approved");
+  return { workflow: "gsd-lite", id: phase.id, ready: blockers.length === 0, blockers, tasks, criteria: phase.criteria.map(c => ({ ...c, refs: [...c.refs] })) };
+}
+export function workflowHash(value: unknown): string { return createHash("sha256").update(JSON.stringify(value)).digest("hex"); }

package/src/local/sandbox.ts

@@ -105,7 +105,7 @@ export type SandboxNetwork = boolean | { proxyPort: number };
  * toolchain and project directories, writing the project and a temp dir of their own. The allow-default profile of
  * 0.9 and earlier was removed in 0.12.0 (issue #83).
  */
-export function profile(cwd: string, network: SandboxNetwork, readAllow: string[] = [], deny: string[] = []): string {
+export function profile(cwd: string, network: SandboxNetwork, readAllow: string[] = [], deny: string[] = [], readOnly: string[] = []): string {
   const home = homedir();
   const inHome = (p: string) => (p.startsWith("~/") ? join(home, p.slice(2)) : p);
   const root = realPath(cwd);
@@ -138,7 +138,7 @@ export function profile(cwd: string, network: SandboxNetwork, readAllow: string[
     "(version 1)",
     ...start,
     "(deny file-write*)",
-    `(allow file-write* (subpath ${q(root)}) (regex #"^/dev/") ${gitDirs.map((d) => `(subpath ${q(d)})`).join(" ")})`,
+    ...(readOnly.length ? ["(allow file-write* (literal \"/dev/null\"))"] : [`(allow file-write* (subpath ${q(root)}) (regex #"^/dev/") ${gitDirs.map((d) => `(subpath ${q(d)})`).join(" ")})`]),
     // Inside cwd: nothing that runs later outside the sandbox, nothing that reconfigures the hub. The .git and
     // .agenthub patterns tolerate the code points HFS+ ignores in every segment, the .git name itself is refused
     // at any depth (creation, rename, symlink, gitfile), a submodule git dir's config and hooks under
@@ -159,14 +159,16 @@ export interface ExecResult {
 }
 
 /** Run argv under seatbelt with a scrubbed environment. Never runs unsandboxed: no sandbox, no exec. */
-export function sandboxedExec(argv: string[], opts: { cwd: string; profile: string; timeoutMs?: number; env?: Record<string, string>; signal?: AbortSignal }): Promise<ExecResult> {
+export function sandboxedExec(argv: string[], opts: { cwd: string; profile: string; timeoutMs?: number; env?: Record<string, string>; signal?: AbortSignal; readOnlyData?: boolean }): Promise<ExecResult> {
+  if (opts.readOnlyData && /\(allow file-write\* \(subpath /.test(opts.profile)) return Promise.resolve({ code: null, output: "error: data.readonly command profile contains a broad write grant" });
   if (!sandboxAvailable()) return Promise.resolve({ code: null, output: "error: command execution needs macOS sandbox-exec and is disabled on this host" });
   if (opts.signal?.aborted) return Promise.resolve({ code: null, output: "error: command cancelled before execution" });
   return new Promise((resolve) => {
     // A temp dir of its own (#63): the user's is shared with every other process, and what a command reads can reach
     // an answer shown to cloud peers. Allowed after the profile's denies, and gone when the command ends.
     const own = realPath(mkdtempSync(join(tmpdir(), "ahub-cmd-")));
-    const sandbox = `${opts.profile}\n(allow file-read* file-write* process-exec (subpath ${q(own)}))`;
+    const sandbox = `${opts.profile}\n(allow file-read* ${opts.readOnlyData ? "" : "file-write* "}process-exec (subpath ${q(own)}))`;
+    // A path-only deny cannot contain hardlink aliases; data mode allows reads/stdout, never filesystem writes.
     const env = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: homedir(), LANG: process.env.LANG ?? "en_US.UTF-8", TERM: "dumb", ...opts.env, TMPDIR: `${own}/` };
     // Own process group: a timeout has to take the grandchildren too, or they keep the pipes open and the project writable.
     const child = spawn(SANDBOX_EXEC, ["-p", sandbox, ...argv], { cwd: opts.cwd, env, stdio: ["ignore", "pipe", "pipe"], detached: true });

package/src/local/tools.ts

@@ -2,6 +2,7 @@ import { lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from "nod
 import { dirname, join, relative, resolve } from "node:path";
 import { realPath } from "../hub/project.ts";
 import { isHubWritePath } from "../hub/permission-mode.ts";
+import { matchesPolicy } from "../hub/path-policy.ts";
 import { isDenied } from "./deny.ts";
 import { OUTPUT_CAP, sandboxedExec } from "./sandbox.ts";
 
@@ -17,6 +18,7 @@ const approvalError = (picked: ToolApproval, denied: string): string | undefined
   : picked === "aborted" ? "error: approval withdrawn because the turn ended; no operation was executed" : denied;
 
 export interface ToolContext {
+  readOnly?: string[];
   cwd: string;
   /** Extra denylist entries from config: substrings of the project-relative path. */
   deny: string[];
@@ -27,7 +29,7 @@ export interface ToolContext {
   /** Turn cancellation signal, including the execution-budget wall cap. */
   signal?: AbortSignal;
   /** Only true permits an effect; expiry and abort remain distinct from a person's denial. */
-  permit: (title: string, tool?: string, signal?: AbortSignal, canonicalTarget?: string, observe?: ApprovalObserver) => Promise<ToolApproval>;
+  permit: (title: string, tool?: string, signal?: AbortSignal, canonicalTarget?: string, observe?: ApprovalObserver, originalPath?: string) => Promise<ToolApproval>;
   /** Trusted process status, independent of what its stdout says. */
   onProcessExit?: (code: number | null) => void;
   /** Publish a message to other peers mid-turn. Returns a one-line receipt. */
@@ -44,7 +46,7 @@ const lexists = (p: string) => {
 };
 
 /** Absolute path inside cwd after resolving symlinks, or an Error. `write` also refuses .git and .agenthub. */
-export function guardPath(ctx: Pick<ToolContext, "cwd" | "deny">, path: string, mode: "read" | "write"): string {
+export function guardPath(ctx: Pick<ToolContext, "cwd" | "deny" | "readOnly">, path: string, mode: "read" | "write"): string {
   const root = realPath(ctx.cwd);
   const abs = resolve(root, path);
   // Resolve symlinks on the deepest part that exists: a link pointing outside must not pass as an inside path.
@@ -64,6 +66,9 @@ export function guardPath(ctx: Pick<ToolContext, "cwd" | "deny">, path: string,
   // Not secret, but writing .git or .agenthub changes what runs outside the worker's control. Names are compared
   // folded: a new `.GIT/config` is `.git/config` to a case-insensitive disk, and git then runs what it names.
   if (mode === "write" && isHubWritePath(rel)) throw new Error(`${path} is not writable by the local worker`);
+  // Identity refusal is stable even when realPath names a protected hardlink alias.
+  if (mode === "write" && ctx.readOnly?.length && (lstatSync(real, { throwIfNoEntry: false })?.nlink ?? 1) > 1) throw new Error("hardlinked write target cannot be verified with data.readonly");
+  if (mode === "write" && matchesPolicy(root, path, ctx.readOnly ?? [])) throw new Error("target is protected by data.readonly");
   return real;
 }
 
@@ -142,7 +147,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         let file = guardPath(ctx, String(a.path), "write");
         const approvedTarget = file;
         const content = String(a.content ?? "");
-        const refused = approvalError(await ctx.permit(`write ${a.path} (${content.length} chars):\n${preview(content)}`, "write", ctx.signal, file), "error: the user did not approve this write");
+        const refused = approvalError(await ctx.permit(`write ${a.path} (${content.length} chars):\n${preview(content)}`, "write", ctx.signal, file, undefined, String(a.path)), "error: the user did not approve this write");
         if (refused) return refused;
         if (ctx.signal?.aborted) return "error: turn cancelled before write";
         file = guardPath(ctx, String(a.path), "write");
@@ -157,7 +162,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         let text = readFileSync(file, "utf8");
         let count = text.split(String(a.old)).length - 1;
         if (!a.old || count !== 1) return `error: \`old\` must match exactly once, it matched ${count} times`;
-        const refused = approvalError(await ctx.permit(`edit ${a.path}:\n- ${preview(String(a.old), 600)}\n+ ${preview(String(a.new ?? ""), 600)}`, "edit", ctx.signal, file), "error: the user did not approve this edit");
+        const refused = approvalError(await ctx.permit(`edit ${a.path}:\n- ${preview(String(a.old), 600)}\n+ ${preview(String(a.new ?? ""), 600)}`, "edit", ctx.signal, file, undefined, String(a.path)), "error: the user did not approve this edit");
         if (refused) return refused;
         if (ctx.signal?.aborted) return "error: turn cancelled before edit";
         // Approval can outlive another peer's edit or a path change. Apply only the approved fragment to current bytes.
@@ -176,7 +181,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         if (command.length > 4000) return "error: command longer than 4000 characters; put it in a script file with write, then run that";
         const refused = approvalError(await ctx.permit(`bash: ${command}`, "bash", ctx.signal), "error: the user did not approve this command");
         if (refused) return refused;
-        const res = await sandboxedExec(["/bin/bash", "-c", command], { cwd: ctx.cwd, profile: ctx.sandboxProfile, timeoutMs: (Number(a.timeout_s) || 120) * 1000, ...(ctx.sandboxEnv ? { env: ctx.sandboxEnv } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
+        const res = await sandboxedExec(["/bin/bash", "-c", command], { cwd: ctx.cwd, profile: ctx.sandboxProfile, readOnlyData: !!ctx.readOnly?.length, timeoutMs: (Number(a.timeout_s) || 120) * 1000, ...(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})`;
       }
@@ -191,7 +196,7 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
           if (refused) return refused;
         }
         // 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, ...(ctx.sandboxEnv ? { env: ctx.sandboxEnv } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
+        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})`;
       }

package/src/memory/brief.ts

@@ -27,33 +27,47 @@ export async function related(client: MemoryClient, project: string, query: stri
   return out;
 }
 
+/** A native memory line for a brief (#258): `mem:<id8> <kind> <tier>: <title or text>`, fails first. */
+export interface NativeItem { id: string; line: string; kind?: string }
+export type NativeBrief = (task: BriefTask) => NativeItem[];
+export interface BriefTask { id?: number; created?: number; title: string; refs: { paths?: string[] }; plan?: { paths?: string[]; symbols?: string[] } }
+
 /**
- * Task briefs: what memory already knows about a piece of work, handed over with it. Index first (search), then the
- * neighbourhood of the top hit (timeline); details stay in claude-mem for the receiver to fetch by id. A peer is never
- * shown the same observation twice in one hub run.
+ * Task briefs: what memory already knows about a piece of work, handed over with it. The hub's own store first (#258:
+ * entries one or two hops from the task's paths, symbols, issue and task, a linked fail first, superseded entries
+ * dropped), then claude-mem: index first (search), then the neighbourhood of the top hit (timeline); details stay in
+ * the store for the receiver to fetch by id. `brief_items` caps both together. A peer is never shown the same entry
+ * twice in one hub run.
  */
 export class Briefs {
-  private readonly seen = new Map<PeerId, Set<number>>();
+  private readonly seen = new Map<PeerId, Set<string>>();
 
   constructor(
-    private readonly client: MemoryClient,
+    private readonly client: MemoryClient | undefined,
     private readonly project: string,
     private readonly maxItems = 8,
+    private readonly native?: NativeBrief,
+    /** Counts of what a brief carried, for the research records (#258 AC11); never its text. */
+    private readonly observe?: (peer: PeerId, task: number, counts: { native: number; fails: number; claudeMem: number }) => void,
   ) {}
 
-  async forTask(peer: PeerId, task: { title: string; refs: { paths?: string[] } }): Promise<string | undefined> {
-    const found = await related(this.client, this.project, [task.title, ...(task.refs.paths ?? [])].join(" "));
-    if (!found.length) return undefined;
-    const seen = this.seen.get(peer) ?? new Set<number>();
+  async forTask(peer: PeerId, task: BriefTask): Promise<string | undefined> {
+    const seen = this.seen.get(peer) ?? new Set<string>();
     this.seen.set(peer, seen);
+    const own: NativeItem[] = [];
+    try { for (const item of this.native?.(task) ?? []) if (!seen.has(item.id) && own.length < this.maxItems) own.push(item); } catch { /* fail-open: the store is optional */ }
+    const found = this.client && own.length < this.maxItems ? await related(this.client, this.project, [task.title, ...(task.refs.paths ?? [])].join(" ")) : [];
     const items: BriefItem[] = [];
     for (const item of found) {
-      if (seen.has(item.id)) continue;
+      if (seen.has(`#${item.id}`)) continue;
       items.push(item);
-      if (items.length === this.maxItems) break;
+      if (own.length + items.length === this.maxItems) break;
     }
-    if (!items.length) return undefined;
-    for (const item of items) seen.add(item.id);
-    return ["Memory brief (claude-mem; fetch details by id if you need them):", ...items.map((i) => `#${i.id} ${i.time} ${i.type} ${i.title}`)].join("\n");
+    if (!own.length && !items.length) return undefined;
+    for (const item of own) seen.add(item.id);
+    for (const item of items) seen.add(`#${item.id}`);
+    if (task.id !== undefined) try { this.observe?.(peer, task.id, { native: own.length, fails: own.filter((i) => i.kind === "fail").length, claudeMem: items.length }); } catch { /* telemetry never fails a brief */ }
+    const header = own.length ? "Memory brief (hub memory first, fails first: ahub memory show <mem id>; claude-mem by #id):" : "Memory brief (claude-mem; fetch details by id if you need them):";
+    return [header, ...own.map((i) => i.line), ...items.map((i) => `#${i.id} ${i.time} ${i.type} ${i.title}`)].join("\n");
   }
 }