@gr8ful/spf 0.1.0

package/dist/core/tracer.js

@@ -0,0 +1,246 @@
+/**
+ * Tracer: every event lands in JSONL and SQLite AS IT HAPPENS.
+ *
+ * Files are the raw record; spf.db is the queryable mirror the UI polls.
+ * No push transport — the flow is always: agents -> sqlite -> web ui.
+ * WAL mode so the UI can read while ADW processes write.
+ */
+import { Database } from "./sqlite.js";
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { newId, nowIso } from "./utils.js";
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS sessions (
+  adw_id        TEXT PRIMARY KEY,
+  adw_name      TEXT,                -- ADW script(s) run, e.g. "adw_plan + adw_build_test"
+  request       TEXT,
+  status        TEXT,
+  engineer      TEXT,
+  started_at    TEXT, ended_at TEXT,
+  total_tokens  INTEGER DEFAULT 0, total_cost REAL DEFAULT 0,
+  archived      INTEGER DEFAULT 0   -- review triage, set by the UI; never by a run
+);
+CREATE TABLE IF NOT EXISTS phases (
+  phase_id      TEXT PRIMARY KEY,
+  adw_id        TEXT REFERENCES sessions,
+  seq           INTEGER,
+  name TEXT, kind TEXT, owner TEXT, description TEXT,
+  status        TEXT DEFAULT 'fail',
+  attempt       INTEGER DEFAULT 0, retries INTEGER DEFAULT 0,
+  error         TEXT,
+  started_at    TEXT, ended_at TEXT
+);
+CREATE TABLE IF NOT EXISTS events (
+  event_id      TEXT PRIMARY KEY,
+  adw_id        TEXT REFERENCES sessions,
+  phase_id      TEXT REFERENCES phases,
+  parent_id     TEXT,
+  type          TEXT,
+  name          TEXT,
+  payload_json  TEXT,
+  tokens        INTEGER,
+  started_at    TEXT, ended_at TEXT
+);
+CREATE TABLE IF NOT EXISTS envelopes (
+  envelope_id   TEXT PRIMARY KEY,
+  adw_id        TEXT REFERENCES sessions,
+  phase_id      TEXT REFERENCES phases,
+  agent         TEXT,
+  output_type   TEXT,
+  payload_json  TEXT,
+  valid         INTEGER,
+  attempt       INTEGER,
+  created_at    TEXT
+);
+CREATE TABLE IF NOT EXISTS gate_results (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  adw_id        TEXT REFERENCES sessions,
+  phase_id      TEXT REFERENCES phases,
+  attempt       INTEGER,
+  gate          TEXT,
+  passed        INTEGER,
+  violations_json TEXT,
+  checks_json   TEXT,               -- [{item, ok, note}] — WHAT the gate verified
+  created_at    TEXT
+);
+CREATE TABLE IF NOT EXISTS processes (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  adw_id        TEXT REFERENCES sessions,
+  kind          TEXT,                -- 'adw' (the workflow process) | 'agent' (a coding-agent child)
+  name          TEXT,                -- '' for the adw, the agent name for a child
+  pid           INTEGER,
+  command       TEXT,                -- what the pid was, so a recycled pid is not killed by mistake
+  started_at    TEXT, ended_at TEXT  -- ended_at NULL = believed alive
+);
+CREATE TABLE IF NOT EXISTS agent_sessions (
+  adw_id        TEXT REFERENCES sessions,
+  agent         TEXT,
+  coding_agent  TEXT, model TEXT, color TEXT,
+  session_id    TEXT,
+  context_tokens INTEGER,           -- window occupancy after the agent's last turn
+  context_window INTEGER,           -- the model's ceiling; 0/NULL = unknown
+  created_at    TEXT, last_used_at TEXT,
+  PRIMARY KEY (adw_id, agent)
+);
+`;
+// Columns added after a schema shipped. CREATE TABLE IF NOT EXISTS never
+// revisits an existing table, so additive changes need an explicit ALTER.
+const MIGRATIONS = [
+    ["agent_sessions", "color", "TEXT"],
+    ["gate_results", "checks_json", "TEXT"],
+    ["sessions", "adw_name", "TEXT"],
+    ["agent_sessions", "context_tokens", "INTEGER"],
+    ["agent_sessions", "context_window", "INTEGER"],
+    ["sessions", "archived", "INTEGER DEFAULT 0"],
+];
+export class Tracer {
+    db;
+    dbPath;
+    eventsJsonl;
+    constructor(dbPath, eventsJsonl) {
+        mkdirSync(path.dirname(dbPath), { recursive: true });
+        this.dbPath = dbPath;
+        this.eventsJsonl = eventsJsonl;
+        mkdirSync(path.dirname(eventsJsonl), { recursive: true });
+        this.db = new Database(this.dbPath);
+        this.db.exec("PRAGMA journal_mode=WAL;");
+        this.db.exec("PRAGMA synchronous=NORMAL;");
+        this.db.exec("PRAGMA busy_timeout=5000;");
+        this.db.exec(SCHEMA);
+        this.migrate();
+    }
+    /** Additive column migrations, so a db from an older SPF still opens. */
+    migrate() {
+        for (const [table, column, decl] of MIGRATIONS) {
+            const columns = new Set(this.db.query(`PRAGMA table_info(${table})`).all().map((row) => row.name));
+            if (!columns.has(column)) {
+                this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${decl}`);
+            }
+        }
+    }
+    // ── events ──────────────────────────────────────────────────────────────
+    event(record) {
+        const eventId = `evt_${newId(12)}`;
+        const ts = nowIso();
+        const line = { event_id: eventId, ts, ...record };
+        appendFileSync(this.eventsJsonl, JSON.stringify(line) + "\n");
+        this.db
+            .query(`INSERT INTO events (event_id, adw_id, phase_id, parent_id, type, name,
+         payload_json, tokens, started_at, ended_at) VALUES (?,?,?,?,?,?,?,?,?,?)`)
+            .run(eventId, record.adw_id, record.phase_id, record.parent_id, record.type, record.name, JSON.stringify(record.payload), record.tokens ?? null, record.started_at || ts, record.ended_at ?? null);
+        return eventId;
+    }
+    // ── sessions ────────────────────────────────────────────────────────────
+    sessionStart(adwId, engineer, adwName) {
+        this.db
+            .query(`INSERT INTO sessions (adw_id, status, engineer, started_at) VALUES (?,?,?,?)
+         ON CONFLICT(adw_id) DO UPDATE SET status='running'`)
+            .run(adwId, "running", engineer, nowIso());
+        if (!adwName)
+            return;
+        // A joined session chains ADWs — record each distinct one, in run order.
+        const row = this.db.query("SELECT adw_name FROM sessions WHERE adw_id=?").get(adwId);
+        const names = row?.adw_name ? row.adw_name.split(" + ") : [];
+        if (!names.includes(adwName)) {
+            names.push(adwName);
+            this.db.query("UPDATE sessions SET adw_name=? WHERE adw_id=?").run(names.join(" + "), adwId);
+        }
+    }
+    sessionRequest(adwId, request) {
+        this.db.query("UPDATE sessions SET request=? WHERE adw_id=?").run(request.slice(0, 500), adwId);
+    }
+    sessionFinish(adwId, ok) {
+        this.db
+            .query("UPDATE sessions SET status=?, ended_at=? WHERE adw_id=?")
+            .run(ok ? "success" : "fail", nowIso(), adwId);
+        this.processesEndAll(adwId); // nothing of this run is alive any more
+    }
+    sessionAddUsage(adwId, tokens, cost) {
+        this.db
+            .query("UPDATE sessions SET total_tokens=total_tokens+?, total_cost=total_cost+? WHERE adw_id=?")
+            .run(tokens, cost, adwId);
+    }
+    // ── processes (adw_id → pid, so a hung run can be found and killed) ─────
+    /**
+     * Record a live process for this run.
+     *
+     * A coding agent that hangs produces no events at all, which is exactly
+     * when you need its pid — and `ps` cannot tell you which adw_id it
+     * belongs to. Writing it here makes the trace the answer to "what is this
+     * run running, and how do I stop it".
+     */
+    processStart(adwId, kind, name, pid, command) {
+        this.db
+            .query(`INSERT INTO processes (adw_id, kind, name, pid, command, started_at) VALUES (?,?,?,?,?,?)`)
+            .run(adwId, kind, name, pid, command.slice(0, 500), nowIso());
+    }
+    /** Mark the newest live row for this pid as finished. */
+    processEnd(adwId, pid) {
+        this.db
+            .query(`UPDATE processes SET ended_at=? WHERE id = (
+           SELECT id FROM processes WHERE adw_id=? AND pid=? AND ended_at IS NULL
+           ORDER BY id DESC LIMIT 1)`)
+            .run(nowIso(), adwId, pid);
+    }
+    /** Close out every live row for a run — called when the session ends. */
+    processesEndAll(adwId) {
+        this.db.query("UPDATE processes SET ended_at=? WHERE adw_id=? AND ended_at IS NULL").run(nowIso(), adwId);
+    }
+    // ── phases ──────────────────────────────────────────────────────────────
+    /**
+     * Highest seq already recorded for this session; 0 when it is new.
+     *
+     * A joined run continues the sequence instead of restarting at 1 — which
+     * would collide with the first run's phases on both `seq` (breaking
+     * ordering) and `phase_id` (silently overwriting a row through the
+     * phase_upsert conflict clause).
+     */
+    maxPhaseSeq(adwId) {
+        const row = this.db.query("SELECT MAX(seq) as m FROM phases WHERE adw_id = ?").get(adwId);
+        return row?.m ?? 0;
+    }
+    phaseUpsert(phase) {
+        const p = phase.params;
+        this.db
+            .query(`INSERT INTO phases (phase_id, adw_id, seq, name, kind, owner, description,
+         status, attempt, retries, error, started_at, ended_at)
+         VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)
+         ON CONFLICT(phase_id) DO UPDATE SET status=excluded.status,
+         attempt=excluded.attempt, error=excluded.error, ended_at=excluded.ended_at`)
+            .run(phase.phase_id, phase.adw_id, phase.seq, p.name, p.kind, p.owner, p.description, phase.status, phase.attempt, p.retries, phase.error ?? null, phase.started_at ?? null, phase.ended_at ?? null);
+    }
+    // ── envelopes / gates / agent sessions ──────────────────────────────────
+    envelopeRow(phase, agent, outputType, payloadJson, valid, attempt) {
+        this.db
+            .query(`INSERT INTO envelopes (envelope_id, adw_id, phase_id, agent, output_type,
+         payload_json, valid, attempt, created_at) VALUES (?,?,?,?,?,?,?,?,?)`)
+            .run(`env_${newId(12)}`, phase.adw_id, phase.phase_id, agent, outputType, payloadJson, valid ? 1 : 0, attempt, nowIso());
+    }
+    /** The report carries both the verdict and the evidence behind it. */
+    gateRow(phase, gate, report, attempt) {
+        this.db
+            .query(`INSERT INTO gate_results (adw_id, phase_id, attempt, gate, passed,
+         violations_json, checks_json, created_at) VALUES (?,?,?,?,?,?,?,?)`)
+            .run(phase.adw_id, phase.phase_id, attempt, gate, report.passed ? 1 : 0, JSON.stringify(report.violations), JSON.stringify(report.checks), nowIso());
+    }
+    /**
+     * The agent's config row is the source of truth for its label and color.
+     *
+     * Context is carried here rather than derived from events because the lane
+     * wants one number per agent — the latest — and a session that runs the
+     * same agent twice overwrites it, exactly like model and session_id.
+     */
+    agentSessionRow(adwId, agent, sessionId, contextTokens = 0, contextWindow = 0) {
+        const ts = nowIso();
+        this.db
+            .query(`INSERT INTO agent_sessions (adw_id, agent, coding_agent, model, color,
+         session_id, context_tokens, context_window, created_at, last_used_at)
+         VALUES (?,?,?,?,?,?,?,?,?,?)
+         ON CONFLICT(adw_id, agent) DO UPDATE SET model=excluded.model,
+         color=excluded.color, session_id=excluded.session_id,
+         context_tokens=excluded.context_tokens,
+         context_window=excluded.context_window,
+         last_used_at=excluded.last_used_at`)
+            .run(adwId, agent.name, agent.coding_agent, agent.model, agent.color, sessionId, contextTokens, contextWindow, ts, ts);
+    }
+}

