@gr8ful/spf 0.3.0 → 0.5.0

package/dist/core/providers.js

@@ -21,4 +21,8 @@ export const PROVIDER_ENV_KEYS = {
     deepseek: ["DEEPSEEK_API_KEY"],
     together: ["TOGETHER_API_KEY"],
     cerebras: ["CEREBRAS_API_KEY"],
+    // Keyless: a local server, not a hosted API — nothing to check for or
+    // prompt for. An empty array here means "known provider, needs no key",
+    // never "unknown provider" (that's a missing table entry, not `[]`).
+    ollama: [],
 };

package/dist/core/refine.d.ts

@@ -0,0 +1,39 @@
+import type { Issue, IssueAuthoringProvider } from "./issues/provider.ts";
+import type { RefinedIssue, SFConfig } from "./data_types.ts";
+export interface PublishedIssue {
+    /** The `RefinedIssue.key` this came from — a run-local id, never a tracker id. */
+    key: string;
+    issue: Issue;
+    kind: RefinedIssue["kind"];
+    /** A node nothing else names as `parent` — the independently-workable unit `spf:refined` goes on. */
+    isLeaf: boolean;
+}
+/**
+ * `IssueAuthoringProvider` has a real implementation only on `GitHubProvider`
+ * today — see `jira_provider.ts`'s module comment on why Jira isn't wired up
+ * yet. Throws rather than returning `null` so a `code` phase calling this
+ * (`steps.publishIssues()`) fails the phase with a clear, specific reason —
+ * the same "fail loudly, never silently do nothing" contract
+ * `agents.validate()` uses for an unconfigured quality suite.
+ */
+export declare function resolveAuthoringProvider(cfg: SFConfig): IssueAuthoringProvider;
+export interface PublishOptions {
+    labelPrefix: string;
+    /** The originating spec issue's id, for every created issue's `## Parent` back-reference. `null`/omitted for a manual run with no source issue. */
+    specIssueId?: string | null;
+}
+/**
+ * Create every node in `issues`, in dependency order, with its
+ * `<prefix>:type:<kind>` label (plus `<prefix>:refined` on leaves only —
+ * see `WatchState`'s doc comment in `provider.ts`), link each to its parent
+ * via the tracker's native hierarchy, and render real `#n` references into
+ * `## Blocked by`. Returns what it created, in creation order.
+ *
+ * Not transactional: if a create or link call throws partway through, the
+ * nodes already published stay published, orphaned from whatever hadn't run
+ * yet. No rollback is attempted — the gate already ran, so this only fails
+ * on a live tracker error (rate limit, network), which a human re-running
+ * the spec (once the marker's `refined` list explains what already exists)
+ * can sort out same as any other `spf watch` failure.
+ */
+export declare function publish(tracker: IssueAuthoringProvider, issues: RefinedIssue[], opts: PublishOptions): Promise<PublishedIssue[]>;

package/dist/core/refine.js

