@gr8ful/spf 0.1.7 → 0.3.0

package/dist/test/interview.test.js

@@ -0,0 +1,297 @@
+/**
+ * `spf init`'s interactive interview (`cli/interview.ts`) — driven through
+ * the `Asker` seam with a scripted fake (`./fake_asker.ts`), never a real
+ * TTY. Covers the three things a wrong answer would actually break:
+ *   1. the pinned-roster trap (planner/reviewer/documenter overridden
+ *      whenever the backend switches to claude_code — see agent_cc.ts/
+ *      agents.ts's back-fill comment),
+ *   2. the generated config is a genuine override — validating it requires
+ *      merging with the packaged built-in roster first, exactly like
+ *      `spf doctor` does, never the raw document alone,
+ *   3. each `spf watch` combination collects exactly the credentials
+ *      `cli/commands/watch.ts`'s resolveIssueProvider/resolveCodeHostProvider
+ *      actually read — no more, no less.
+ */
+import { test, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { runInterview, gatherContext } from "../cli/interview.js";
+import { loadConfig, validate } from "../core/agents.js";
+import { BUILTIN_CONFIG_PATH } from "../core/paths.js";
+import { createFakeAsker } from "./fake_asker.js";
+let dir;
+before(() => {
+    dir = mkdtempSync(join(tmpdir(), "spf-interview-test-"));
+    execFileSync("git", ["init", "-q"], { cwd: dir });
+    execFileSync("git", ["remote", "add", "origin", "https://github.com/acme/widgets.git"], { cwd: dir });
+    // -c user.*, not a global git config: this must pass in a fresh CI runner
+    // with no git identity configured at all (same reasoning as ui_server.test.ts).
+    execFileSync("git", ["-c", "user.email=test@example.com", "-c", "user.name=spf tests", "commit", "-q", "--allow-empty", "-m", "init"], { cwd: dir });
+});
+after(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+/** Merge with the real packaged roster and validate — the same pipeline `spf doctor` runs, and the only honest way to check a partial override document. */
+function mergedConfigPath() {
+    const configPath = join(dir, `spf.config.${Math.random().toString(36).slice(2)}.yaml`);
+    return configPath;
+}
+test("claude_code + watch(github/github): overrides the three pinned agents and merges cleanly", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: {
+            "backend runs": "claude_code",
+            "Model (Claude": "sonnet",
+            Authentication: "login",
+            "Issue tracker": "github",
+            "Code host": "github",
+            "Chain to run": "plan-build-test",
+        },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": true,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        secret: { GITHUB_TOKEN: "ghp_abcdefghijklmnop" },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.defaults.coding_agent, "claude_code");
+    assert.equal(config.defaults.model, "sonnet");
+    const overrides = config.agents;
+    assert.deepEqual(overrides.map((a) => a.name).sort(), ["documenter", "planner", "reviewer"]);
+    for (const a of overrides)
+        assert.equal(a.model, "sonnet");
+    assert.equal(config.watch.repo, "acme/widgets"); // detected from origin
+    assert.equal(result.env.GITHUB_TOKEN, "ghp_abcdefghijklmnop");
+    assert.ok(result.envExampleKeys.includes("GITHUB_TOKEN"));
+    const configPath = mergedConfigPath();
+    const { stringify } = await import("yaml");
+    writeFileSync(configPath, stringify(config));
+    const cfg = loadConfig([BUILTIN_CONFIG_PATH, configPath]);
+    assert.equal(cfg.defaults.coding_agent, "claude_code");
+    assert.equal(cfg.agents.find((a) => a.name === "planner").model, "sonnet");
+    assert.equal(cfg.agents.find((a) => a.name === "builder").model, "sonnet"); // inherits defaults.model, needed no override
+    validate(cfg, cfg.agents.map((a) => a.name), Object.keys(cfg.quality.suites), dir); // throws on any problem
+});
+test("flue + openrouter: no pinned-agent overrides needed, provider key collected", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: { "backend runs": "flue", Provider: "openrouter" },
+        text: { "Model id": "moonshotai/kimi-k2.7" },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        secret: { OPENROUTER_API_KEY: "sk-or-v1-test" },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.defaults.coding_agent, "flue");
+    assert.equal(config.defaults.model, "openrouter/moonshotai/kimi-k2.7");
+    assert.equal(config.agents, undefined, "flue never needs the pinned-roster fix — agents' own models are already valid Flue ids");
+    assert.equal(result.env.OPENROUTER_API_KEY, "sk-or-v1-test");
+    assert.ok(!("watch" in config));
+});
+test("watch(jira/bitbucket): collects exactly JIRA_* + BITBUCKET_*, never GITHUB_TOKEN", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: {
+            "backend runs": "claude_code",
+            "Model (Claude": "sonnet",
+            Authentication: "login",
+            "Issue tracker": "jira",
+            "Code host": "bitbucket",
+            "Chain to run": "plan-build-test",
+        },
+        text: {
+            "Repo (workspace/repo_slug)": "acme/widgets-repo",
+            "Jira base URL": "https://acme.atlassian.net/",
+            "Jira project key": "proj",
+        },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": true,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        secret: { JIRA_API_TOKEN: "jira-token", BITBUCKET_API_TOKEN: "bb-token" },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.watch.issue_provider, "jira");
+    assert.equal(config.watch.code_host, "bitbucket");
+    assert.equal(config.watch.jira.base_url, "https://acme.atlassian.net"); // trailing slash stripped
+    assert.equal(config.watch.jira.project_key, "PROJ"); // upper-cased
+    assert.equal(result.env.JIRA_API_TOKEN, "jira-token");
+    assert.equal(result.env.BITBUCKET_API_TOKEN, "bb-token");
+    assert.equal(result.env.GITHUB_TOKEN, undefined, "neither provider needs GitHub — must not ask for or write GITHUB_TOKEN");
+});
+test("declining the final confirm returns null — nothing to write", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({ defaultConfirm: false }); // every confirm, including the final one, says no
+    const result = await runInterview(asker, ctx);
+    assert.equal(result, null);
+});
+test("notifications: declining the gate leaves config.notifications undefined", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: { "backend runs": "claude_code", "Model (Claude": "sonnet", Authentication: "login" },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Send notifications": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.notifications, undefined);
+});
+test("notifications: accepting collects the scope, a channel, and its webhook env key", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: {
+            "backend runs": "claude_code",
+            "Model (Claude": "sonnet",
+            Authentication: "login",
+            "Notify on": "all",
+            Channel: "slack",
+        },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Send notifications": true,
+            "Add another channel": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        secret: { SLACK_WEBHOOK_URL: "https://hooks.slack.com/services/T000/B000/XXXX" },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.notifications.events, "all");
+    assert.deepEqual(config.notifications.channels, [{ kind: "slack", webhook_url_env: "SLACK_WEBHOOK_URL" }]);
+    assert.equal(result.env.SLACK_WEBHOOK_URL, "https://hooks.slack.com/services/T000/B000/XXXX");
+    assert.ok(result.envExampleKeys.includes("SLACK_WEBHOOK_URL"));
+    // The written document must still merge and validate cleanly, same
+    // pipeline `spf doctor` runs.
+    const configPath = mergedConfigPath();
+    const { stringify } = await import("yaml");
+    writeFileSync(configPath, stringify(config));
+    const cfg = loadConfig([BUILTIN_CONFIG_PATH, configPath]);
+    assert.equal(cfg.notifications.events, "all");
+    assert.equal(cfg.notifications.channels[0].kind, "slack");
+});
+test("customize models per agent: declining keeps today's behavior — only the three pinned agents, all matching defaults.model", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: { "backend runs": "claude_code", "Model (Claude": "opus", Authentication: "login" },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Customize models per agent": false,
+            "Send notifications": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.deepEqual(config.agents.map((a) => a.name).sort(), ["documenter", "planner", "reviewer"]);
+    for (const a of config.agents)
+        assert.equal(a.model, "opus");
+});
+test("customize models per agent: accepting patches the pinned three and appends builder/scout", async () => {
+    const ctx = gatherContext(dir, new Map());
+    assert.deepEqual(ctx.rosterNames.slice().sort(), ["builder", "documenter", "planner", "reviewer", "scout"]);
+    const asker = createFakeAsker({
+        select: { "backend runs": "claude_code", "Model (Claude": "sonnet", Authentication: "login" },
+        text: {
+            "  planner": "opus",
+            "  builder": "sonnet",
+            "  scout": "haiku",
+            "  reviewer": "opus",
+            "  documenter": "sonnet",
+        },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Customize models per agent": true,
+            "Send notifications": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    const byName = Object.fromEntries(config.agents.map((a) => [a.name, a.model]));
+    assert.deepEqual(byName, { planner: "opus", reviewer: "opus", documenter: "sonnet", builder: "sonnet", scout: "haiku" });
+    const configPath = mergedConfigPath();
+    const { stringify } = await import("yaml");
+    writeFileSync(configPath, stringify(config));
+    const cfg = loadConfig([BUILTIN_CONFIG_PATH, configPath]);
+    validate(cfg, cfg.agents.map((a) => a.name), Object.keys(cfg.quality.suites), dir); // throws on any problem
+    assert.equal(cfg.agents.find((a) => a.name === "scout").model, "haiku");
+});
+test("an existing .env value is offered back as the default when a secret is left blank", async () => {
+    const ctx = gatherContext(dir, new Map([["GITHUB_TOKEN", "ghp_existingvalue"]]));
+    const asker = createFakeAsker({
+        select: {
+            "backend runs": "claude_code",
+            "Model (Claude": "sonnet",
+            Authentication: "login",
+            "Issue tracker": "github",
+            "Code host": "github",
+            "Chain to run": "plan-build-test",
+        },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": true,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        // no GITHUB_TOKEN entry in `secret` — the fake leaves it blank, same as a real user hitting Enter to keep the current value
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    assert.equal(result.env.GITHUB_TOKEN, undefined, "a blank secret answer must not overwrite the existing value with empty");
+});

package/dist/test/notify.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/notify.test.js

@@ -0,0 +1,174 @@
+/**
+ * The notifier: the `events` filter matrix, per-channel scope override, a
+ * real webhook POST against a local `node:http` receiver (not a `fetch`
+ * mock — proves the actual bytes on the wire), a rejecting channel never
+ * propagating, `flush()` actually awaiting pending sends, and an unset env
+ * var degrading to a warning instead of a crash.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import * as v from "valibot";
+import { Notifier, resolveNotifier, DEFAULT_NOTIFY_ENV_KEY } from "../core/notify/notifier.js";
+import { SFConfigSchema } from "../core/data_types.js";
+function baseConfig(overrides = {}) {
+    return v.parse(SFConfigSchema, { notifications: { events: "errors", channels: [], ...overrides } });
+}
+function infoEvent() {
+    return { kind: "run_started", level: "info", title: "run started", fields: [] };
+}
+function errorEvent() {
+    return { kind: "run_failed", level: "error", title: "run failed", fields: [] };
+}
+class RecordingChannel {
+    received = [];
+    label = "recording";
+    async send(event) {
+        this.received.push(event);
+    }
+}
+class RejectingChannel {
+    label = "rejecting";
+    async send() {
+        throw new Error("boom");
+    }
+}
+class BlockedChannel {
+    label = "blocked";
+    release;
+    gate = new Promise((resolve) => (this.release = resolve));
+    async send() {
+        await this.gate;
+    }
+}
+test("events: off never sends, regardless of level", () => {
+    const channel = new RecordingChannel();
+    const notifier = new Notifier([{ channel, scope: "off" }], 1000, false, () => { });
+    notifier.send(infoEvent());
+    notifier.send(errorEvent());
+    assert.deepEqual(channel.received, []);
+});
+test("events: errors sends only level=error", () => {
+    const channel = new RecordingChannel();
+    const notifier = new Notifier([{ channel, scope: "errors" }], 1000, false, () => { });
+    notifier.send(infoEvent());
+    notifier.send(errorEvent());
+    assert.equal(channel.received.length, 1);
+    assert.equal(channel.received[0].level, "error");
+});
+test("events: all sends both info and error", () => {
+    const channel = new RecordingChannel();
+    const notifier = new Notifier([{ channel, scope: "all" }], 1000, false, () => { });
+    notifier.send(infoEvent());
+    notifier.send(errorEvent());
+    assert.equal(channel.received.length, 2);
+});
+test("a per-channel scope overrides the top-level scope", () => {
+    const loud = new RecordingChannel();
+    const quiet = new RecordingChannel();
+    const notifier = new Notifier([
+        { channel: loud, scope: "all" },
+        { channel: quiet, scope: "errors" },
+    ], 1000, false, () => { });
+    notifier.send(infoEvent());
+    assert.equal(loud.received.length, 1);
+    assert.equal(quiet.received.length, 0);
+});
+test("dry-run logs and sends nothing to any channel", () => {
+    const channel = new RecordingChannel();
+    const logs = [];
+    const notifier = new Notifier([{ channel, scope: "all" }], 1000, true, (m) => logs.push(m));
+    notifier.send(infoEvent());
+    assert.deepEqual(channel.received, []);
+    assert.equal(logs.length, 1);
+    assert.match(logs[0], /would notify/);
+});
+test("a rejecting channel logs one line and never throws or blocks other channels", async () => {
+    const rejecting = new RejectingChannel();
+    const ok = new RecordingChannel();
+    const logs = [];
+    const notifier = new Notifier([
+        { channel: rejecting, scope: "all" },
+        { channel: ok, scope: "all" },
+    ], 1000, false, (m) => logs.push(m));
+    assert.doesNotThrow(() => notifier.send(infoEvent()));
+    await notifier.flush();
+    assert.equal(ok.received.length, 1);
+    assert.equal(logs.length, 1);
+    assert.match(logs[0], /rejecting notification failed: boom/);
+});
+test("flush() actually awaits pending sends before returning", async () => {
+    const blocked = new BlockedChannel();
+    const notifier = new Notifier([{ channel: blocked, scope: "all" }], 1000, false, () => { });
+    notifier.send(infoEvent());
+    let flushed = false;
+    const flushPromise = notifier.flush().then(() => {
+        flushed = true;
+    });
+    await new Promise((r) => setTimeout(r, 20));
+    assert.equal(flushed, false, "flush must not resolve before the pending send does");
+    blocked.release();
+    await flushPromise;
+    assert.equal(flushed, true);
+});
+test("resolveNotifier returns null when events is off", () => {
+    const cfg = baseConfig({ events: "off", channels: [{ kind: "webhook", webhook_url_env: "SPF_TEST_WEBHOOK" }] });
+    assert.equal(resolveNotifier(cfg), null);
+});
+test("resolveNotifier returns null when no channels are configured", () => {
+    const cfg = baseConfig({ events: "all", channels: [] });
+    assert.equal(resolveNotifier(cfg), null);
+});
+test("resolveNotifier skips a channel whose env var is unset, with one warning naming the key — never throws", () => {
+    delete process.env["SPF_TEST_WEBHOOK_UNSET"];
+    const cfg = baseConfig({ events: "all", channels: [{ kind: "webhook", webhook_url_env: "SPF_TEST_WEBHOOK_UNSET" }] });
+    const logs = [];
+    const notifier = resolveNotifier(cfg, { log: (m) => logs.push(m) });
+    assert.equal(notifier, null);
+    assert.equal(logs.length, 1);
+    assert.match(logs[0], /SPF_TEST_WEBHOOK_UNSET is not set/);
+});
+test("resolveNotifier falls back to the kind's default env key when webhook_url_env is empty", () => {
+    process.env["SLACK_WEBHOOK_URL"] = "http://127.0.0.1:1/unused";
+    try {
+        const cfg = baseConfig({ events: "all", channels: [{ kind: "slack" }] });
+        const notifier = resolveNotifier(cfg);
+        assert.notEqual(notifier, null);
+        assert.equal(DEFAULT_NOTIFY_ENV_KEY["slack"], "SLACK_WEBHOOK_URL");
+    }
+    finally {
+        delete process.env["SLACK_WEBHOOK_URL"];
+    }
+});
+test("a webhook channel posts the real NotifyEvent JSON over the wire to a local receiver", async () => {
+    let receivedBody = "";
+    let receivedContentType = "";
+    const server = createServer((req, res) => {
+        receivedContentType = req.headers["content-type"] ?? "";
+        let body = "";
+        req.on("data", (chunk) => (body += chunk));
+        req.on("end", () => {
+            receivedBody = body;
+            res.writeHead(200);
+            res.end("ok");
+        });
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = server.address().port;
+    const envKey = "SPF_TEST_WEBHOOK_LIVE";
+    process.env[envKey] = `http://127.0.0.1:${port}/hook`;
+    try {
+        const cfg = baseConfig({ events: "all", channels: [{ kind: "webhook", webhook_url_env: envKey }] });
+        const notifier = resolveNotifier(cfg);
+        assert.notEqual(notifier, null);
+        const event = { kind: "issue_claimed", level: "info", title: "issue 42 claimed", fields: [["issue", "42"]] };
+        notifier.send(event);
+        await notifier.flush();
+        assert.equal(receivedContentType, "application/json");
+        assert.deepEqual(JSON.parse(receivedBody), event);
+    }
+    finally {
+        delete process.env[envKey];
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+});

package/dist/test/ui_server.test.js

@@ -25,7 +25,7 @@ before(async () => {
     execFileSync("git", ["-c", "user.email=test@example.com", "-c", "user.name=spf tests", "commit", "-q", "--allow-empty", "-m", "init"], { cwd: dir });
     const dbPath = join(dir, "spf.db");
     const tracer = new Tracer(dbPath, join(dir, "sessions", ADW_ID, "events.jsonl"));
-    tracer.sessionStart(ADW_ID, "tester", "adw_quality");
+    tracer.sessionStart(ADW_ID, "tester", "quality");
     const phase = {
         phase_id: `${ADW_ID}_01_request`,
         adw_id: ADW_ID,

package/dist/test/watch.test.js

@@ -1,7 +1,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import path from "node:path";
-import { branchNameFor, claimNewWork, createWatchState, finishReviews, reconcileOrphans } from "../core/watch.js";
+import { branchNameFor, claimNewWork, createWatchState, finishReviews, reconcileOrphans, tick } from "../core/watch.js";
 /** In-memory fake — exactly the seam `provider.ts` exists for. */
 class FakeProvider {
     entries = new Map();
@@ -96,9 +96,15 @@ function makeDeps(provider, codeHost, overrides = {}) {
         dryRun: false,
         runChain: async () => ({ accepted: true, adwId: "issue-1", detail: "" }),
         log: () => { },
+        notify: () => { },
         ...overrides,
     };
 }
+/** Collects every `deps.notify(...)` call, for asserting kinds/levels without a real channel. */
+function collectNotifications() {
+    const events = [];
+    return { events, notify: (event) => events.push(event) };
+}
 async function waitUntil(predicate, timeoutMs = 2000) {
     const start = Date.now();
     while (!predicate()) {
@@ -281,3 +287,110 @@ test("finishReviews: a still-open PR leaves the issue in review", async () => {
     assert.equal(provider.transitions.length, 0);
     assert.equal(provider.entries.get("42").state, "review");
 });
+// ── notifications ────────────────────────────────────────────────────────────
+test("claim -> PR opened -> merged fires issue_claimed, pr_opened, then issue_done (all info-level)", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("50", "Add a /health endpoint");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, { notify });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_claimed", "pr_opened"]);
+    assert.ok(events.every((e) => e.level === "info"));
+    codeHost.prs.set(1000, { merged: true, state: "closed", ciStatus: "success" });
+    await finishReviews(deps);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_claimed", "pr_opened", "issue_done"]);
+    assert.equal(events.at(-1).level, "info");
+});
+test("a rejected chain run fires issue_blocked at error level", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("51", "Flaky feature");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, {
+        notify,
+        runChain: async () => ({ accepted: false, adwId: "issue-51", detail: "build-test failed" }),
+    });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    const blocked = events.filter((e) => e.kind === "issue_blocked");
+    assert.equal(blocked.length, 1);
+    assert.equal(blocked[0].level, "error");
+    assert.equal(blocked[0].detail, "build-test failed");
+});
+test("an accepted run with nothing committed fires issue_blocked", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("52", "No-op request");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, { notify, worktreeGit: () => fakeGit({ diffFiles: () => [] }) });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_claimed", "issue_blocked"]);
+    assert.match(events[1].detail ?? "", /no committed changes/);
+});
+test("an exception mid-runIssue fires watch_error at error level", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("53", "Explodes");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, {
+        notify,
+        runChain: async () => {
+            throw new Error("kaboom");
+        },
+    });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    const errors = events.filter((e) => e.kind === "watch_error");
+    assert.equal(errors.length, 1);
+    assert.equal(errors[0].level, "error");
+    assert.match(errors[0].detail ?? "", /kaboom/);
+});
+test("finishReviews: a closed-without-merging PR fires issue_blocked", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("54", "rejected", "review", { pr: 700, branch: "spf-watch/54-x" });
+    const codeHost = new FakeCodeHost();
+    codeHost.prs.set(700, { merged: false, state: "closed", ciStatus: "failure" });
+    const { events, notify } = collectNotifications();
+    await finishReviews(makeDeps(provider, codeHost, { notify }));
+    assert.deepEqual(events.map((e) => e.kind), ["issue_blocked"]);
+    assert.equal(events[0].level, "error");
+});
+test("reconcileOrphans: giving up past the retry cap fires issue_blocked", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("55", "orphaned, no marker", "working", { attempt: 2 }); // one more push exceeds MAX_ORPHAN_ATTEMPTS (2)
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    await reconcileOrphans(makeDeps(provider, codeHost, { notify }), state);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_blocked"]);
+    assert.match(events[0].detail ?? "", /Gave up after 2 orphaned attempts/);
+});
+test("reconcileOrphans: a routine orphan resume/retry notifies nothing — only the terminal give-up does", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("56", "orphaned, resumable", "working", { pr: 800, branch: "spf-watch/56-x" });
+    const codeHost = new FakeCodeHost();
+    codeHost.prs.set(800, { merged: false, state: "open", ciStatus: "pending" });
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    await reconcileOrphans(makeDeps(provider, codeHost, { notify }), state);
+    assert.deepEqual(events, []);
+});
+test("tick: a per-stage error is caught and fires exactly one watch_error", async () => {
+    const provider = new FakeProvider();
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    provider.listEligible = async () => {
+        throw new Error("listEligible exploded");
+    };
+    await tick(makeDeps(provider, codeHost, { notify }), state);
+    assert.deepEqual(events.map((e) => e.kind), ["watch_error"]);
+    assert.match(events[0].detail ?? "", /listEligible exploded/);
+});

