@staix/agent-hub 0.12.22 → 0.12.24

package/src/hub/terminal-open.ts

@@ -0,0 +1,64 @@
+import { spawn } from "node:child_process";
+import { personEnv } from "./child-process.ts";
+import { openStartTerminal, orcaExecutable, shellQuote, startTerminalWorktree, 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 };
+export interface TerminalOpener {
+  /** Whether a start could open a terminal now; opens nothing. */
+  available(): TerminalOpened;
+  /** A terminal running `argv`, which the caller assembled from fixed words: nothing here adds to it. */
+  open(title: string, argv: readonly string[]): Promise<TerminalOpened>;
+}
+
+// ponytail: a template command still running after this long is taken to be the terminal itself, so one that fails
+// later is reported as opened; a provider-specific readiness check (as recovery has for Orca) if that ever misleads.
+const SETTLE_MS = 1500;
+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.
+ */
+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 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 (!opts.run && !Bun.which(orcaExecutable())) return { ok: false, why: `the ${orcaExecutable()} command is not on PATH` };
+    return { ok: true, via: "orca" };
+  };
+  return {
+    available,
+    async open(title, argv) {
+      const can = available();
+      if (!can.ok) return can;
+      // One command line, each word quoted for a POSIX shell: the terminal's shell runs exactly these words.
+      const command = argv.map(shellQuote).join(" ");
+      try {
+        if (can.via === "orca") {
+          await openStartTerminal(worktree()!, command, title, opts.run ? { runner: opts.run } : undefined);
+          return can;
+        }
+        // One pass with a function: a placeholder inside a substituted value (a project path that contains "{cwd}")
+        // is not expanded again, and "$" in a path is not a replacement pattern. Only {command} is shell-quoted;
+        // {title} and {cwd} are raw text for an argv element of their own.
+        const values: Record<string, string> = { command, title, cwd: opts.cwd };
+        const [bin, ...args] = opts.template.map((part) => part.replace(PLACEHOLDER, (_, name: string) => values[name]!));
+        // Detached and unwatched: the terminal is the person's and outlives the hub.
+        const child = spawn(bin!, args, { cwd: opts.cwd, env: personEnv(env), stdio: "ignore", detached: true });
+        const failed = await new Promise<string | undefined>((resolve) => {
+          const timer = setTimeout(() => resolve(undefined), SETTLE_MS); // still running: it is the terminal itself
+          child.once("error", (error) => { clearTimeout(timer); resolve(`terminal.open could not start (${(error as NodeJS.ErrnoException).code ?? "error"})`); });
+          child.once("exit", (code, signal) => { clearTimeout(timer); resolve(code === 0 ? undefined : `terminal.open exited ${signal ?? code}`); });
+        });
+        child.unref();
+        return failed ? { ok: false, why: failed } : can;
+      } catch (error) {
+        // The provider's own text can name paths and its stderr: it goes to the hub's log, not to the caller.
+        return { ok: false, why: can.via === "orca" ? "Orca could not create the terminal" : "terminal.open could not be run", detail: (error as Error).message };
+      }
+    },
+  };
+}

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,10 +1,21 @@
+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";
 