package/dist/core/utils.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Small shared helpers. Anything bigger belongs in its own module.
+ *
+ * Bun loads .env files automatically for anything run with `bun run`/`bun`,
+ * so there is no load_dotenv() call to make here — that parity is free.
+ */
+import path from "node:path";
+/**
+ * The engineer's own environment, as their shell would hand it over.
+ *
+ * Python's version stripped a `uv run` venv's bin dir off PATH so a
+ * subprocess's `python3` resolved the operator's own interpreter, not the
+ * ADW's ephemeral one. Bun scripts run directly (no venv layer prepended to
+ * PATH), so there is nothing to strip here — this exists for call-site parity
+ * and as the one place to patch if a future wrapper starts doing the same
+ * thing to PATH.
+ */
+export declare function operatorEnv(): Record<string, string>;
+export declare function newId(length?: number): string;
+/** Matches Python's `datetime.now(timezone.utc).isoformat(timespec="milliseconds")`. */
+export declare function nowIso(): string;
+export declare function ensureDir(dirPath: string): string;
+/** CLI prompt arg: a file path resolves to its contents, else inline text. */
+export declare function resolvePrompt(arg: string): string;
+export declare function engineerName(): string;
+/**
+ * Minimal `--flag value` / `--bare-flag` CLI parsing — the CLI only ever
+ * needs a handful of positionals plus a handful of named options and bare
+ * boolean flags, so a full argparse port would be more machinery than the
+ * job needs. `flagNames` are boolean — present means true, never consumes
+ * the next argv value; anything else in `optionNames` always takes a value.
+ */
+export declare function parseCli(argv: string[], optionNames: string[], flagNames?: string[]): {
+    positionals: string[];
+    options: Record<string, string>;
+    flags: Record<string, boolean>;
+};
+/** Run an ADW's async main() and translate its outcome into a process exit code. */
+export declare function runMain(main: () => Promise<number>): void;
+export { path };