package/dist/ui/shared/types.d.ts

@@ -15,7 +15,7 @@ export type PhaseKind = "engineer" | "code" | "agent";
 export type EventType = "phase_start" | "phase_end" | "agent_start" | "agent_end" | "tool_call" | "handoff" | "gate_pass" | "gate_fail" | "log" | "error";
 export interface Session {
     adw_id: string;
-    /** ADW script(s) that ran this session, e.g. "adw_plan + adw_build_test". */
+    /** Chain(s) that ran this session, e.g. "plan + build-test". */
     adw_name: string | null;
     request: string | null;
     status: SessionStatus | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.1.7",
+  "version": "0.3.0",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",
@@ -38,7 +38,10 @@
     "pretest": "npm run build:cli",
     "test": "node --test \"dist/**/*.test.js\"",
     "prepack": "node scripts/check-pack-ready.js",
-    "size-check": "node scripts/check-tarball-size.js"
+    "size-check": "node scripts/check-tarball-size.js",
+    "tag:major": "node scripts/tag-release.js major",
+    "tag:minor": "node scripts/tag-release.js minor",
+    "tag:patch": "node scripts/tag-release.js patch"
   },
   "dependencies": {
     "@flue/runtime": "2.0.3",

package/dist/chains/adw_build.d.ts

@@ -1,12 +0,0 @@
-/**
- * ADW Build — one-shot implementation workflow.
- *
- * Usage:
- *   spf build "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
- *
- * Phases: engineer(request) -> builder
- */
-import type { ChainContext } from "./context.ts";
-export declare const REQUIRED_AGENTS: string[];
-export declare const REQUIRED_SUITES: string[];
-export declare function main(ctx: ChainContext): Promise<number>;