@staix/agent-hub 0.19.0 → 0.21.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,33 @@
+// 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.
+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 child = Bun.spawn(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);
+  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);
+  }
+}
+export {};

package/src/cli/smoke-pty.ts

@@ -0,0 +1,145 @@
+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 async function runPty(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 = commandFor(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(); }
+    },
+  };
+}

package/src/cli/source-output.ts

@@ -0,0 +1,29 @@
+// Human output for `ahub source add|list` (#508). Pure: data in, spans out, no I/O. `--json` is the caller's branch and prints the same data.
+import { blank, grid, heading, pair, s } from "./sdlc-output.ts";
+import { moment } from "./sdlc-output.ts";
+import type { Span } from "./console-state.ts";
+
+const list = (value: unknown): any[] => Array.isArray(value) ? value : [];
+const size = (bytes: unknown) => typeof bytes === "number" && Number.isFinite(bytes) ? bytes < 1024 ? `${bytes} B` : bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KiB` : `${(bytes / 1024 / 1024).toFixed(1)} MiB` : "unknown";
+
+/** `ahub source add`: what was registered, and whether it was new or an upgrade of an existing record. */
+export function renderSourceAdd(result: unknown, columns?: number): Span[][] {
+  const r = result as any, out: Span[][] = [...heading(r?.created ? `Registered ${r?.id}` : r?.upgraded ? `Already registered ${r?.id}; now private` : `Already registered ${r?.id}`, columns)];
+  out.push(...pair("kind", r?.kind ?? "unknown", columns, 8), ...pair("origin", r?.origin ?? "unknown", columns, 8), ...pair("sha256", r?.sha256 ?? "unknown", columns, 8), ...pair("size", size(r?.bytes), columns, 8));
+  out.push(...pair("private", r?.private ? "yes" : "no", columns, 8, r?.private ? "attention" : undefined), ...pair("text", r?.text ? "projected" : "none (no converter handles these bytes)", columns, 8, r?.text ? undefined : "muted"));
+  if (list(r?.reasons).length) out.push(...pair("because", list(r.reasons).join("; "), columns, 8, "attention"));
+  return out;
+}
+
+/** `ahub source list`: one row per registered source, newest last. The person sees every origin of a private source. */
+export function renderSourceList(rows: unknown, columns?: number, now = Date.now()): Span[][] {
+  const sources = list(rows);
+  if (!sources.length) return [[s("no sources registered; add one with ahub source add <path|url>", "muted")]];
+  const out: Span[][] = [...heading(`Sources (${sources.length})`, columns)];
+  out.push(...grid(["ID", "KIND", "SIZE", "PRIVATE", "ADDED", "ORIGIN"], sources.map((row: any) => [
+    s(row.id, "issueRef"), s(row.kind), s(size(row.bytes)), s(row.private ? "yes" : "no", row.private ? "attention" : "muted"), s(moment(row.added_at, now)), s(row.origin),
+  ]), columns));
+  const many = sources.filter((row: any) => list(row.origins).length > 1);
+  for (const row of many) out.push(blank, ...pair(row.id, `${list(row.origins).length} origins: ${list(row.origins).map((o: any) => `${o.origin}${o.private ? " (private)" : ""}`).join("; ")}`, columns, 20, undefined));
+  return out;
+}

package/src/cli/task-output.ts

@@ -5,6 +5,7 @@
 // and detail, empty refs and plan): this module shows that stub and never asks for more.
 import { type Span, type Tone, plural, table, terminalText, wrap } from "./console-state.ts";
 import { moment } from "./sdlc-output.ts";
+import { taskHolderText } from "./role-holders.ts";
 
 type Line = Span[];
 // Local copies of the layout primitives of sdlc-output.ts (#814 T1), the source of these helpers: that file stays untouched by this task
@@ -100,8 +101,8 @@ function taskBlock(task: any, columns: number | undefined, now: number, detail:
   const out: Line[] = [...para(`${id}  ${dash(task?.title)}`, columns, undefined, "", 6).map((line, i): Line => i === 0 ? [s(id, "taskRef"), s(line[0]!.text.slice(id.length), "strong")] : line)];
   const w = 10;
   out.push(...pair("state", `${dash(task?.state)}${task?.cancelled ? " (cancelled)" : ""}`, columns, w, stateTone(task?.state), "  "),
-    ...pair("class", dash(task?.class), columns, w, undefined, "  "), ...pair("owner", dash(task?.owner), columns, w, undefined, "  "), ...pair("reviewer", dash(task?.reviewer), columns, w, undefined, "  "));
-  if (task?.planner) out.push(...pair("planner", task.planner, columns, w, undefined, "  "));
+    ...pair("class", dash(task?.class), columns, w, undefined, "  "), ...pair("owner", taskHolderText(task, "owner"), columns, w, undefined, "  "), ...pair("reviewer", taskHolderText(task, "reviewer"), columns, w, undefined, "  "));
+  if (task?.planner !== undefined) out.push(...pair("planner", taskHolderText(task, "planner"), columns, w, undefined, "  "));
   if (task?.reserved) out.push(...pair("reserved", task.reserved, columns, w, undefined, "  "));
   out.push(...pair("after", ids(task?.deps), columns, w, undefined, "  "));
   if (typeof task?.release === "number") out.push(...pair("release", `#${task.release}`, columns, w, undefined, "  "));