package/dist/core/utils.js

@@ -0,0 +1,108 @@
+/**
+ * Small shared helpers. Anything bigger belongs in its own module.
+ *
+ * Bun loads .env files automatically for anything run with `bun run`/`bun`,
+ * so there is no load_dotenv() call to make here — that parity is free.
+ */
+import { randomBytes } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+/**
+ * The engineer's own environment, as their shell would hand it over.
+ *
+ * Python's version stripped a `uv run` venv's bin dir off PATH so a
+ * subprocess's `python3` resolved the operator's own interpreter, not the
+ * ADW's ephemeral one. Bun scripts run directly (no venv layer prepended to
+ * PATH), so there is nothing to strip here — this exists for call-site parity
+ * and as the one place to patch if a future wrapper starts doing the same
+ * thing to PATH.
+ */
+export function operatorEnv() {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return env;
+}
+export function newId(length = 8) {
+    return randomBytes(Math.floor(length / 2)).toString("hex");
+}
+/** Matches Python's `datetime.now(timezone.utc).isoformat(timespec="milliseconds")`. */
+export function nowIso() {
+    const iso = new Date().toISOString(); // e.g. 2024-01-01T12:00:00.123Z
+    return iso.replace("Z", "+00:00");
+}
+export function ensureDir(dirPath) {
+    mkdirSync(dirPath, { recursive: true });
+    return dirPath;
+}
+/** CLI prompt arg: a file path resolves to its contents, else inline text. */
+export function resolvePrompt(arg) {
+    try {
+        if (existsSync(arg) && statSync(arg).isFile()) {
+            return readFileSync(arg, "utf-8");
+        }
+    }
+    catch {
+        // not a valid path — fall through to inline text
+    }
+    return arg;
+}
+export function engineerName() {
+    const name = (process.env.ENGINEER_NAME || "").trim();
+    if (name)
+        return name;
+    try {
+        const out = spawnSync("git", ["config", "user.name"], { encoding: "utf-8", timeout: 5000 });
+        if (out.status === 0 && out.stdout.trim())
+            return out.stdout.trim();
+    }
+    catch {
+        // git not available or not configured — fall through
+    }
+    return process.env.USER || process.env.USERNAME || "engineer";
+}
+/**
+ * Minimal `--flag value` / `--bare-flag` CLI parsing — the CLI only ever
+ * needs a handful of positionals plus a handful of named options and bare
+ * boolean flags, so a full argparse port would be more machinery than the
+ * job needs. `flagNames` are boolean — present means true, never consumes
+ * the next argv value; anything else in `optionNames` always takes a value.
+ */
+export function parseCli(argv, optionNames, flagNames = []) {
+    const positionals = [];
+    const options = {};
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const name = arg.slice(2);
+            if (flagNames.includes(name)) {
+                flags[name] = true;
+                continue;
+            }
+            if (!optionNames.includes(name))
+                throw new Error(`unknown option: --${name}`);
+            const value = argv[++i];
+            if (value === undefined)
+                throw new Error(`--${name} requires a value`);
+            options[name] = value;
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    return { positionals, options, flags };
+}
+/** Run an ADW's async main() and translate its outcome into a process exit code. */
+export function runMain(main) {
+    main()
+        .then((code) => process.exit(code))
+        .catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    });
+}
+export { path };