@@ -0,0 +1,152 @@
+/**
+ * Publish logic for the refine lane: turn a gated `RefineOutput.issues` list
+ * (a product spec decomposed into a feature/story tree — see
+ * `RefinedIssueSchema` in `data_types.ts`) into real tracker issues, in
+ * dependency order, with the right labels and parent/child links. Nothing
+ * else: no marker bookkeeping, no `transition()`, no comment posted back
+ * onto the spec issue. Those are watch-lifecycle concerns `core/watch.ts`'s
+ * `runSpec` owns, exactly the way `runIssue` (the build lane) owns
+ * `openPr`/`transition` rather than a chain step doing it — this file is
+ * "given issues and a tracker, create them correctly," the one part
+ * `to-tickets` (the skill this lane's prompt is ported from) leaves
+ * entirely unspecified, and the part that makes a re-run duplicate every
+ * ticket (see `WatchMarker.refined`'s doc comment in `provider.ts` for how
+ * `runSpec` closes that gap using what this module returns).
+ */
+import { GitHubProvider } from "./issues/github_provider.js";
+/**
+ * `IssueAuthoringProvider` has a real implementation only on `GitHubProvider`
+ * today — see `jira_provider.ts`'s module comment on why Jira isn't wired up
+ * yet. Throws rather than returning `null` so a `code` phase calling this
+ * (`steps.publishIssues()`) fails the phase with a clear, specific reason —
+ * the same "fail loudly, never silently do nothing" contract
+ * `agents.validate()` uses for an unconfigured quality suite.
+ */
+export function resolveAuthoringProvider(cfg) {
+    if (cfg.watch.issue_provider !== "github") {
+        throw new Error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} does not support issue authoring — ` +
+            `the refine lane needs "github" (see jira_provider.ts's module comment on why Jira isn't wired up yet)`);
+    }
+    // Issue authoring always targets the ISSUE tracker's repo — `issue_repo`
+    // if set, falling back to plain `repo` (the common case: issue_provider
+    // and code_host are both github, so they're the same repo). Reading
+    // `repo` alone would be wrong for a github-issues + bitbucket-code setup,
+    // where `repo` names the BITBUCKET repo (see WatchConfigSchema's doc
+    // comment) — this would try to create GitHub issues against a Bitbucket
+    // identifier.
+    const repo = cfg.watch.issue_repo.trim() || cfg.watch.repo.trim();
+    if (!repo) {
+        throw new Error(`watch.repo (or watch.issue_repo, if code_host names a different repo) is not configured — add it to spf.config.yaml's watch: section, e.g. "owner/name"`);
+    }
+    const token = process.env["GITHUB_TOKEN"];
+    if (!token) {
+        throw new Error('GITHUB_TOKEN is not set — the refine lane needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo)');
+    }
+    return new GitHubProvider(repo, cfg.watch.label_prefix, token);
+}
+function typeLabel(labelPrefix, kind) {
+    return `${labelPrefix}:type:${kind}`;
+}
+/**
+ * The body GitHub actually stores: the refiner's own `## What to build` /
+ * `## Acceptance criteria` text, plus a `## Parent` back-reference to the
+ * source spec (when there is one — a bare `spf refine` run with no
+ * `--issue` has none), plus a `## Blocked by` section with real `#n`
+ * references — `to-tickets`' own template shape, ported. Every `blocked_by`
+ * key is guaranteed to already be in `byKey` by the time this runs:
+ * `topoOrder` visits a node's dependencies before the node itself.
+ */
+function renderBody(node, byKey, specIssueId) {
+    const parts = [node.body.trim()];
+    if (specIssueId)
+        parts.push(`## Parent\n\nDecomposed from #${specIssueId}.`);
+    if (node.blocked_by.length > 0) {
+        const refs = node.blocked_by.map((key) => {
+            const published = byKey.get(key);
+            // Defensive only: gates.refinementWellFormed already rejects a
+            // blocked_by key that doesn't resolve to another node in the list.
+            return published ? `#${published.issue.id}` : key;
+        });
+        parts.push(`## Blocked by\n\n${refs.map((r) => `- ${r}`).join("\n")}`);
+    }
+    else {
+        parts.push(`## Blocked by\n\nNone (can start immediately).`);
+    }
+    return parts.join("\n\n");
+}
+/**
+ * Order nodes so every `parent` and every `blocked_by` reference is already
+ * published (a real issue, in `byKey`) before the node that names it —
+ * required both for the sub-issue link (the parent must exist first) and
+ * for `renderBody`'s `#n` references. `gates.refinementWellFormed` has
+ * already rejected a cyclic input by the time `publish()` ever runs; the
+ * `visiting` check here is a defensive backstop against a caller that
+ * skipped the gate, not the primary line of defense.
+ */
+function topoOrder(issues) {
+    const byKey = new Map(issues.map((i) => [i.key, i]));
+    const ordered = [];
+    const done = new Set();
+    const visiting = new Set();
+    function visit(node) {
+        if (done.has(node.key))
+            return;
+        if (visiting.has(node.key)) {
+            throw new Error(`refine: dependency cycle detected at key ${JSON.stringify(node.key)} — gates.refinementWellFormed should have caught this before publish ran`);
+        }
+        visiting.add(node.key);
+        for (const depKey of [node.parent, ...node.blocked_by]) {
+            if (!depKey)
+                continue;
+            const dep = byKey.get(depKey);
+            if (dep)
+                visit(dep);
+        }
+        visiting.delete(node.key);
+        done.add(node.key);
+        ordered.push(node);
+    }
+    for (const issue of issues)
+        visit(issue);
+    return ordered;
+}
+/**
+ * Create every node in `issues`, in dependency order, with its
+ * `<prefix>:type:<kind>` label (plus `<prefix>:refined` on leaves only —
+ * see `WatchState`'s doc comment in `provider.ts`), link each to its parent
+ * via the tracker's native hierarchy, and render real `#n` references into
+ * `## Blocked by`. Returns what it created, in creation order.
+ *
+ * Not transactional: if a create or link call throws partway through, the
+ * nodes already published stay published, orphaned from whatever hadn't run
+ * yet. No rollback is attempted — the gate already ran, so this only fails
+ * on a live tracker error (rate limit, network), which a human re-running
+ * the spec (once the marker's `refined` list explains what already exists)
+ * can sort out same as any other `spf watch` failure.
+ */
+export async function publish(tracker, issues, opts) {
+    const ordered = topoOrder(issues);
+    const childKeys = new Set(issues.filter((i) => i.parent).map((i) => i.parent));
+    const byKey = new Map();
+    const created = [];
+    for (const node of ordered) {
+        const isLeaf = !childKeys.has(node.key);
+        const labels = [typeLabel(opts.labelPrefix, node.kind)];
+        if (isLeaf)
+            labels.push(`${opts.labelPrefix}:refined`);
+        const body = renderBody(node, byKey, opts.specIssueId);
+        const issue = await tracker.createIssue({ title: node.title, body, labels });
+        const published = { key: node.key, issue, kind: node.kind, isLeaf };
+        byKey.set(node.key, published);
+        created.push(published);
+        if (node.parent) {
+            const parent = byKey.get(node.parent);
+            // topoOrder guarantees the parent was visited (and thus published)
+            // first; a missing entry here would mean the gate let an
+            // unresolved parent through, which refinementWellFormed rejects.
+            if (parent)
+                await tracker.linkChild(parent.issue, issue);
+        }
+    }
+    return created;
+}