+/** What a request's session may do (#269): `settings` while a session opened by `ahub ui --settings` is inside its window. */
+export interface DashboardSession { settings: boolean; settingsUntil?: number }
 export interface DashboardOptions {
-  snapshot: (after: number, input?: Record<string, unknown>) => unknown | Promise<unknown>;
-  action: (input: Record<string, unknown>) => unknown | Promise<unknown>;
+  snapshot: (after: number, input?: Record<string, unknown>, session?: DashboardSession) => unknown | Promise<unknown>;
+  action: (input: Record<string, unknown>, session?: DashboardSession) => unknown | Promise<unknown>;
   projects?: () => unknown | Promise<unknown>;
   selectedProjectId?: string;
   /** Injectable clock for expiry tests; production uses wall time. */
@@ -13,17 +24,24 @@ export interface DashboardOptions {
 
 const TICKET_MS = 60_000;
 const SESSION_MS = 60 * 60_000;
+/** How long a session opened by `ahub ui --settings` may change settings that raise authority; it stays an ordinary session after. */
+export const SETTINGS_MS = 15 * 60_000;
 const LIMIT = 64;
 const secret = () => randomBytes(32).toString("hex");
 
 /** Separate browser surface. Only the authenticated control console may construct it and issue tickets. */
 export function startDashboard(options: DashboardOptions) {
   const now = options.now ?? Date.now;
-  const tickets = new Map<string, number>();
-  const sessions = new Map<string, number>();
+  const tickets = new Map<string, { expires: number; settings: boolean }>();
+  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("/* TASK_PROGRESS_MODEL */", () => `const taskProgress = ${taskProgress.toString()};`);
+    .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("/* 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 = {
@@ -36,14 +54,18 @@ export function startDashboard(options: DashboardOptions) {
   const json = (body: unknown, status = 200, extra: Record<string, string> = {}) =>
     new Response(JSON.stringify(body), { status, headers: { ...headers, "Content-Type": "application/json", ...extra } });
   const reject = (status: number, error: string) => json({ ok: false, error }, status);
-  function prune(map: Map<string, number>) {
-    for (const [key, expires] of map) if (expires <= now()) map.delete(key);
+  function prune(map: Map<string, { expires: number }>) {
+    for (const [key, entry] of map) if (entry.expires <= now()) map.delete(key);
   }
+  const sessionOf = (cookie: string | undefined): DashboardSession => {
+    const until = cookie ? sessions.get(cookie)?.settingsUntil : undefined;
+    return until !== undefined && until > now() ? { settings: true, settingsUntil: until } : { settings: false };
+  };
   const server = Bun.serve({
     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");
@@ -75,10 +97,11 @@ export function startDashboard(options: DashboardOptions) {
       if (path !== "/session" && (!cookie || !sessions.has(cookie))) return reject(401, "session expired; run ahub ui");
       if (path === "/session") {
         const ticket = typeof input.ticket === "string" ? input.ticket : "";
-        if (!tickets.delete(ticket)) return reject(401, "ticket expired or used; run ahub ui");
+        const issued = tickets.get(ticket);
+        if (!issued || !tickets.delete(ticket)) return reject(401, "ticket expired or used; run ahub ui");
         if (sessions.size >= LIMIT) return reject(429, "too many sessions; try later");
         const session = secret();
-        sessions.set(session, now() + SESSION_MS);
+        sessions.set(session, { expires: now() + SESSION_MS, ...(issued.settings ? { settingsUntil: now() + SETTINGS_MS } : {}) });
         return json({ ok: true }, 200, { "Set-Cookie": `${cookieName}=${session}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${SESSION_MS / 1000}` });
       }
       if (path === "/projects") {
@@ -97,7 +120,7 @@ export function startDashboard(options: DashboardOptions) {
         const after = input.after ?? 0;
         if (typeof after !== "number" || !Number.isSafeInteger(after) || after < 0) return reject(400, "invalid cursor");
         try {
-          const result = await options.snapshot(after, input);
+          const result = await options.snapshot(after, input, sessionOf(cookie));
           if (!result || typeof result !== "object" || Array.isArray(result)) return json(result);
           const response = { ...(result as Record<string, unknown>) };
           if (typeof response.projectId === "string" && typeof input.projectId === "string" && response.projectId !== input.projectId) return reject(409, "snapshot project changed; refresh the dashboard");
@@ -110,7 +133,9 @@ export function startDashboard(options: DashboardOptions) {
         }
       }
       try {
-        return json(await options.action(input));
+        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.
         return reject(400, "action failed; check its inputs and the terminal");
@@ -125,11 +150,12 @@ export function startDashboard(options: DashboardOptions) {
   const cookieName = `ahub_ui_${server.port}`;
   return {
     origin,
-    issue(): string {
+    /** `settings`: the ticket of `ahub ui --settings`, whose session may raise authority for SETTINGS_MS (#269). */
+    issue(settings = false): string {
       prune(tickets);
       if (tickets.size >= LIMIT) tickets.delete(tickets.keys().next().value!);
       const ticket = secret();
-      tickets.set(ticket, now() + TICKET_MS);
+      tickets.set(ticket, { expires: now() + TICKET_MS, settings });
       return `${origin}/#${ticket}`;
     },
     stop() {

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/deny.ts

@@ -1,4 +1,4 @@
-import { basename, sep } from "node:path";
+import { basename, dirname, sep } from "node:path";
 
 /**
  * The one denylist. tools.ts checks paths against it, sandbox.ts turns it into seatbelt rules, capture.ts keeps
@@ -50,13 +50,23 @@ const hfsFoldedName = (name: string) => `${HFS_IGNORABLE}*${[...name].map((c) =>
  * rename, symlink or gitfile, and `config` and `hooks` directly under it are folded too; the cost is that
  * `git init`, `git clone` and `git worktree add` no longer run inside the sandbox. `commondir` is refused at any
  * depth below a `.git` and below each external git dir: that is where git keeps it for linked worktrees and
- * submodules. An external git dir's `config`/`hooks` rules cover only its own children (plus the hooks
- * directory's contents): at any depth they would deny refs named `config` or `hooks` in a worktree or submodule
- * project (`git branch fix/config` fails on `.git/logs/refs/heads/fix/config`). Every pattern keeps its `^`
- * anchor (an unanchored starred alternation does not match in this engine) and no folded literal contains the
- * root: an SBPL string literal dies at 1024 bytes ("Error reading string"), which a long project path would trip.
+ * submodules. A submodule's git dir under `.git/modules/` gets the same `config`/`hooks` refusal at whatever depth
+ * submodules nest (a nested one lives under `.git/modules/<a>/modules/<b>`, #281), anchored at the discovered
+ * modules root so a directory named `refs`, `config` or `hooks` ABOVE the project neither disables the rule nor
+ * trips it; a `/refs/` or `/logs/` segment below the root keeps a branch or tag named `config` or `hooks` writable
+ * (the round-3 regression of #277), at the price of leaving a submodule whose own path holds a `refs` or `logs`
+ * segment unprotected. The basenames are folded; a folded INTERMEDIATE component on HFS+ (a spelling of `modules`)
+ * is a known residual, the same one the external git dir rules carry. The directory entries above those files are
+ * protected as the `.git` name is: the discovered git dirs, the modules root and every component in between are
+ * refused as targets (rename, replace, symlink, recreate). An external git dir's `config`/`hooks` rules cover only
+ * its own children (plus the hooks directory's contents): at any depth they would deny refs named `config` or
+ * `hooks` in a worktree or submodule project (`git branch fix/config` fails on `.git/logs/refs/heads/fix/config`).
+ * Every pattern keeps its `^` anchor (an unanchored starred alternation does not match in this engine) and no
+ * folded literal contains the root: an SBPL string literal dies at 1024 bytes ("Error reading string"), which a
+ * long project path would trip. ponytail: the modules rules do contain the (plain) modules root; a project path
+ * over roughly 600 bytes with submodules would exceed the limit — fold the root's segments if one ever shows up.
  */
-export function hubWriteRegexes(root: string, gitDirs: string[] = []): string[] {
+export function hubWriteRegexes(root: string, gitDirs: string[] = [], moduleGit?: { root: string; entries: string[] }): string[] {
   const git = hfsFoldedName(".git");
   const re = (s: string) => `(regex ${sbplString(s)})`;
   const external = gitDirs.flatMap((d) => [
@@ -64,12 +74,24 @@ export function hubWriteRegexes(root: string, gitDirs: string[] = []): string[]
     `(subpath ${sbplString(`${d}/hooks`)})`,
     `(require-all (subpath ${sbplString(d)}) ${re(`^.*/${hfsFoldedName("commondir")}$`)})`,
   ]);
+  const modules = moduleGit
+    ? [
+        // Every name matches whole components only: `(.*/)?` forces a boundary, so a submodule named `catalogs`
+        // or `prefs` keeps the refusal and one named `webhooks` keeps its ordinary writes (#281 round 2).
+        `(require-all ${re(`^${sbplEscape(moduleGit.root)}/(.*/)?${hfsFoldedName("config")}$`)} (require-not ${re(`^${sbplEscape(moduleGit.root)}/(.*/)?(refs|logs)/`)}))`,
+        `(require-all ${re(`^${sbplEscape(moduleGit.root)}/(.*/)?${hfsFoldedName("hooks")}(/|$)`)} (require-not ${re(`^${sbplEscape(moduleGit.root)}/(.*/)?(refs|logs)/`)}))`,
+        // A submodule git dir as a directory entry: no rename, replace, symlink or recreate. The basename is
+        // folded (HFS+ opens the folded spelling as the real entry); the plain prefix is the path as discovered.
+        ...moduleGit.entries.map((d) => re(`^${sbplEscape(dirname(d))}/${hfsFoldedName(basename(d))}$`)),
+      ]
+    : [];
   return [
     `(require-all (subpath ${sbplString(root)}) ${re(`^.*/${hfsFoldedName(".agenthub")}(/|$)`)})`,
     re(`^.*/${git}$`),
     re(`^.*/${git}/${hfsFoldedName("config")}$`),
     re(`^.*/${git}/${hfsFoldedName("hooks")}(/|$)`),
     `(require-all ${re(`^.*/${git}/.*$`)} ${re(`^.*/${hfsFoldedName("commondir")}$`)})`,
+    ...modules,
     ...external,
   ];
 }