package/dist/core/watch.d.ts

@@ -0,0 +1,44 @@
+import type { GitHandle } from "./git_helper.ts";
+import type { Issue, IssueProvider } from "./issues/provider.ts";
+export interface ChainRunResult {
+    accepted: boolean;
+    adwId: string;
+    /** Shown to the engineer via a `blocked` comment on a failed/no-op run. */
+    detail: string;
+}
+export interface WatchDeps {
+    provider: IssueProvider;
+    git: GitHandle;
+    /** Bound to a specific worktree path (diffFiles/push run there) — inject `git_helper.makeGit` for real use, a fake for tests. */
+    worktreeGit: (worktreePath: string) => GitHandle;
+    labelPrefix: string;
+    chain: string;
+    baseBranch: string;
+    concurrency: number;
+    worktreesDir: string;
+    dryRun: boolean;
+    runChain: (opts: {
+        prompt: string;
+        cwd: string;
+        adwId: string;
+    }) => Promise<ChainRunResult>;
+    log: (message: string) => void;
+}
+export interface WatchRunState {
+    inflight: Set<number>;
+}
+export declare function createWatchState(): WatchRunState;
+export declare function branchNameFor(issue: Issue): string;
+/**
+ * Any issue labeled `working` that THIS process isn't tracking is an
+ * orphan — a daemon restart, or another instance's claim this process
+ * never saw. Resume if its marker points at a still-open (or already
+ * merged) PR; otherwise retry up to `MAX_ORPHAN_ATTEMPTS`, then give up.
+ */
+export declare function reconcileOrphans(deps: WatchDeps, state: WatchRunState): Promise<void>;
+/** Poll every `review`-labeled issue's PR for merged (-> done) or closed-without-merging (-> blocked). */
+export declare function finishReviews(deps: WatchDeps): Promise<void>;
+/** Claim as many `ready` issues as the concurrency budget allows, and kick off `runIssue` for each in the background. */
+export declare function claimNewWork(deps: WatchDeps, state: WatchRunState): Promise<void>;
+/** One poll tick: reconcile, finish, claim — each independently caught, so one phase's error never blocks the rest. */
+export declare function tick(deps: WatchDeps, state: WatchRunState): Promise<void>;