package/dist/core/session.js

@@ -11,6 +11,15 @@ import { Run } from "./runner.js";
 import { Tracer } from "./tracer.js";
 import { engineerName, newId } from "./utils.js";
 import { resolveNotifier } from "./notify/notifier.js";
+import * as otel from "./otel.js";
+/**
+ * How long a signalled run may spend pushing spans before it exits anyway.
+ * Short on purpose: someone who just pressed ^C is waiting, and an
+ * observability projection is never worth making a kill feel broken. The
+ * budget is enforced inside `otel.flushAll()` (a raced, unref'd deadline), so
+ * an unreachable collector costs exactly this and not one tick more.
+ */
+const SIGNAL_DRAIN_MS = 750;
 /**
  * A killed run still closes its own trace.
  *
@@ -20,11 +29,31 @@ import { resolveNotifier } from "./notify/notifier.js";
  * flight that is already dead. Handling the signal both finalizes here and
  * lets the phase's try/catch record the phase as failed on the way out
  * (best-effort: a signal can still land mid-write).
+ *
+ * SQLite is written FIRST and synchronously, exactly as before — the otel
+ * drain is appended after it and can only ever cost time, never correctness.
+ * (`notify` has no equivalent drain on this path: its in-flight webhooks are
+ * dropped on a signal today. Fixing that means touching the notifier's
+ * lifecycle, which is outside this change; only the otel path is drained here.)
+ * A second signal during the drain exits immediately — someone pressing ^C
+ * twice means "now", and a shutdown path that ignores that is a hang.
  */
 function finalizeWhenKilled(run) {
+    let draining = false;
     const handler = (signal) => {
+        const code = 128 + (signal === "SIGINT" ? 2 : 15);
+        if (draining)
+            process.exit(code);
+        draining = true;
         run.tracer.sessionFinish(run.adw_id, false); // also closes process rows
-        process.exit(128 + (signal === "SIGINT" ? 2 : 15));
+        // Unconfigured (the default) exits SYNCHRONOUSLY, exactly as it did before
+        // otel existed — no extra tick between the signal and the exit for the
+        // repos that never opted in.
+        if (!run.tracer.otel)
+            process.exit(code);
+        // Bounded and never-throwing: flushAll() swallows its own failures and
+        // resolves on its own deadline, so this always reaches process.exit().
+        void otel.flushAll(SIGNAL_DRAIN_MS).then(() => process.exit(code), () => process.exit(code));
     };
     process.on("SIGTERM", handler);
     process.on("SIGINT", handler);
@@ -44,7 +73,15 @@ export function ensure(cfg, adwId, cwd, chainName) {
     const id = adwId || newId(8);
     const anchor = paths.resolveAnchor(cwd);
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
-    const tracer = new Tracer(dataPaths.db_path, path.join(dataPaths.sessions_dir, id, "events.jsonl"));
+    // `null` unless `observability.otel` is configured — no environment variable
+    // can turn this on (see core/otel.ts's EXPLICIT CONFIG ONLY). Constructed
+    // BEFORE the Tracer because the Tracer's write methods are the fan-out
+    // seams: SQLite stays the source of truth, otel is a projection off it, and
+    // registering here (module-level LIVE, exactly like resolveNotifier) is what
+    // lets the CLI's finally block and the signal handler above drain it without
+    // threading a handle through every call site.
+    const otelExporter = otel.resolveOtelExporter(cfg, { adwId: id, chainName: chainName || "adw" });
+    const tracer = new Tracer(dataPaths.db_path, path.join(dataPaths.sessions_dir, id, "events.jsonl"), otelExporter);
     const run = new Run({
         cfg,
         adwId: id,

package/dist/core/tracer.d.ts

@@ -2,18 +2,47 @@
  * 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.
+ *
+ * No push transport in the CONTROL flow — that is always, still, and only:
+ * agents -> sqlite -> web ui. SQLite is the source of truth; nothing
+ * downstream of it can affect a phase, a gate, or a run outcome.
+ *
+ * The one amendment: when (and only when) `observability.otel` is configured,
+ * each write method below ends with a single fan-out line to an optional
+ * OtelExporter — a lossy, allowlisted PROJECTION of what was just written,
+ * pushed to an OTLP endpoint fire-and-forget. It is deliberately NOT a second
+ * record: it never blocks, never throws into a caller (see `fanOut`), drops
+ * spans under backpressure, and carries only the allowlisted subset of fields
+ * (never `EventRecord.payload`, never the request text, never envelope
+ * contents — `core/otel.ts`'s header has the full list and the reasons).
+ * Methods whose data is entirely outside that allowlist —
+ * `sessionRequest` (the operator's prompt), `envelopeRow` (agent output),
+ * `processStart`/`processEnd` (pids) — have NO fan-out line on purpose. Do not
+ * add one.
  */
 import { Database } from "./sqlite.ts";
 import type { AgentConfig, EventRecord, GateReport, Phase } from "./data_types.ts";
+import type { OtelExporter } from "./otel.ts";
 export declare class Tracer {
     db: Database;
     dbPath: string;
     eventsJsonl: string;
-    constructor(dbPath: string, eventsJsonl: string);
+    /** `null` unless `observability.otel` is configured — see the header. */
+    otel: OtelExporter | null;
+    constructor(dbPath: string, eventsJsonl: string, otel?: OtelExporter | null);
     /** Additive column migrations, so a db from an older SPF still opens. */
     private migrate;
+    /**
+     * The ONE door to the optional otel projection, and the only reason a fan-out
+     * line is safe to put at the end of a synchronous write method: it is a
+     * no-op when unconfigured, and it swallows everything. An exporter bug, a
+     * malformed span, an exhausted queue — none of it may ever surface as a
+     * failed phase, because export is not allowed to dispose of anything. The
+     * exporter's own methods are synchronous enqueues; the network happens later,
+     * on an unref'd timer.
+     */
+    private fanOut;
     event(record: EventRecord): string;
     sessionStart(adwId: string, engineer: string, adwName?: string | null): void;
     sessionRequest(adwId: string, request: string): void;

package/dist/core/tracer.js

@@ -2,8 +2,24 @@
  * 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.
+ *
+ * No push transport in the CONTROL flow — that is always, still, and only:
+ * agents -> sqlite -> web ui. SQLite is the source of truth; nothing
+ * downstream of it can affect a phase, a gate, or a run outcome.
+ *
+ * The one amendment: when (and only when) `observability.otel` is configured,
+ * each write method below ends with a single fan-out line to an optional
+ * OtelExporter — a lossy, allowlisted PROJECTION of what was just written,
+ * pushed to an OTLP endpoint fire-and-forget. It is deliberately NOT a second
+ * record: it never blocks, never throws into a caller (see `fanOut`), drops
+ * spans under backpressure, and carries only the allowlisted subset of fields
+ * (never `EventRecord.payload`, never the request text, never envelope
+ * contents — `core/otel.ts`'s header has the full list and the reasons).
+ * Methods whose data is entirely outside that allowlist —
+ * `sessionRequest` (the operator's prompt), `envelopeRow` (agent output),
+ * `processStart`/`processEnd` (pids) — have NO fan-out line on purpose. Do not
+ * add one.
  */
 import { Database } from "./sqlite.js";
 import { appendFileSync, mkdirSync } from "node:fs";
@@ -97,7 +113,10 @@ export class Tracer {
     db;
     dbPath;
     eventsJsonl;
-    constructor(dbPath, eventsJsonl) {
+    /** `null` unless `observability.otel` is configured — see the header. */
+    otel;
+    constructor(dbPath, eventsJsonl, otel) {
+        this.otel = otel ?? null;
         mkdirSync(path.dirname(dbPath), { recursive: true });
         this.dbPath = dbPath;
         this.eventsJsonl = eventsJsonl;
@@ -118,6 +137,27 @@ export class Tracer {
             }
         }
     }
+    /**
+     * The ONE door to the optional otel projection, and the only reason a fan-out
+     * line is safe to put at the end of a synchronous write method: it is a
+     * no-op when unconfigured, and it swallows everything. An exporter bug, a
+     * malformed span, an exhausted queue — none of it may ever surface as a
+     * failed phase, because export is not allowed to dispose of anything. The
+     * exporter's own methods are synchronous enqueues; the network happens later,
+     * on an unref'd timer.
+     */
+    fanOut(action) {
+        if (!this.otel)
+            return;
+        try {
+            action(this.otel);
+        }
+        catch {
+            // Deliberately silent: a logged line per event on a hot path would be
+            // its own failure mode, and otel.ts already logs its own send failures
+            // exactly once.
+        }
+    }
     // ── events ──────────────────────────────────────────────────────────────
     event(record) {
         const eventId = `evt_${newId(12)}`;
@@ -128,23 +168,28 @@ export class Tracer {
             .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);
+        this.fanOut((otel) => otel.recordEvent(record, eventId, ts)); // otel projection — see fanOut
         return eventId;
     }
     // ── sessions ────────────────────────────────────────────────────────────
     sessionStart(adwId, engineer, adwName) {
+        const startedAt = nowIso();
         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);
+            .run(adwId, "running", engineer, startedAt);
+        if (adwName) {
+            // 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);
+            }
         }
+        // otel projection: the run's clock only. `engineer` is a person's name —
+        // outside the allowlist, and not a measure of anything.
+        this.fanOut((otel) => otel.recordSessionStart(startedAt));
     }
     sessionRequest(adwId, request) {
         this.db.query("UPDATE sessions SET request=? WHERE adw_id=?").run(request.slice(0, 500), adwId);
@@ -154,6 +199,7 @@ export class Tracer {
             .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
+        this.fanOut((otel) => otel.recordSessionFinish(ok)); // otel projection: emits the root run span, once
     }
     sessionAddUsage(adwId, tokens, cost) {
         this.db
@@ -208,6 +254,9 @@ export class Tracer {
          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);
+        // otel projection: a no-op on the start-of-phase upsert (no ended_at yet) —
+        // phase spans are emitted at phase END only. `phase.error` never crosses.
+        this.fanOut((otel) => otel.recordPhase(phase));
     }
     // ── envelopes / gates / agent sessions ──────────────────────────────────
     envelopeRow(phase, agent, outputType, payloadJson, valid, attempt) {
@@ -222,6 +271,10 @@ export class Tracer {
             .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());
+        // otel projection: gate name + verdict + violation COUNT as a span event on
+        // the phase span. The violation and check TEXT stays here in SQLite — it
+        // quotes the agent's claim and the repo's files.
+        this.fanOut((otel) => otel.recordGate(phase, gate, report, attempt));
     }
     /**
      * The agent's config row is the source of truth for its label and color.
@@ -242,5 +295,10 @@ export class Tracer {
          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);
+        // otel projection: the TYPED source of an agent's model + backend for its
+        // span (agents.ts writes this row before the agent_end event, which is what
+        // lets otel.ts avoid reading the agent_start payload at all). `sessionId`
+        // is not exported — it is a coding-agent handle, not a measure.
+        this.fanOut((otel) => otel.recordAgentSession(agent));
     }
 }

package/dist/core/watch.d.ts

@@ -6,6 +6,32 @@ export interface ChainRunResult {
     adwId: string;
     /** Shown to the engineer via a `blocked` comment on a failed/no-op run. */
     detail: string;
+    /**
+     * A short, already-sanitized/truncated digest of the reviewer's verdict
+     * (approved/blocking/findings), read back best-effort from the sessions DB
+     * — see `cli/commands/watch.ts`'s `runChain`. `undefined` when the chain
+     * that ran has no reviewer step, or the DB read/parse failed; `runIssue`
+     * below falls back to `reviewRequired` to tell those two apart in the PR
+     * body and `pr_opened` notification.
+     */
+    reviewSummary?: string;
+    /** Whether the chain that ran declares a "reviewer" in its `requiredAgents` — distinguishes "reviewer approved" from "nothing reviewed this change" when `reviewSummary` is absent. */
+    reviewRequired?: boolean;
+}
+/** One issue the refine lane created — enough for `finishSpec`'s summary comment and the marker's idempotency record. */
+export interface RefinedIssueRef {
+    id: string;
+    title: string;
+    kind: string;
+    isLeaf: boolean;
+}
+export interface RefineRunResult {
+    accepted: boolean;
+    adwId: string;
+    /** Shown to the engineer via a `blocked` comment on a failed/no-op run. */
+    detail: string;
+    /** What `steps.publishIssues()` created, read back from its side-channel file — see `cli/commands/watch.ts`'s `runRefine`. Empty when `!accepted`. */
+    created: RefinedIssueRef[];
 }
 export interface WatchDeps {
     provider: IssueProvider;
@@ -17,6 +43,23 @@ export interface WatchDeps {
     chain: string;
     baseBranch: string;
     concurrency: number;
+    /**
+     * The second lane — decomposing a `<prefix>:spec-ready` product spec
+     * instead of building a `<prefix>:ready` issue. `false` (the default) is
+     * a complete no-op: `claimSpecs`/`reconcileRefining` return immediately,
+     * so an existing `spf watch` config sees no new poll traffic at all until
+     * this is turned on. See `WatchConfigSchema`'s `refine` field.
+     */
+    refineEnabled: boolean;
+    refineConcurrency: number;
+    refineChain: string;
+    /** Same shape as `runChain`, for the refine lane — see its own doc comment for why the two aren't unified into one callback. */
+    runRefine: (opts: {
+        prompt: string;
+        cwd: string;
+        adwId: string;
+        issueId: string;
+    }) => Promise<RefineRunResult>;
     worktreesDir: string;
     /**
      * Symlink (or otherwise wire up) `<worktreePath>/.spf/data` to the MAIN
@@ -49,9 +92,22 @@ export interface WatchDeps {
 }
 export interface WatchRunState {
     inflight: Set<string>;
+    /**
+     * Separate from `inflight` — not a defensive copy of the same set, a
+     * genuinely different budget. The refine lane's `claimSpecs` caps against
+     * `refineConcurrency`, independent of the build lane's `concurrency`; a
+     * shared set would conflate "how many specs are being refined" with "how
+     * many issues are being built" and make either budget impossible to
+     * enforce on its own. The two never collide on an id in practice (a
+     * `spec-ready` issue and a `ready` issue are never the same issue), but
+     * that isn't why this is separate — the budgets are what require it.
+     */
+    refining: Set<string>;
 }
 export declare function createWatchState(): WatchRunState;
 export declare function branchNameFor(issue: Issue): string;
+/** Same idea as `branchNameFor`, for the refine lane's throwaway worktree — a spec never gets a PR, so this branch is only ever fetched-from-and-thrown-away, never pushed. */
+export declare function refineBranchNameFor(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
@@ -59,9 +115,19 @@ export declare function branchNameFor(issue: Issue): string;
  * merged) PR; otherwise retry up to `MAX_ORPHAN_ATTEMPTS`, then give up.
  */
 export declare function reconcileOrphans(deps: WatchDeps, state: WatchRunState): Promise<void>;
+/**
+ * The refine lane's own `reconcileOrphans` — a `refining`-labeled spec this
+ * process isn't tracking is either a completed publish that crashed before
+ * its own `transition(issue, "done")` ran (resume: finish it, no re-run),
+ * or a genuine orphan (retry up to `MAX_ORPHAN_ATTEMPTS`, then give up).
+ * A no-op entirely when `watch.refine` is off — see `WatchDeps.refineEnabled`.
+ */
+export declare function reconcileRefining(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. */
+/** Claim as many `spec-ready` specs as `refineConcurrency` allows, and kick off `runSpec` for each in the background. A no-op when `watch.refine` is off. */
+export declare function claimSpecs(deps: WatchDeps, state: WatchRunState): Promise<void>;
+/** One poll tick: reconcile both lanes, finish reviews, then claim both lanes — each stage independently caught, so one stage's error never blocks the rest. */
 export declare function tick(deps: WatchDeps, state: WatchRunState): Promise<void>;