@gr8ful/spf 0.5.1 → 0.7.0

package/dist/core/tiering.js

@@ -0,0 +1,235 @@
+/**
+ * Risk-tiered per-role model routing — SPF #14.
+ *
+ * PURE except for `probeServedOllamaTags`, the one async/impure export (a
+ * network probe — see its own doc comment below). Everything else here is a
+ * function of its own arguments: no `Run`, no `ChainContext`, no git handle,
+ * no filesystem. That purity is deliberate — it is what lets `startRun`
+ * (`src/chains/steps.ts`) and `spf estimate` call the IDENTICAL
+ * `resolveTiering` and get identical answers with no drift between "what
+ * will dispatch" and "what would dispatch".
+ *
+ * No imports from `src/chains/` and none from `src/cli/` — `spf doctor` and
+ * `startRun` both import FROM this module, never the reverse.
+ *
+ * ── The mechanism, in one paragraph ─────────────────────────────────────
+ * A run's `risk` (`low`/`standard`/`high`) is a single run-global scalar,
+ * classified once from the chain's name and the prompt's word count
+ * (`classifyRisk`). Separately, `tiering.roles` names a baseline tier per
+ * ROLE (an agent name) on `tiering.tiers`, a ladder ordered weakest first.
+ * `resolveTiering` shifts every routed role's baseline by the SAME step in
+ * the SAME direction (down for `low`, up for `high`), walking down to the
+ * nearest rung that is both available (§ probe) and backend-compatible
+ * (rule T) — never up, because a degradation must never silently escalate
+ * spend. An agent not named in `roles` is never touched: its own `model:`
+ * stands. `effectiveAgent` is the one place that turns a resolution into an
+ * actual `AgentConfig` — overriding `model` and NOTHING else.
+ */
+import { ollamaBaseUrl } from "./ollama_provider.js";
+// ── the classifier (design doc §2) ──────────────────────────────────────────
+/**
+ * One explicit `name -> weight` table entry per BUILT-IN chain
+ * (`src/chains/index.ts`'s `CHAINS`), including every chain that weighs
+ * `0` — an entry, not a fallthrough. A name absent from this table (any
+ * repo-local `.spf/chains/*.yaml` chain, or a built-in nobody has wired in
+ * yet) falls to `0` through `chainWeight`'s own default — a DIFFERENT code
+ * path from being explicitly listed as `0`, which is what lets a test
+ * assert "every built-in chain has a real entry here" rather than merely
+ * "this returned 0", so a new built-in nobody wired in cannot land in the
+ * `0` bucket unnoticed.
+ */
+export const CHAIN_WEIGHTS = {
+    scout: -1,
+    prompt: -1,
+    document: -1,
+    quality: -1,
+    "simple-sdlc": 1,
+    "plan-build-test-quality": 1,
+    refine: 1,
+    plan: 0,
+    build: 0,
+    "plan-build": 0,
+    "build-test": 0,
+    "plan-build-test": 0,
+    "build-review": 0,
+};
+/** `name in CHAIN_WEIGHTS` distinguishes "explicitly 0" from "fell through" — see `CHAIN_WEIGHTS`'s own comment. */
+export function chainWeight(name) {
+    return name in CHAIN_WEIGHTS ? CHAIN_WEIGHTS[name] : 0;
+}
+/** Whitespace-delimited word count, deliberately not tokens — no tokenizer exists for an arbitrary ollama/<tag>, and a word count is free, stable, and reproducible from the trace. */
+export function promptWords(prompt) {
+    return prompt.split(/\s+/).filter(Boolean).length;
+}
+/** `-1` for a terse ask, `+1` for a long one, `0` otherwise. */
+export function promptWeight(words) {
+    if (words <= 60)
+        return -1;
+    if (words >= 400)
+        return 1;
+    return 0;
+}
+/**
+ * The classifier. Asymmetric on purpose: demotion (`low`) requires TWO
+ * agreeing signals (`sum <= -2` — both `chain_weight` and `prompt_weight`
+ * at `-1`); promotion (`high`) requires only ONE. Concretely that means a
+ * long prompt (`prompt_weight === 1`, ≥400 words) forces `high`
+ * UNCONDITIONALLY, even riding on top of a `-1` chain (`spf scout "<≥400
+ * words>"` → `high`, not the `sum === 0` "standard" a naive `sum >= 1`
+ * threshold would give) — the design doc's own §2 3×3 table and its §3.1
+ * reachability table both pin this cell as `high`, so the table (not the
+ * simpler-looking `sum` arithmetic sketched alongside it) is what
+ * `src/test/tiering.test.ts`'s full-grid test treats as the specification.
+ * An unnecessarily weak model produces a wrong answer that costs a whole
+ * re-run — the expensive failure; an unnecessarily strong one just costs
+ * some tokens — the cheap failure. Skewed toward the cheap one.
+ */
+export function classifyRisk(chainName, prompt) {
+    const chain_weight = chainWeight(chainName);
+    const prompt_words = promptWords(prompt);
+    const prompt_weight = promptWeight(prompt_words);
+    const sum = chain_weight + prompt_weight;
+    const risk = prompt_weight === 1 || sum >= 1 ? "high" : sum <= -2 ? "low" : "standard";
+    return { risk, signals: { chain: chainName, chain_weight, prompt_words, prompt_weight, sum } };
+}
+const RISK_STEP = { low: -1, standard: 0, high: 1 };
+function stripOllamaPrefix(model) {
+    return model.startsWith("ollama/") ? model.slice("ollama/".length) : model;
+}
+/** Usable == not dropped by the availability probe, AND backend-compatible (rule T). */
+function usable(tier, agent, servedOllamaTags) {
+    if (tier.coding_agent !== agent.coding_agent)
+        return false; // rule T
+    if (servedOllamaTags !== null && tier.model.startsWith("ollama/")) {
+        // The comparison strips the "ollama/" prefix before lookup — getting
+        // this backwards fails CLOSED in the wrong direction: every ollama/*
+        // rung would look unserved and every ladder would walk to the bottom.
+        return servedOllamaTags.has(stripOllamaPrefix(tier.model));
+    }
+    return true;
+}
+/**
+ * The ladder walk (design doc §4.3). Never throws and never reports a
+ * severity — a backend mismatch (rule T) or an unknown tier name is a
+ * `notes` line plus a role left unrouted; `agents.validate()` owns
+ * severity, this owns detection.
+ */
+export function resolveTiering(input) {
+    const { cfg, chainName, prompt, servedOllamaTags, required } = input;
+    const { risk, signals } = classifyRisk(chainName, prompt);
+    const routing = {};
+    const notes = [];
+    if (!cfg.tiering.enabled)
+        return { risk, signals, routing, notes };
+    const step = RISK_STEP[risk];
+    for (const agentName of required) {
+        const baseline = cfg.tiering.roles[agentName];
+        if (baseline === undefined)
+            continue; // precedence: not named in roles -> untouched
+        const agent = cfg.agents.find((a) => a.name === agentName);
+        if (!agent) {
+            notes.push(`tiering.roles.${agentName} names an agent not defined in this roster — left unrouted, no change`);
+            continue;
+        }
+        const i = cfg.tiering.tiers.findIndex((t) => t.name === baseline);
+        if (i === -1) {
+            notes.push(`tiering.roles.${agentName} names tier ${JSON.stringify(baseline)}, which is not declared in tiering.tiers — left unrouted`);
+            continue;
+        }
+        const target = Math.min(Math.max(i + step, 0), cfg.tiering.tiers.length - 1);
+        let j = target;
+        while (j >= 0 && !usable(cfg.tiering.tiers[j], agent, servedOllamaTags))
+            j--;
+        if (j < 0) {
+            notes.push(`${agentName}: no rung at or below ${cfg.tiering.tiers[target].name} is usable for this run (unserved tag or backend mismatch) — ` +
+                `left unrouted, dispatching on ${agent.model}`);
+            continue;
+        }
+        const tier = cfg.tiering.tiers[j];
+        routing[agentName] = { tier: tier.name, configured: agent.model, effective: tier.model };
+    }
+    return { risk, signals, routing, notes };
+}
+/**
+ * The diff view, derived — `{agent: effective}` for entries where
+ * `configured !== effective`. Empty means tiering changed nothing this run.
+ * Deriving it (rather than storing it) is what keeps this view and the
+ * full `routing` map from disagreeing: one source, one filter.
+ */
+export function changedModels(res) {
+    const changed = {};
+    for (const [agentName, route] of Object.entries(res.routing)) {
+        if (route.configured !== route.effective)
+            changed[agentName] = route.effective;
+    }
+    return changed;
+}
+/**
+ * The single dispatch-site change (design doc §4.6): `model` and ONLY
+ * `model`. `run` is a minimal structural shape — deliberately not
+ * `agents.ts`'s `RunForAgents`, which would import this module and create a
+ * cycle — so any run-shaped object with an (optional) `tiering` field
+ * satisfies it.
+ */
+export function effectiveAgent(run, base) {
+    const effective = run.tiering?.routing[base.name]?.effective;
+    return effective === undefined ? base : { ...base, model: effective };
+}
+// ── availability probe (design doc §4.4B) ───────────────────────────────────
+const PROBE_TIMEOUT_MS = 3_000; // same budget spf doctor's own probeGet uses
+let cachedProbe;
+async function fetchServedOllamaTags() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+        // ollamaBaseUrl() is the SAME default-substitution a real dispatch
+        // uses, including treating a set-but-EMPTY OLLAMA_BASE_URL as unset —
+        // never re-derive that default here.
+        const url = ollamaBaseUrl().replace(/\/+$/, "") + "/models";
+        const res = await fetch(url, { signal: controller.signal });
+        if (res.status !== 200)
+            return null;
+        const body = (await res.json());
+        if (!body || !Array.isArray(body.data))
+            return null;
+        const tags = new Set();
+        for (const entry of body.data) {
+            if (entry && typeof entry === "object" && "id" in entry) {
+                tags.add(String(entry.id));
+            }
+        }
+        return tags; // bare tags — no "ollama/" prefix in the response
+    }
+    catch {
+        return null; // timeout | connection refused | unparseable body all fail OPEN
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * `Promise<Set<string> | null>` of bare (unprefixed) served Ollama tags, or
+ * `null` on any failure — non-200, timeout, connection refused, an
+ * unparseable/`data`-less body. `null` means "fail open, drop nothing",
+ * never "everything is unserved": an unreachable probe silently degrading
+ * every agent to the bottom rung is a worse outcome than the honest
+ * "Unknown model ID" error Ollama itself raises at first dispatch.
+ *
+ * Only actually probes when tiering is enabled AND at least one declared
+ * tier's model starts with `ollama/` — never on a run whose tiers are all
+ * hosted, and never when tiering is off. Memoized once per process.
+ *
+ * A NEW helper, not a reuse of `spf doctor`'s `probeGet`: that helper
+ * discards the response body, which is the only part that matters here.
+ */
+export async function probeServedOllamaTags(cfg) {
+    if (!cfg.tiering.enabled || !cfg.tiering.tiers.some((t) => t.model.startsWith("ollama/")))
+        return null;
+    if (cachedProbe === undefined)
+        cachedProbe = fetchServedOllamaTags();
+    return cachedProbe;
+}
+/** Test-only: `probeServedOllamaTags` memoizes once per process, so a test that stubs `fetch` differently across cases must reset the cache between them. */
+export function resetProbeCacheForTest() {
+    cachedProbe = undefined;
+}

package/dist/core/tracer.d.ts

@@ -31,6 +31,16 @@ export declare class Tracer {
     /** `null` unless `observability.otel` is configured — see the header. */
     otel: OtelExporter | null;
     constructor(dbPath: string, eventsJsonl: string, otel?: OtelExporter | null);
+    /**
+     * Close the sqlite handle. A one-shot CLI process never needs this — it
+     * exits right after its one Tracer anyway — but `spf watch`'s daemon loop
+     * builds a fresh Tracer (and a fresh `new Database(dbPath)`) per claimed
+     * issue, in-process, for the life of the daemon; without this, every
+     * issue's handle stayed open forever. Called from `session.ts`'s
+     * `finalize()`, once a run's own dispatch has fully settled — see its
+     * comment for why that timing is safe.
+     */
+    close(): void;
     /** Additive column migrations, so a db from an older SPF still opens. */
     private migrate;
     /**

package/dist/core/tracer.js

@@ -128,6 +128,18 @@ export class Tracer {
         this.db.exec(SCHEMA);
         this.migrate();
     }
+    /**
+     * Close the sqlite handle. A one-shot CLI process never needs this — it
+     * exits right after its one Tracer anyway — but `spf watch`'s daemon loop
+     * builds a fresh Tracer (and a fresh `new Database(dbPath)`) per claimed
+     * issue, in-process, for the life of the daemon; without this, every
+     * issue's handle stayed open forever. Called from `session.ts`'s
+     * `finalize()`, once a run's own dispatch has fully settled — see its
+     * comment for why that timing is safe.
+     */
+    close() {
+        this.db.close();
+    }
     /** Additive column migrations, so a db from an older SPF still opens. */
     migrate() {
         for (const [table, column, decl] of MIGRATIONS) {

package/dist/core/watch.d.ts

@@ -1,6 +1,7 @@
 import type { GitHandle } from "./git_helper.ts";
-import type { CodeHostProvider, Issue, IssueProvider } from "./issues/provider.ts";
+import type { CodeHostProvider, Issue, IssueComment, IssueProvider, WatchMarker, WatchState } from "./issues/provider.ts";
 import type { NotifyEvent } from "./notify/channel.ts";
+import { type RefinedPriority } from "./data_types.ts";
 export interface ChainRunResult {
     accepted: boolean;
     adwId: string;
@@ -18,20 +19,38 @@ export interface ChainRunResult {
     /** 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. */
+/** One issue the refine lane created — enough for `announceRefined`'s summary comment and the marker's idempotency record. */
 export interface RefinedIssueRef {
     id: string;
     title: string;
     kind: string;
     isLeaf: boolean;
 }
+/**
+ * One open question the refiner raised instead of a tree — mirrors
+ * `RefineQuestionSchema` (`core/data_types.ts`) field-for-field, kept as its
+ * own local shape rather than importing that type, the same way
+ * `RefinedIssueRef` above mirrors `RefinedIssue` rather than importing it:
+ * this module stays deliberately decoupled from the chain layer (see the
+ * module doc comment), reading only what `escalateSpec`'s comment needs.
+ */
+export interface RefinedQuestionRef {
+    id: string;
+    question: string;
+    why_it_matters: string;
+    options: string[];
+    recommendation: string;
+    evidence: string[];
+}
 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`. */
+    /** What `steps.publishIssues()` created, read back from its side-channel file — see `cli/commands/watch.ts`'s `runRefine`. Empty when `!accepted` or when the run escalated instead of publishing. */
     created: RefinedIssueRef[];
+    /** What the refiner is asking, read back from its own side-channel file — see `cli/commands/watch.ts`'s `runRefine`. Empty when `!accepted` or when the run published a tree instead of escalating; `gates.refinementWellFormed` guarantees `created` and `questions` are never both non-empty. */
+    questions: RefinedQuestionRef[];
 }
 export interface WatchDeps {
     provider: IssueProvider;
@@ -43,6 +62,17 @@ export interface WatchDeps {
     chain: string;
     baseBranch: string;
     concurrency: number;
+    /**
+     * `watch.chain_options` (see `WatchConfigSchema`'s doc comment) — passed
+     * unchanged into both `runChain`'s and `runRefine`'s opts below, exactly
+     * like `spf <chain> --suite <name>` builds an options map for an
+     * interactive dispatch (`cli/commands/run.ts`). Fixes the KNOWN
+     * LIMITATION from PR #20: an unattended `spf watch` dispatch used to call
+     * `runChainDef` with no options at all, so nothing --suite-shaped could
+     * ever reach it. One shared map for both lanes — `spf watch` has no
+     * separate `refine.chain_options` today.
+     */
+    chainOptions: Record<string, string>;
     /**
      * The second lane — decomposing a `<prefix>:spec-ready` product spec
      * instead of building a `<prefix>:ready` issue. `false` (the default) is
@@ -59,6 +89,7 @@ export interface WatchDeps {
         cwd: string;
         adwId: string;
         issueId: string;
+        chainOptions: Record<string, string>;
     }) => Promise<RefineRunResult>;
     worktreesDir: string;
     /**
@@ -78,7 +109,20 @@ export interface WatchDeps {
         prompt: string;
         cwd: string;
         adwId: string;
+        chainOptions: Record<string, string>;
     }) => Promise<ChainRunResult>;
+    /**
+     * `IssueAuthoringProvider.listChildren`'s read-back, injected as a bound
+     * function rather than a whole provider object — same reasoning as
+     * `runChain`/`runRefine`/`linkDataDir`: this module drives whatever it's
+     * given without importing a concrete provider type. `undefined` on any
+     * tracker that doesn't implement `IssueAuthoringProvider` (Jira today —
+     * see `jira_provider.ts`'s module comment); `rollUp` treats that as a
+     * logged no-op, not a failure — the build lane still functions without
+     * container roll-up, unlike the refine lane, which cannot function
+     * without authoring at all (see `cli/commands/watch.ts`'s startup check).
+     */
+    listChildren?: (parent: Issue) => Promise<Issue[]>;
     log: (message: string) => void;
     /**
      * Structured push, alongside `log`'s plain string — a required field, like
@@ -103,6 +147,20 @@ export interface WatchRunState {
      * that isn't why this is separate — the budgets are what require it.
      */
     refining: Set<string>;
+    /**
+     * Issue id -> its container's real issue id, recorded the moment
+     * `claimNewWork` claims a leaf whose hidden `spf-refine:` marker names a
+     * parent, deleted in the same `.finally()` that clears `inflight`. Zero
+     * API cost — no tracker read needed to populate it — and it's the whole
+     * basis of sibling affinity in `orderEligible`: a sibling of something
+     * already in flight sorts ahead of an equal-priority issue from an
+     * unrelated feature, so a feature already underway tends to finish before
+     * the daemon starts a new one instead of interleaving both. This holds
+     * only while a sibling is ACTUALLY in flight — a daemon restart begins
+     * with this empty, so ordering falls back to priority + created-asc until
+     * the in-memory picture rebuilds itself over the next few ticks.
+     */
+    inflightParents: Map<string, string>;
 }
 export declare function createWatchState(): WatchRunState;
 export declare function branchNameFor(issue: Issue): string;
@@ -115,19 +173,124 @@ export declare function refineBranchNameFor(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>;
+/**
+ * Poll every `spec-in-progress` spec: once every id `WatchMarker.refined`
+ * recorded — every issue the refiner produced, leaf or container — carries
+ * `<prefix>:done`, the spec's own decomposed work is actually finished, and
+ * only then does this move it `-> done`. This is the whole point of
+ * `announceRefined` landing on `spec-in-progress` rather than `done`
+ * straight away: the spec's status is what a product manager reads to know
+ * whether the work is finished, and "done" the instant a tree gets PUBLISHED
+ * would be a lie — the work hasn't started yet, let alone finished.
+ *
+ * A container in the refined list is done exactly when `rollUp` (see
+ * `finishReviews`) has already rolled it up — by the time every id here is
+ * `<prefix>:done`, every leaf beneath every container is too, transitively,
+ * with no need to walk the hierarchy again from this side.
+ *
+ * A referenced id that 404s (deleted from the tracker) is treated as
+ * satisfied — same policy as `frontierBlockedOn`'s blockers: a removed issue
+ * must not wedge the spec's completion forever. A spec with no marker, or an
+ * empty `refined` list, is left alone with a log line rather than assumed
+ * done — data that shouldn't exist given the gate's at-least-one-leaf rule,
+ * but never silently marked complete on that assumption.
+ */
+export declare function finishTrackedSpecs(deps: WatchDeps): Promise<void>;
+/**
+ * Render the spec issue's comment thread for the refiner's prompt, replacing
+ * the previous bare `title\n\nbody` — the whole reason a human's answer
+ * could never reach a resumed run before this feature. When `feedback` names
+ * the timestamp of the most recent question comment, everything at or after
+ * it is surfaced as "answers to your open questions" (what a resumed run
+ * most needs to read); everything earlier is "earlier discussion" — context,
+ * not necessarily an answer. A spec that has never been escalated (no
+ * `feedback`) has no such split: any pre-existing comments are all "earlier
+ * discussion".
+ *
+ * Truncates the RENDERED thread, not the comment list, to roughly
+ * `MAX_THREAD_CHARS`, dropping the oldest comments first — an explicit
+ * "N earlier comment(s) omitted" line, never a silent truncation.
+ *
+ * `priority` — the spec's own `<prefix>:priority:pN` label, read by
+ * `runSpec` below — renders as its own `## Priority` section right after the
+ * header, present or absent independent of whether there's any comment
+ * thread at all: a spec with no priority label (the common case today) omits
+ * the section entirely, exactly the prompt this function produced before
+ * priority existed. `core/refine.ts`'s `publish()` is what actually ENFORCES
+ * the ceiling this section only asks for — see its own doc comment.
+ *
+ * Exported and pure (no provider, no I/O) so it's directly unit-testable.
+ */
+export declare function buildSpecPrompt(issue: Issue, comments: IssueComment[], feedback?: WatchMarker["feedback"], priority?: RefinedPriority | null): string;
 /**
  * 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`.
+ * process isn't tracking is one of three things: a completed publish that
+ * crashed before its own `transition(issue, "done")` ran (resume: finish it,
+ * no re-run), a completed escalation that crashed before its own
+ * `transition(issue, "needs-feedback")` ran (resume: finish THAT transition,
+ * no re-asking — `escalateSpec` writes the marker's `feedback` before it
+ * transitions, so seeing `feedback` on a still-`refining` spec can only mean
+ * that last step didn't complete), 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. */
+/**
+ * Sort `issues` the way `claimNewWork` walks them: priority first (p0 ahead
+ * of p2 regardless of creation order), then sibling affinity (a leaf whose
+ * hidden marker names a parent already in `inflightParents.values()` sorts
+ * ahead of an equal-priority leaf from an unrelated feature — the mechanism
+ * that tends to finish one feature before starting the next, without giving
+ * up the one-PR-per-story design), then creation order (oldest first,
+ * matching `listByLabel`'s own `sort=created&direction=asc` — the final,
+ * stable tiebreaker when priority and affinity both tie).
+ *
+ * Pure and exported so it's directly unit-testable without a provider, same
+ * spirit as `buildSpecPrompt` below. Two honest limits, both already true of
+ * what feeds it: affinity only reflects a sibling ACTUALLY in flight in this
+ * process right now — a daemon restart begins with `inflightParents` empty,
+ * so ordering degrades to priority + created-asc until it rebuilds itself
+ * over the next few ticks; and priority is read from the label, so an issue
+ * a human just relabeled sorts by its NEW priority starting next tick, never
+ * retroactively re-ordering claims a previous tick already made.
+ */
+export declare function orderEligible(issues: Issue[], inflightParents: Map<string, string>, labelPrefix: string): Issue[];
+/**
+ * Claim as many `ready` issues as the concurrency budget allows, in priority
+ * + sibling-affinity + created-asc order (`orderEligible`), skipping any
+ * whose `blocked_by` isn't fully `<prefix>:done` yet (`frontierBlockedOn`),
+ * and kick off `runIssue` for each claimed one in the background.
+ */
 export declare function claimNewWork(deps: WatchDeps, state: WatchRunState): Promise<void>;
-/** 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. */
+/**
+ * Claim as many specs in `from` as `refineConcurrency` allows, and kick off
+ * `runSpec` for each in the background. A no-op when `watch.refine` is off.
+ *
+ * `from` defaults to `spec-ready` (a fresh spec) but `tick()` also calls this
+ * with `"continue-refinement"` — a human's signal that they've answered a
+ * prior round's questions and refinement should resume. Both share this same
+ * function (and `state.refining`'s budget) rather than a second copy of the
+ * claim loop, the same way the build lane's `claim()` itself takes a
+ * parameterized `{from, to}` rather than a hardcoded `ready -> working`.
+ *
+ * Known, deliberate wart: `claim()` only removes `from`'s label, so while a
+ * resumed run is in flight the issue briefly still carries
+ * `<prefix>:needs-feedback` alongside the (now claimed) `refining` state that
+ * replaced `continue-refinement`. Nothing polls `needs-feedback` on its own,
+ * and the run's own terminating `transition()` — to `needs-feedback` again,
+ * `done`, or `blocked` — strips every state label from the fresh snapshot it
+ * reads at that point, so this self-heals on the very next transition rather
+ * than needing a second mutator alongside `transition()`.
+ */
+export declare function claimSpecs(deps: WatchDeps, state: WatchRunState, from?: WatchState): 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. `claimSpecs` runs twice: resumed specs (`continue-refinement`,
+ * a human who already answered and is waiting) before fresh ones
+ * (`spec-ready`) — both share `state.refining`'s budget, so
+ * `refine.concurrency` still caps the lane as a whole either way.
+ */
 export declare function tick(deps: WatchDeps, state: WatchRunState): Promise<void>;