@staix/agent-hub 0.20.0 → 0.22.0

package/src/cli/sdlc-output.ts

@@ -5,7 +5,7 @@
 import { duration, plural, relative, table, terminalText, wrap, type Span, type Tone } from "./console-state.ts";
 
 type Line = Span[];
-const s = (value: unknown, tone?: Tone): Span => ({ text: terminalText(value).replace(/[\n\t]/g, " "), ...(tone ? { tone } : {}) });
+export const s = (value: unknown, tone?: Tone): Span => ({ text: terminalText(value).replace(/[\n\t]/g, " "), ...(tone ? { tone } : {}) });
 const room = (columns?: number) => columns ?? Infinity;
 const list = (value: unknown): any[] => Array.isArray(value) ? value : [];
 const yes = (value: unknown) => value === true ? "yes" : value === false ? "no" : "unknown";
@@ -29,7 +29,7 @@ function para(text: string, columns: number | undefined, tone?: Tone, indent = "
  * the value does not fit in the room left of the label column, the value moves under the label instead, so a path or id
  * is broken only when it is wider than the whole terminal.
  */
-function pair(label: string, value: unknown, columns: number | undefined, labelWidth: number, tone?: Tone, indent = ""): Line[] {
+export function pair(label: string, value: unknown, columns: number | undefined, labelWidth: number, tone?: Tone, indent = ""): Line[] {
   const text = terminalText(value).replace(/[\n\t]/g, " ");
   const head = indent + label.padEnd(labelWidth) + "  ";
   const longest = Math.max(0, ...text.split(/\s+/).map(textWidth));
@@ -52,7 +52,7 @@ const textWidth = (text: string) => Bun.stringWidth(text);
  * widest cells wrap inside their column (a PR linked to thirty tasks wraps its TASKS cell, it does not push the
  * table to 134 columns); and when even each column's longest unbreakable word cannot fit, one labelled block per row.
  */
-function grid(head: string[], data: Span[][], columns: number | undefined): Line[] {
+export function grid(head: string[], data: Span[][], columns: number | undefined): Line[] {
   const natural = head.map((name, i) => Math.max(textWidth(name), ...data.map(row => textWidth(row[i]?.text ?? ""))));
   const gaps = GAP * (head.length - 1);
   if (columns === undefined || natural.reduce((sum, n) => sum + n, 0) + gaps <= columns) return table(head, data, room(columns), natural);
@@ -79,8 +79,8 @@ function blocks(head: string[], data: Span[][], columns: number): Line[] {
     ...head.slice(1).flatMap((name, i) => pair(name.toLowerCase(), row[i + 1]?.text ?? "", columns, label, row[i + 1]?.tone, "  "))]);
 }
 /** A heading wraps to the width like any paragraph; a long repository name never pushes it past the terminal. */
-const heading = (text: string, columns?: number): Line[] => wrap(text, room(columns), 2).map(line => [s(line, "strong")]);
-const blank: Line = [s("")];
+export const heading = (text: string, columns?: number): Line[] => wrap(text, room(columns), 2).map(line => [s(line, "strong")]);
+export const blank: Line = [s("")];
 const readyTone = (ready: unknown): Tone => ready === true ? "success" : "attention";
 
 // ---- sdlc status / explain ----------------------------------------------------------------------------------------
@@ -115,6 +115,12 @@ function taskBlock(row: any, columns: number | undefined, detail: boolean): Line
     out.push(...pair("tests", `${t.applicability === "bug" ? "bug fix" : t.applicability === "not_bug" ? "not a bug fix" : "bug status unknown"}, red-first ${String(t.redFirst).replace("_", " ")}, files ${t.fileState}`, columns, 11, undefined, "  "));
     out.push(...bullets("modified tests", list(t.modifiedTests), columns, undefined, "    "), ...bullets("test blockers", list(t.blockers), columns, "attention", "    "));
   }
+  const e = row.evalGate;
+  if (e) {
+    const shown = e.state === "not_configured" ? "eval check not configured (suite choice pending the person)" : e.state === "coverage_unknown" ? "PR file coverage unknown" : `${e.check} ${String(e.state)}${e.passRate !== undefined ? `, pass rate ${e.passRate}` : ""}${e.suite !== undefined ? `, suite ${e.suite}` : ""}`;
+    out.push(...pair("eval gate", `configuration PR, ${shown}`, columns, 11, e.state === "passed" && !list(e.gaps).length ? undefined : "attention", "  "));
+    out.push(...bullets("eval gaps", [...list(e.gaps), ...list(e.notes)], columns, "attention", "    "));
+  }
   const c = row.criteria;
   if (c) {
     out.push(...pair("criteria", `${c.ready ? "all met" : "not all met"}${c.id ? `, checklist ${c.id}` : ""}${c.note ? `, ${c.note}` : ""}`, columns, 11, readyTone(c.ready), "  "));
@@ -175,6 +181,12 @@ export function renderSdlcRelease(reply: unknown, columns?: number, now = Date.n
   if (a) out.push(blank, ...pair("authorization", `${a.state}: version ${a.receipt?.version ?? "unknown"} at ${short(a.receipt?.commit)}, approved ${moment(a.receipt?.at, now)}`, columns, w, a.state === "matched" ? "success" : "attention"));
   else out.push(blank, ...pair("authorization", "none recorded: run ahub sdlc authorize-release <version>", columns, w, "muted"));
   for (const t of list(r.trains)) out.push(...pair(`train #${t.release?.id ?? "?"}`, `${t.readiness?.trigger ?? "unknown"}${list(t.readiness?.blockers).length ? `, ${list(t.readiness.blockers).join("; ")}` : ""}`, columns, w, list(t.readiness?.blockers).length ? "attention" : undefined));
+  const rm = r.releaseMetrics;
+  if (rm) {
+    const mean = (values: unknown[]) => { const known = values.filter((v): v is number => typeof v === "number" && Number.isFinite(v)); return known.length ? span(known.reduce((a, b) => a + b, 0) / known.length) : "unknown"; };
+    out.push(blank, ...pair("releases", `${list(rm.intervals).length ? `interval ${mean(list(rm.intervals).map((i: any) => i.ms))} mean over ${plural(list(rm.intervals).length, "gap")}` : "interval unknown (needs two shipped releases with history)"}; lead time ${mean(list(rm.approvalToReleaseMs).map((x: any) => x.ms))} mean approval to release; hotfix rate ${percent(rm.hotfixRate)}${rm.hotfixCount === null || rm.hotfixCount === undefined ? "" : ` (${rm.hotfixCount})`}`, columns, w));
+    if (list(rm.unknown).length) out.push(...pair("unknown", `${plural(list(rm.unknown).length, "release")} without complete history: ${list(rm.unknown).map((id: number) => `#${id}`).join(", ")}`, columns, w, "attention", "  "));
+  }
   out.push(...bullets("blockers", list(r.blockers), columns, "attention"));
   return out;
 }
@@ -184,6 +196,7 @@ export function renderSdlcRelease(reply: unknown, columns?: number, now = Date.n
 const SUMMARY_ROWS: [string, string, boolean][] = [
   ["acceptance_to_plan_ms", "acceptance to plan", true], ["acceptance_to_first_review_ms", "acceptance to first review", true], ["acceptance_to_merge_ms", "acceptance to merge", true],
   ["rework_rounds", "rework rounds", false], ["same_head_ci_reruns", "same-head CI reruns", false], ["stale_head_re_reviews", "stale-head re-reviews", false],
+  ["review_rounds_at_merge", "review rounds at merge", false], ["ci_runs_at_merge", "CI runs at merge", false], ["github_reviews_at_merge", "GitHub reviews at merge", false],
 ];
 const BAND_TONE: Record<string, Tone> = { ok: "success", log: "muted", diagnose: "attention", propose: "failure" };
 /** `ahub sdlc metrics [--since ...]`: times and counts from board history, the two approval rates, stalls and band tiers. */
@@ -206,7 +219,7 @@ export function renderSdlcMetrics(result: unknown, columns?: number, now = Date.
   if (st) out.push(blank, ...pair("stalls", `${st.open ?? 0} open${Object.keys(st.byKind ?? {}).length ? ` (${Object.entries(st.byKind).map(([k, n]) => `${k} ${n}`).join(", ")})` : ""}, ${st.doneWithoutWrites ?? 0} done without writes`, columns, 10, st.open ? "attention" : undefined));
   if (m?.bands === "off" || m?.bands === undefined) out.push(...pair("bands", "off", columns, 10, "muted"));
   else {
-    out.push(blank, ...grid(["BAND", "TIER", "BASELINE", "LAST", "Z", "TASK"], list(m.bands).map((b: any) => [s(String(b.metric).replaceAll("_", " ")), s(b.tier, BAND_TONE[b.tier] ?? undefined), s(count(b.baseline)), s(count(b.last)), s(count(b.z)), s(b.lastTask ? `#${b.lastTask}` : "-", "taskRef")]), columns));
+    out.push(blank, ...grid(["BAND", "TIER", "BASELINE", "LAST", "Z", "SUBJECT"], list(m.bands).map((b: any) => [s(String(b.metric).replaceAll("_", " ")), s(b.tier, BAND_TONE[b.tier] ?? undefined), s(count(b.baseline)), s(count(b.last)), s(count(b.z)), s(b.lastTask ? `${b.subject === "release" ? "release " : b.subject === "scan" ? "scan " : ""}#${b.lastTask}` : "-", "taskRef")]), columns));
     for (const b of list(m.bands)) if (b.reason && b.tier !== "ok") out.push(...para(`${String(b.metric).replaceAll("_", " ")}: ${b.reason}`, columns, "muted", "  ", 2));
   }
   return out;
@@ -240,3 +253,28 @@ export function renderAuthorization(authorization: unknown, columns?: number, no
     ...pair("id", a?.id ?? "unknown", columns, w, "muted"), blank,
     ...para("A daemon restart revokes this authorization.", columns, "muted")];
 }
+
+// ---- sdlc merge ---------------------------------------------------------------------------------------------------
+
+const MERGE_STATE: Record<string, [string, Tone]> = { merged: ["merged", "success"], not_merged: ["not merged", "failure"], unknown: ["merge state unknown", "attention"] };
+/** `ahub sdlc merge <task> [--dry-run]` (#899): the hub's decision, every gate that refused it, the `gh` command, and GitHub's readback after a run. */
+export function renderSdlcMerge(view: unknown, columns?: number, _now = Date.now()): Span[][] {
+  const v = view as any;
+  const w = 8, refused = list(v?.refused), argv = list(v?.argv);
+  const out: Line[] = [...heading(`Guarded merge of task #${v?.task ?? "unknown"}`, columns)];
+  out.push(...pair("mode", v?.mode ?? "unknown", columns, w, v?.mode === "off" ? "attention" : undefined));
+  if (v?.decision === "merge") out.push(...pair("decision", "merge: every gate passed", columns, w, "success"));
+  else if (v?.decision === "refused") out.push(...pair("decision", `refused by ${plural(refused.length, "gate")}`, columns, w, "attention"));
+  else out.push(...pair("decision", "unknown", columns, w, "attention"));
+  out.push(...bullets("refused", refused, columns, "attention", "  "));
+  if (argv.length) out.push(...pair("command", `gh ${argv.join(" ")}`, columns, w));
+  const ran = v?.ran === true ? "yes" : v?.ran === false ? (v?.mode === "dry-run" && argv.length ? "no (dry run: the command above was not run)" : "no") : "unknown";
+  out.push(...pair("ran", ran, columns, w, v?.ran === true ? undefined : "muted"));
+  const r = v?.result;
+  if (r && typeof r === "object") {
+    const [state, tone] = MERGE_STATE[String(r.state)] ?? ["merge state unknown", "attention" as Tone];
+    out.push(blank, ...pair("result", `${state}, gh exit ${count(r.exit)}${r.mergeCommit ? `, merge commit ${short(r.mergeCommit)}` : ""}`, columns, w, tone));
+    if (r.cleanup) out.push(...pair("cleanup", `branch cleanup ${String(r.cleanup).replaceAll("_", " ")}${r.reason ? ` (${String(r.reason).replaceAll("_", " ")})` : ""}`, columns, w, r.cleanup === "deleted" ? undefined : "muted"));
+  }
+  return out;
+}

package/src/cli/smoke-pty-bridge.ts

@@ -0,0 +1,82 @@
+// macOS script(1) requires a terminal on its own stdin, including when its child gets a PTY.
+// Keep a real PTY in this owned bridge instead; the outer Node child remains tracked by stopOwnedProcess.
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * #560: Bun up to 1.4.3 can hang for good inside `Bun.spawn({ terminal })` on macOS when the child writes and starts exiting before the call returns (oven-sh/bun#45300, fixed in 1.4.4): the
+ * event loop thread blocks in wait4 while the exiting session leader waits for that same thread to drain its pty. Measured here with a bare Bun script and no agent-hub code: 26 of 96 runs hung
+ * at 12 in parallel on 1.4.3 and 0 of 180 on 1.4.4. The child therefore starts behind a gate: a shell that waits for a file the bridge writes right after `Bun.spawn` has returned, then `exec`s the
+ * real command (same pid, same session, same terminal). The wait has no bound of its own: a bridge that dies before it opens the gate closes the pty, which hangs the shell up (the trap below), and a bridge
+ * that is alive but never opens it is a hung bridge, which `runPty` stops with its group.
+ * ponytail: ceiling and upgrade path. The gate exists only because of oven-sh/bun#45300 on Bun up to 1.4.3 (this repo pins 1.4.2 in `.bun-version`); the upgrade path is to delete GATE_SCRIPT, `gate` and `gateDir` once the pinned Bun is 1.4.4 or newer, which is its own task because it
+ * touches CI and every OS leg. The parent-death stop below stays whatever the Bun version: an orphaned bridge is this repository's bug, not Bun's. The gate costs about one shell start (a few ms).
+ */
+// The shell removes its own gate (file, then directory) once released and when it is hung up or terminated (a bridge killed with SIGKILL runs no cleanup, and the pty closing
+// sends the shell SIGHUP), so no path leaves a directory behind. `exec` resets the traps for the real command.
+const GATE_SCRIPT = 'd=${0%/*}; trap "rm -f \\"$0\\"; rmdir \\"$d\\" 2>/dev/null; exit 125" HUP TERM INT; while [ ! -e "$0" ]; do sleep 0.01; done; rm -f "$0"; rmdir "$d" 2>/dev/null; exec "$@"';
+/** A bridge whose caller died is stopped instead of running on: its child holds a terminal nobody reads and, under launchd, nothing else would ever stop it. */
+const PARENT_POLL_MS = 250;
+const PARENT_TERM_GRACE_MS = 1_000;
+const PARENT_HARD_EXIT_MS = 3_000;
+
+// The caller is whoever started this bridge, read before anything that can take time: a caller that dies while `Bun.spawn` runs (the window #45300 widens) has already reparented this process by the
+// time the call returns, and a parent read after it would be launchd and never change.
+const parent = process.ppid;
+const callerGone = (): boolean => process.ppid !== parent;
+const argv = process.argv.slice(2);
+if (!argv.length) {
+  process.exitCode = 125;
+} else {
+  let streamClosed!: () => void;
+  const eof = new Promise<void>(resolve => { streamClosed = resolve; });
+  const gateDir = process.platform === "darwin" ? mkdtempSync(join(tmpdir(), "ahub-pty-gate-")) : undefined;
+  const gate = gateDir ? join(gateDir, "open") : undefined;
+  let watch: ReturnType<typeof setInterval> | undefined;
+  try {
+    const child = Bun.spawn(gate ? ["/bin/sh", "-c", GATE_SCRIPT, gate, ...argv] : argv, {
+      cwd: process.cwd(), env: process.env,
+      terminal: {
+        cols: 120, rows: 40, name: "xterm-256color",
+        data: (_terminal, data) => { process.stdout.write(data); },
+        exit: () => streamClosed(),
+      },
+    });
+    const stop = () => { try { child.kill("SIGTERM"); } catch { /* exit readback decides */ } };
+    process.on("SIGINT", stop); process.on("SIGTERM", stop);
+    /** The caller is gone: stop the child now, kill it after a grace period, and exit even if its exit is never reported. */
+    const abandon = () => {
+      clearInterval(watch);
+      stop();
+      setTimeout(() => { try { child.kill("SIGKILL"); } catch { /* already gone */ } }, PARENT_TERM_GRACE_MS).unref();
+      setTimeout(() => process.exit(129), PARENT_HARD_EXIT_MS).unref();
+    };
+    // A caller that died while Bun.spawn ran never gets its command run: the gate stays shut and the gate shell takes the SIGTERM (its trap removes the gate and exits).
+    // Abandoning once is enough: the interval below exists only while the caller is still there, and clears itself the first time it is not.
+    if (callerGone()) abandon();
+    else {
+      if (gate) writeFileSync(gate, "");
+      watch = setInterval(() => { if (callerGone()) abandon(); }, PARENT_POLL_MS);
+    }
+    try {
+      const code = await child.exited;
+      // Drain the PTY before closing it; a descendant holding a slave cannot make the bridge wait forever.
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      await Promise.race([eof, new Promise<void>(resolve => { timer = setTimeout(resolve, 250); })]);
+      if (timer) clearTimeout(timer);
+      process.exitCode = code;
+    } catch {
+      process.exitCode = 125;
+    } finally {
+      child.terminal?.close();
+      process.removeListener("SIGINT", stop); process.removeListener("SIGTERM", stop);
+    }
+  } catch {
+    process.exitCode = 125;
+  } finally {
+    if (watch) clearInterval(watch);
+    if (gateDir) rmSync(gateDir, { recursive: true, force: true });
+  }
+}
+export {};

package/src/cli/smoke-pty.ts

@@ -0,0 +1,153 @@
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { shellQuote } from "./shell-quote.ts";
+import type { ChildProcess } from "node:child_process";
+import { stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+
+export const MAX_PTY_OUTPUT_BYTES = 1024 * 1024;
+const MIN_TIMEOUT_MS = 100;
+const MAX_TIMEOUT_MS = 120_000;
+const SCRIPT = "/usr/bin/script";
+const PTY_COMMAND = '/bin/stty rows 40 cols 120 || exit 125; exec "$@"';
+
+export interface PtyOptions {
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  timeoutMs: number;
+  onOutput?: (chunk: Buffer) => void;
+  signal?: AbortSignal;
+  ready?: () => Promise<void>;
+}
+
+export interface PtyResult {
+  outcome: "exited" | "completed" | "timeout" | "aborted" | "failed";
+  exitCode: number | null;
+  outputBytes: number;
+  elapsedMs: number;
+  cleaned: boolean;
+}
+
+type Outcome = PtyResult["outcome"];
+type Winner = { outcome: Outcome };
+
+
+function commandFor(argv: readonly string[]): string[] {
+  const command = process.platform === "darwin"
+    ? [process.execPath, join(import.meta.dir, "smoke-pty-bridge.ts"), ...argv]
+    : [SCRIPT, "-q", "-e", "-f", "-c", ["/bin/sh", "-c", PTY_COMMAND, "ahub-pty", ...argv].map(shellQuote).join(" "), "/dev/null"];
+  return command;
+}
+
+function validate(argv: readonly string[], options: PtyOptions): void {
+  if (!Array.isArray(argv) || argv.length === 0 || argv.some(arg => typeof arg !== "string" || arg.includes("\0")) || !argv[0]) throw new Error("invalid PTY command");
+  if (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs < MIN_TIMEOUT_MS || options.timeoutMs > MAX_TIMEOUT_MS) throw new Error("invalid PTY timeout");
+  if (typeof options.cwd !== "string" || !options.cwd || !options.env || typeof options.env !== "object") throw new Error("invalid PTY environment");
+  if (process.platform !== "darwin" && process.platform !== "linux") throw new Error("PTY smoke runner is unsupported on this platform");
+}
+
+function waitForExit(proc: ChildProcess): Promise<{ code: number | null }> {
+  return new Promise(resolve => {
+    if (proc.exitCode !== null || proc.signalCode !== null) { resolve({ code: proc.exitCode }); return; }
+    proc.once("exit", code => resolve({ code }));
+    proc.once("error", () => resolve({ code: null }));
+  });
+}
+
+/** Run an argv vector inside a fixed-size PTY, always stopping its owned process group before returning. */
+export function runPty(argv: readonly string[], options: PtyOptions): Promise<PtyResult> {
+  return runPtyWith(commandFor, argv, options);
+}
+
+/**
+ * `runPty` with the launcher named by the caller. Only code can reach it (a test names a bridge that ignores SIGTERM or never exits); no config key, request or environment variable does, so the
+ * bridge a hub runs is always `commandFor`'s.
+ */
+export async function runPtyWith(launcher: (argv: readonly string[]) => string[], argv: readonly string[], options: PtyOptions): Promise<PtyResult> {
+  validate(argv, options);
+  const started = Date.now();
+  if (options.signal?.aborted) return { outcome: "aborted", exitCode: null, outputBytes: 0, elapsedMs: Date.now() - started, cleaned: true };
+
+  let proc: ChildProcess;
+  try {
+    const command = launcher(argv);
+    proc = spawn(command[0]!, command.slice(1), {
+      cwd: options.cwd,
+      env: { ...options.env, TERM: "xterm-256color" },
+      detached: true,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch {
+    throw new Error("PTY process could not be started");
+  }
+  trackGroup(proc);
+  const closed = new Promise<void>(resolve => proc.once("close", () => resolve()));
+
+  let outputBytes = 0, outputFailure: Error | undefined;
+  const drain = (chunk: Buffer) => {
+    outputBytes += chunk.length;
+    const room = Math.max(0, MAX_PTY_OUTPUT_BYTES - (outputBytes - chunk.length));
+    if (room > 0 && options.onOutput) {
+      try { options.onOutput(chunk.subarray(0, Math.min(room, chunk.length))); }
+      catch { outputFailure = new Error("PTY output handler failed"); }
+    }
+    if (outputBytes > MAX_PTY_OUTPUT_BYTES) outputFailure = new Error("PTY output exceeded 1 MiB");
+  };
+  proc.stdout?.on("data", drain);
+  proc.stderr?.on("data", drain);
+
+  let exitCode: number | null = null;
+  const exited = waitForExit(proc).then(value => { exitCode = value.code; return { outcome: "exited" as const }; });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let abortListener: (() => void) | undefined;
+  const interrupted = new Promise<Winner>(resolve => {
+    timer = setTimeout(() => resolve({ outcome: "timeout" }), options.timeoutMs);
+    options.signal?.addEventListener("abort", abortListener = () => resolve({ outcome: "aborted" }), { once: true });
+    if (options.signal?.aborted) resolve({ outcome: "aborted" });
+  });
+  const spawned = new Promise<void>((resolve, reject) => {
+    if (proc.pid !== undefined) { resolve(); return; }
+    proc.once("spawn", () => resolve());
+    proc.once("error", () => reject());
+  });
+
+  let winner: Winner;
+  let cleaned = false;
+  try {
+    const beforeStart = await Promise.race([spawned.then(() => ({ outcome: "started" as const })), interrupted]);
+    if (beforeStart.outcome !== "started") winner = beforeStart;
+    else if (proc.exitCode !== null || proc.signalCode !== null) winner = { outcome: "exited" };
+    else {
+      const ready = options.ready ? Promise.resolve().then(async (): Promise<Winner> => {
+        if (proc.exitCode !== null || proc.signalCode !== null) return { outcome: "exited" as const };
+        await options.ready!();
+        return { outcome: "completed" };
+      }).catch(() => ({ outcome: "failed" as const })) : undefined;
+      const failures = new Promise<Winner>(resolve => {
+        const check = () => { if (outputFailure) resolve({ outcome: "failed" }); };
+        proc.stdout?.on("data", check);
+        proc.stderr?.on("data", check);
+        check();
+      });
+      winner = await Promise.race([exited, interrupted, failures, ...(ready ? [ready] : [])]);
+    }
+  } catch {
+    winner = { outcome: "failed" };
+  }
+
+  if (timer) clearTimeout(timer);
+  if (abortListener) options.signal?.removeEventListener("abort", abortListener);
+  if (proc.pid === undefined) await spawned.catch(() => {});
+  try {
+    await stopOwnedProcess(proc, { group: true });
+    cleaned = true;
+  } catch {
+    cleaned = false;
+  }
+  let closeTimer: ReturnType<typeof setTimeout> | undefined;
+  await Promise.race([closed, new Promise<void>(resolve => { closeTimer = setTimeout(resolve, 250); })]);
+  if (closeTimer) clearTimeout(closeTimer);
+  // The owned-group stop drops pipes, but the close event is only a bounded best-effort drain barrier.
+  if (outputFailure) winner = { outcome: "failed" };
+  if (!cleaned && winner.outcome !== "timeout" && winner.outcome !== "aborted") winner = { outcome: "failed" };
+  return { outcome: winner.outcome, exitCode: exitCode ?? proc.exitCode, outputBytes, elapsedMs: Date.now() - started, cleaned };
+}

package/src/cli/smoke-run.ts

@@ -0,0 +1,139 @@
+import { closeSync, constants, existsSync, fstatSync, mkdirSync, mkdtempSync, openSync, readSync, rmSync, writeFileSync, writeSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { assessVersion } from "../adapters/compat.ts";
+import { hubGitSync } from "../hub/git.ts";
+import { realPath } from "../hub/project.ts";
+import { runPty } from "./smoke-pty.ts";
+import type { SmokeTarget } from "./smoke-target.ts";
+
+export interface SmokeReceipt {
+  schemaVersion: 1;
+  leg: "qwen-dual-output";
+  outcome: "passed" | "failed" | "timeout";
+  reason: "complete" | "protocol" | "timeout" | "cleanup" | "aborted";
+  checks: { disposable: boolean; protocol: boolean; queued: boolean; cleaned: boolean };
+  counts: { submits: number; users: number; assistants: number; stops: number; events: number; terminalBytes: number };
+  timings: { totalMs: number; protocolMs: number | null };
+}
+export interface SmokeOptions { leg: "qwen-dual-output"; receipt: string; timeoutMs: number; signal?: AbortSignal }
+/** Host-only test ports, never loaded from project configuration or accepted as CLI arguments. */
+export interface SmokePorts { command?: readonly string[]; env?: NodeJS.ProcessEnv }
+const FIRST = "AHUB_SMOKE_FIRST", SECOND = "AHUB_SMOKE_SECOND";
+const FIRST_PROMPT = `Print ${FIRST} once, then list 64 short numbered lines. Do not use any tools.`;
+const SECOND_PROMPT = `Reply with exactly ${SECOND}. Do not use any tools.`;
+const protocolError = () => new Error("smoke protocol refused");
+const inside = (root: string, value: string) => { const name = relative(root, value); return !!name && !isAbsolute(name) && name !== ".." && !name.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`); };
+
+/** No model-selected commands, prompts or persisted output: this is one fixed Q2 protocol leg. */
+export async function runSmoke(target: SmokeTarget, options: SmokeOptions, ports: SmokePorts = {}): Promise<SmokeReceipt> {
+  target.check();
+  if (options.leg !== "qwen-dual-output" || !Number.isSafeInteger(options.timeoutMs) || options.timeoutMs < 100 || options.timeoutMs > 120_000) throw new Error("smoke arguments refused");
+  const receiptPath = resolve(target.cwd, options.receipt), parent = dirname(receiptPath);
+  if (!inside(target.cwd, receiptPath) || parent !== target.cwd || realPath(parent) !== parent || existsSync(receiptPath)) throw new Error("smoke receipt refused");
+  const source = ports.env ?? process.env;
+  if (!source.OPENAI_API_KEY?.trim() || !source.OPENAI_BASE_URL?.trim() || !source.OPENAI_MODEL?.trim()) throw new Error("smoke prerequisites unavailable");
+  let endpoint: URL;
+  try { endpoint = new URL(source.OPENAI_BASE_URL); } catch { throw new Error("smoke prerequisites unavailable"); }
+  if (endpoint.username || endpoint.password || !["https:", "http:"].includes(endpoint.protocol)) throw new Error("smoke prerequisites unavailable");
+  const command = ports.command ?? [Bun.which("qwen", { PATH: source.PATH }) ?? ""];
+  if (!command.length || !command[0]) throw new Error("smoke prerequisites unavailable");
+  const started = performance.now();
+  const receipt: SmokeReceipt = { schemaVersion: 1, leg: "qwen-dual-output", outcome: "failed", reason: "protocol", checks: { disposable: true, protocol: false, queued: false, cleaned: true }, counts: { submits: 0, users: 0, assistants: 0, stops: 0, events: 0, terminalBytes: 0 }, timings: { totalMs: 0, protocolMs: null } };
+  target.check();
+  const run = mkdtempSync(join(target.cwd, ".smoke-run-"));
+  const home = join(run, "home"), cwd = join(run, "project"), temporary = join(run, "tmp");
+  for (const dir of [home, cwd, temporary, join(home, ".qwen")]) mkdirSync(dir, { mode: 0o700 });
+  let cleaned = true, protocolMs: number | null = null;
+  try {
+    const git = hubGitSync(["-c", "init.templateDir=", "init", "-q", cwd], { encoding: "utf8" });
+    if (git.status !== 0) throw protocolError();
+    writeFileSync(join(home, ".qwen", "settings.json"), JSON.stringify({ security: { auth: { selectedType: "openai" } }, general: { disableAutoUpdate: true, disableUpdateNag: true }, privacy: { usageStatisticsEnabled: false }, telemetry: { enabled: false }, mcpServers: {} }), { mode: 0o600, flag: "wx" });
+    const input = join(run, "input.jsonl"), events = join(run, "events.jsonl"), mcp = join(run, "mcp.json");
+    for (const file of [input, events]) writeFileSync(file, "", { mode: 0o600, flag: "wx" });
+    writeFileSync(mcp, JSON.stringify({ mcpServers: {} }), { mode: 0o600, flag: "wx" });
+    const env: NodeJS.ProcessEnv = { HOME: home, XDG_CONFIG_HOME: join(home, ".config"), XDG_CACHE_HOME: join(home, ".cache"), XDG_DATA_HOME: join(home, ".local", "share"), PATH: source.PATH ?? "", TERM: "xterm-256color", LANG: "en_US.UTF-8", TMPDIR: temporary, OPENAI_API_KEY: source.OPENAI_API_KEY, OPENAI_BASE_URL: source.OPENAI_BASE_URL, OPENAI_MODEL: source.OPENAI_MODEL, QWEN_USAGE_STATISTICS_ENABLED: "false", NO_COLOR: "1" };
+    const fd = openSync(events, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const inputFd = openSync(input, constants.O_WRONLY | constants.O_APPEND | constants.O_NOFOLLOW);
+    const decoder = new TextDecoder();
+    let position = 0, partial = "", announced = false, assistant = false, queued = false, queueCandidate = false;
+    const protocolStop = new AbortController();
+    const protocolStarted = performance.now();
+    const deadline = protocolStarted + options.timeoutMs;
+    const submit = (text: string, window?: () => boolean) => { target.check(); if (window && !window()) return false; if (!fstatSync(inputFd).isFile() || fstatSync(inputFd).nlink !== 1) throw protocolError(); writeSync(inputFd, JSON.stringify({ type: "submit", text }) + "\n"); receipt.counts.submits++; return true; };
+    try {
+      target.check(); cleaned = false; receipt.checks.cleaned = false;
+      const result = await runPty([...command, "--input-file", input, "--json-file", events, "--mcp-config", mcp, "--approval-mode", "default", "--auth-type", "openai", "--model", source.OPENAI_MODEL], { cwd, env, timeoutMs: options.timeoutMs, signal: options.signal, ready: async () => {
+        try {
+          while (performance.now() < deadline && !options.signal?.aborted && !protocolStop.signal.aborted) {
+            const info = fstatSync(fd);
+            if (!info.isFile() || info.nlink !== 1 || info.size < position || info.size > 8 * 1024 * 1024) throw protocolError();
+            if (position < info.size) {
+              const chunk = Buffer.alloc(Math.min(64 * 1024, info.size - position));
+              const got = readSync(fd, chunk, 0, chunk.length, position); position += got;
+              partial += decoder.decode(chunk.subarray(0, got), { stream: true });
+              if (Buffer.byteLength(partial) > 128 * 1024) throw protocolError();
+              let newline: number;
+              while ((newline = partial.indexOf("\n")) >= 0) {
+                const line = partial.slice(0, newline); partial = partial.slice(newline + 1);
+                if (!line.trim()) continue;
+                if (Buffer.byteLength(line) > 64 * 1024) throw protocolError();
+                let event: any; try { event = JSON.parse(line); } catch { throw protocolError(); }
+                receipt.counts.events++;
+                if (!event || typeof event !== "object" || Array.isArray(event)) throw protocolError();
+                if (event.type === "control_request") throw protocolError(); // this read-only leg never answers approvals
+                if (event.type === "system" && event.subtype === "session_start") {
+                  if (announced || event.data?.protocol_version !== 2 || !assessVersion("qwen-dual", event.data?.version).ok || !Array.isArray(event.data?.supported_events) || !["user", "assistant", "stream_event"].every(name => event.data.supported_events.includes(name))) throw protocolError();
+                  announced = true; submit(FIRST_PROMPT);
+                } else if (event.type === "user") {
+                  if (!announced || receipt.counts.users >= receipt.counts.submits || receipt.counts.users === 1 && receipt.counts.stops !== 1) throw protocolError();
+                  const content = event.message?.content;
+                  const text = typeof content === "string" ? content : Array.isArray(content) ? content.filter((b: any) => b?.type === "text" && typeof b.text === "string").map((b: any) => b.text).join("") : "";
+                  if (text.trim() !== (receipt.counts.users === 0 ? FIRST_PROMPT : SECOND_PROMPT)) throw protocolError();
+                  receipt.counts.users++;
+                } else if (event.type === "assistant") {
+                  const blocks = event.message?.content;
+                  const text = Array.isArray(blocks) ? blocks.filter((b: any) => b?.type === "text" && typeof b.text === "string").map((b: any) => b.text).join("") : "";
+                  if (event.message?.stop_reason === "tool_use" || !text.includes(receipt.counts.stops === 0 ? FIRST : SECOND) || receipt.counts.users !== receipt.counts.stops + 1 || assistant) throw protocolError();
+                  assistant = true; receipt.counts.assistants++;
+                } else if (event.type === "stream_event") {
+                  if (!event.event || typeof event.event.type !== "string") throw protocolError();
+                  if (event.event?.type === "message_stop") {
+                    if (!assistant || receipt.counts.stops === 0 && !queued) throw protocolError();
+                    assistant = false; receipt.counts.stops++;
+                    if (receipt.counts.stops === 2) { receipt.checks.protocol = true; receipt.checks.queued = queued; return; }
+                  } else if (receipt.counts.users === 1 && !queued && ["message_start", "content_block_start", "content_block_delta"].includes(event.event.type)) {
+                    queueCandidate = true;
+                  }
+                }
+              }
+              // Consume everything already published before calling a still-running turn queued.
+              if (position < info.size) continue;
+              if (queueCandidate && !queued && partial.length === 0) {
+                if (submit(SECOND_PROMPT, () => fstatSync(fd).size === position)) { queued = true; queueCandidate = false; }
+              }
+            }
+            await Bun.sleep(20);
+          }
+          throw protocolError();
+        } finally { protocolMs = Math.round(performance.now() - protocolStarted); }
+      } });
+      receipt.counts.terminalBytes = result.outputBytes;
+      receipt.checks.cleaned = result.cleaned;
+      cleaned = result.cleaned;
+      if (result.outcome === "completed" && receipt.checks.protocol && receipt.checks.queued && result.cleaned) { receipt.outcome = "passed"; receipt.reason = "complete"; }
+      else if (result.outcome === "timeout" || !receipt.checks.protocol && performance.now() >= deadline) { receipt.outcome = "timeout"; receipt.reason = "timeout"; }
+      else if (result.outcome === "aborted") receipt.reason = "aborted";
+    } finally { protocolStop.abort(); closeSync(fd); closeSync(inputFd); }
+  } catch { receipt.reason = "protocol"; }
+  finally {
+    // Remove only the directory this invocation made, after all owned processes were confirmed stopped.
+    if (cleaned) rmSync(run, { recursive: true, force: true });
+  }
+  receipt.timings.totalMs = Math.round(performance.now() - started);
+  receipt.timings.protocolMs = protocolMs;
+  if (!receipt.checks.cleaned) { receipt.outcome = "failed"; receipt.reason = "cleanup"; }
+  target.check();
+  try { writeFileSync(receiptPath, JSON.stringify(receipt, null, 2) + "\n", { mode: 0o600, flag: "wx" }); }
+  catch { throw new Error("smoke receipt refused"); }
+  return receipt;
+}

package/src/cli/smoke-target.ts

@@ -0,0 +1,130 @@
+import { lstatSync, type Stats } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import type { Project } from "../hub/registry.ts";
+import { hubGitSync } from "../hub/git.ts";
+import { realPath } from "../hub/project.ts";
+
+const REFUSAL = "smoke target refused";
+
+export interface SmokeTarget {
+  cwd: string;
+  hubHome: string;
+  stateDir: string;
+  projectId: string;
+  check(): void;
+}
+
+type Identity = { dev: number; ino: number };
+type Snapshot = { cwd: string; hubHome: string; stateDir: string; projectId: string; identities: { cwd: Identity; git: Identity; home: Identity; state: Identity } };
+
+function refuse(): never { throw new Error(REFUSAL); }
+
+function realDirectory(path: string): { path: string; stat: Stats } {
+  if (!isAbsolute(path)) refuse();
+  assertNoSymlink(path);
+  const canonical = realPath(path);
+  const stat = lstatSync(canonical);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) refuse();
+  return { path: canonical, stat };
+}
+
+/** Check the caller's spelling too: resolving a symlink before the check would hide a redirected path. */
+function assertNoSymlink(path: string): void {
+  if (path.split(sep).includes("..")) refuse();
+  const absolute = resolve(path);
+  const root = parse(absolute).root;
+  let current = root;
+  for (const segment of absolute.slice(root.length).split(sep).filter(Boolean)) {
+    current = join(current, segment);
+    const stat = lstatSync(current);
+    if (stat.isSymbolicLink()) refuse();
+  }
+  if (lstatSync(root).isSymbolicLink()) refuse();
+}
+
+function inside(root: string, child: string): boolean {
+  const rel = relative(root, child);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+function identity(stat: Stats): Identity { return { dev: stat.dev, ino: stat.ino }; }
+function sameIdentity(a: Identity, b: Identity): boolean { return a.dev === b.dev && a.ino === b.ino; }
+
+function gitPath(cwd: string, args: string[]): string {
+  const result = hubGitSync(["-C", cwd, ...args], { encoding: "utf8", timeout: 2000, maxBuffer: 64 * 1024 });
+  if (result.status !== 0) refuse();
+  const path = result.stdout.trim();
+  if (!path) refuse();
+  return realPath(path);
+}
+
+function inspect(input: {
+  cwd: string;
+  hubHome: string;
+  project: Pick<Project, "id" | "root" | "stateDir">;
+  expectedProjectId: string;
+  liveTest: boolean;
+}): Snapshot {
+  if (input.liveTest !== true || !input.expectedProjectId || input.project.id !== input.expectedProjectId) refuse();
+
+  const root = realDirectory(input.cwd);
+  const registeredRoot = realDirectory(input.project.root);
+  if (root.path !== registeredRoot.path) refuse();
+
+  const tempRoot = realPath(tmpdir());
+  const temp = realDirectory(tempRoot);
+  if (dirname(root.path) !== temp.path || !basename(root.path).startsWith("ahub-smoke-") || root.path === temp.path) refuse();
+  const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+  if (uid !== undefined && root.stat.uid !== uid) refuse();
+
+  const gitDirPath = join(root.path, ".git");
+  const gitDir = lstatSync(gitDirPath);
+  if (gitDir.isSymbolicLink() || !gitDir.isDirectory()) refuse();
+  if (gitPath(root.path, ["rev-parse", "--show-toplevel"]) !== root.path) refuse();
+  if (gitPath(root.path, ["rev-parse", "--path-format=absolute", "--git-common-dir"]) !== gitDirPath) refuse();
+
+  // ponytail: first slice accepts an uncommitted, untracked scratch index only; a future explicit disposable manifest can admit fixture histories.
+  for (const args of [["for-each-ref", "--count=1", "--format=%(refname)"], ["ls-files"], ["remote"]]) {
+    const result = hubGitSync(["-C", root.path, ...args], { encoding: "utf8", timeout: 2000, maxBuffer: 64 * 1024 });
+    if (result.status !== 0 || result.stdout.trim()) refuse();
+  }
+
+  const home = realDirectory(input.hubHome);
+  const state = realDirectory(input.project.stateDir);
+  if (!inside(root.path, home.path) || !inside(root.path, state.path)) refuse();
+
+  return {
+    cwd: root.path,
+    hubHome: home.path,
+    stateDir: state.path,
+    projectId: input.project.id,
+    identities: { cwd: identity(root.stat), git: identity(gitDir), home: identity(home.stat), state: identity(state.stat) },
+  };
+}
+
+export function validateSmokeTarget(input: {
+  cwd: string;
+  hubHome: string;
+  project: Pick<Project, "id" | "root" | "stateDir">;
+  expectedProjectId: string;
+  liveTest: boolean;
+}): SmokeTarget {
+  let original: Snapshot;
+  try { original = inspect(input); } catch { return refuse(); }
+  return {
+    cwd: original.cwd,
+    hubHome: original.hubHome,
+    stateDir: original.stateDir,
+    projectId: original.projectId,
+    check() {
+      try {
+        const current = inspect(input);
+        if (current.cwd !== original.cwd || current.hubHome !== original.hubHome || current.stateDir !== original.stateDir
+          || current.projectId !== original.projectId || !sameIdentity(current.identities.cwd, original.identities.cwd)
+          || !sameIdentity(current.identities.git, original.identities.git) || !sameIdentity(current.identities.home, original.identities.home)
+          || !sameIdentity(current.identities.state, original.identities.state)) refuse();
+      } catch { refuse(); }
+    },
+  };
+}