package/dist/core/watch.js

@@ -0,0 +1,194 @@
+/**
+ * The `spf watch` state machine: poll -> claim -> run a chain -> PR ->
+ * done/blocked. Provider-agnostic (drives whatever `IssueProvider` it's
+ * given) and chain-agnostic (drives whatever `runChain` callback it's
+ * given) — deliberately kept out of `src/chains/`'s dependency direction,
+ * so this stays testable against a fake provider and a fake `runChain`
+ * with no chain registry involved.
+ *
+ * Design lifted from the user's own GitHub-poller reference implementation
+ * (a label-as-state-machine daemon), leaned down for a v1: no per-issue
+ * telemetry, no dashboard, no Projects v2 mirroring, no CI-fix retry loop,
+ * no auto-merge. What's kept, because it's cheap and load-bearing:
+ *
+ *  - `transition()` is the ONE state mutator (see `provider.ts`) — every
+ *    state change traces to one call site.
+ *  - A marker (a hidden HTML comment on the issue) is the durable scratch
+ *    state — zero infrastructure, survives a daemon crash.
+ *  - `listInState("review", {includeAll: true})` — a tracker that
+ *    auto-closes an issue the instant its linked PR merges (GitHub's
+ *    `Closes #n`) can make it vanish from an open-only query before the
+ *    next tick runs.
+ *  - Orphan reconciliation: any `working` issue this process isn't
+ *    tracking gets one of three outcomes (resume via its marker's PR,
+ *    retry up to a cap, or give up and block) every tick — a hung daemon
+ *    restart never leaves an issue silently stuck.
+ *  - Worktree-per-issue, isolated outside the repo, made cheap by SPF's
+ *    own `--cwd` support: no new chain-dispatch plumbing needed, just
+ *    pointing an existing chain at a different working tree.
+ */
+import path from "node:path";
+const MAX_ORPHAN_ATTEMPTS = 2;
+export function createWatchState() {
+    return { inflight: new Set() };
+}
+export function branchNameFor(issue) {
+    const slug = issue.title
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, 5)
+        .join("-")
+        .replace(/[^a-z0-9-]/g, "");
+    return `spf-watch/${issue.number}-${slug || "issue"}`.slice(0, 200);
+}
+function worktreePathFor(deps, issue) {
+    return path.join(deps.worktreesDir, `issue-${issue.number}`);
+}
+function cleanupWorktree(deps, marker) {
+    if (!marker)
+        return;
+    try {
+        if (marker.worktree)
+            deps.git.worktreeRemove(marker.worktree);
+        if (marker.branch)
+            deps.git.deleteLocalBranch(marker.branch);
+    }
+    catch (error) {
+        deps.log(`watch: cleanup warning: ${error.message}`);
+    }
+}
+/**
+ * Any issue labeled `working` that THIS process isn't tracking is an
+ * orphan — a daemon restart, or another instance's claim this process
+ * never saw. Resume if its marker points at a still-open (or already
+ * merged) PR; otherwise retry up to `MAX_ORPHAN_ATTEMPTS`, then give up.
+ */
+export async function reconcileOrphans(deps, state) {
+    const working = await deps.provider.listInState("working");
+    for (const issue of working) {
+        if (state.inflight.has(issue.number))
+            continue;
+        const marker = await deps.provider.readMarker(issue);
+        if (marker?.pr) {
+            const status = await deps.provider.prStatus({ number: marker.pr, branch: marker.branch ?? "", url: "" });
+            if (status.state === "open" || status.merged) {
+                deps.log(`watch: #${issue.number} orphaned with an open/merged PR #${marker.pr} — resuming as review`);
+                if (!deps.dryRun)
+                    await deps.provider.transition(issue, "review");
+                continue;
+            }
+        }
+        const attempt = (marker?.attempt ?? 0) + 1;
+        if (attempt <= MAX_ORPHAN_ATTEMPTS) {
+            deps.log(`watch: #${issue.number} orphaned, retry ${attempt}/${MAX_ORPHAN_ATTEMPTS} — back to ready`);
+            if (!deps.dryRun) {
+                await deps.provider.writeMarker(issue, { ...marker, attempt });
+                await deps.provider.transition(issue, "ready");
+            }
+        }
+        else {
+            deps.log(`watch: #${issue.number} orphaned past ${MAX_ORPHAN_ATTEMPTS} attempts — blocked`);
+            if (!deps.dryRun) {
+                await deps.provider.transition(issue, "blocked", `Gave up after ${MAX_ORPHAN_ATTEMPTS} orphaned attempts.`);
+                cleanupWorktree(deps, marker);
+            }
+        }
+    }
+}
+/** Poll every `review`-labeled issue's PR for merged (-> done) or closed-without-merging (-> blocked). */
+export async function finishReviews(deps) {
+    const reviewing = await deps.provider.listInState("review", { includeAll: true });
+    for (const issue of reviewing) {
+        const marker = await deps.provider.readMarker(issue);
+        if (!marker?.pr)
+            continue;
+        const status = await deps.provider.prStatus({ number: marker.pr, branch: marker.branch ?? "", url: "" });
+        if (status.merged) {
+            deps.log(`watch: #${issue.number}'s PR #${marker.pr} merged — done`);
+            if (!deps.dryRun) {
+                await deps.provider.transition(issue, "done");
+                cleanupWorktree(deps, marker);
+            }
+        }
+        else if (status.state === "closed") {
+            deps.log(`watch: #${issue.number}'s PR #${marker.pr} closed without merging — blocked`);
+            if (!deps.dryRun) {
+                await deps.provider.transition(issue, "blocked", `PR #${marker.pr} was closed without merging.`);
+                cleanupWorktree(deps, marker);
+            }
+        }
+    }
+}
+/** One issue's full claim -> chain -> PR path, run in the background — `claimNewWork` doesn't await this. */
+async function runIssue(deps, issue) {
+    const branch = branchNameFor(issue);
+    const worktreePath = worktreePathFor(deps, issue);
+    const adwId = `issue-${issue.number}`;
+    try {
+        deps.git.fetch("origin", deps.baseBranch);
+        deps.git.worktreeAdd(worktreePath, branch, `origin/${deps.baseBranch}`);
+        await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, attempt: 0 });
+        const prompt = `${issue.title}\n\n${issue.body}`.trim();
+        const result = await deps.runChain({ prompt, cwd: worktreePath, adwId });
+        if (!result.accepted) {
+            deps.log(`watch: #${issue.number}: chain "${deps.chain}" did not succeed — blocked`);
+            await deps.provider.transition(issue, "blocked", result.detail || `Chain "${deps.chain}" (adw_id ${adwId}) did not complete successfully. Run \`spf phases ${adwId}\` for detail.`);
+            cleanupWorktree(deps, { worktree: worktreePath, branch });
+            return;
+        }
+        const wtGit = deps.worktreeGit(worktreePath);
+        if (wtGit.diffFiles(`origin/${deps.baseBranch}`).length === 0) {
+            deps.log(`watch: #${issue.number}: chain succeeded but committed nothing — blocked`);
+            await deps.provider.transition(issue, "blocked", `Chain "${deps.chain}" (adw_id ${adwId}) completed but left no committed changes.`);
+            cleanupWorktree(deps, { worktree: worktreePath, branch });
+            return;
+        }
+        wtGit.push("origin", branch);
+        const pr = await deps.provider.openPr(issue, {
+            branch,
+            title: `${issue.title} (#${issue.number})`,
+            body: `Automated by \`spf watch\` — chain \`${deps.chain}\`, adw_id \`${adwId}\`.`,
+            base: deps.baseBranch,
+        });
+        await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, pr: pr.number, attempt: 0 });
+        await deps.provider.transition(issue, "review");
+        deps.log(`watch: #${issue.number}: opened PR #${pr.number} — review`);
+    }
+    catch (error) {
+        const message = error.message;
+        deps.log(`watch: #${issue.number}: error: ${message}`);
+        await deps.provider.transition(issue, "blocked", `spf watch error: ${message}`).catch(() => undefined);
+        cleanupWorktree(deps, { worktree: worktreePath, branch });
+    }
+}
+/** Claim as many `ready` issues as the concurrency budget allows, and kick off `runIssue` for each in the background. */
+export async function claimNewWork(deps, state) {
+    if (state.inflight.size >= deps.concurrency)
+        return;
+    const eligible = await deps.provider.listEligible();
+    for (const issue of eligible) {
+        if (state.inflight.size >= deps.concurrency)
+            break;
+        if (state.inflight.has(issue.number))
+            continue;
+        if (deps.dryRun) {
+            deps.log(`watch: [dry-run] would claim #${issue.number} (${issue.title}) and run chain "${deps.chain}"`);
+            continue;
+        }
+        const claimed = await deps.provider.claim(issue);
+        if (!claimed) {
+            deps.log(`watch: #${issue.number} lost the claim race this tick — skipping`);
+            continue;
+        }
+        deps.log(`watch: claimed #${issue.number}: ${issue.title}`);
+        state.inflight.add(issue.number);
+        runIssue(deps, issue).finally(() => state.inflight.delete(issue.number));
+    }
+}
+/** One poll tick: reconcile, finish, claim — each independently caught, so one phase's error never blocks the rest. */
+export async function tick(deps, state) {
+    await reconcileOrphans(deps, state).catch((error) => deps.log(`watch: reconcileOrphans error: ${error.message}`));
+    await finishReviews(deps).catch((error) => deps.log(`watch: finishReviews error: ${error.message}`));
+    await claimNewWork(deps, state).catch((error) => deps.log(`watch: claimNewWork error: ${error.message}`));
+}

package/dist/test/agent_cc.test.d.ts

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