@gr8ful/spf 0.5.1 → 0.6.0

package/dist/core/issues/github_provider.js

@@ -1,5 +1,16 @@
 const API = "https://api.github.com";
-const STATES = ["ready", "working", "review", "done", "blocked", "spec-ready", "refining", "refined"];
+const STATES = [
+    "ready",
+    "working",
+    "review",
+    "done",
+    "blocked",
+    "spec-ready",
+    "refining",
+    "refined",
+    "needs-feedback",
+    "continue-refinement",
+];
 const MARKER_RE = /<!--\s*spf-watch:\s*(\{.*?\})\s*-->/s;
 /** The refine lane's leaf/container taxonomy — see `data_types.ts`'s `RefinedIssueSchema.kind`. Not a `WatchState`: these never appear on the left of a `transition()` call, so `transition()` never strips them. */
 export const ISSUE_KINDS = ["epic", "feature", "story", "bug", "task"];
@@ -13,6 +24,8 @@ const LABEL_META = {
     "spec-ready": { color: "0e8a16", description: "spf watch's refine lane will claim this spec on its next poll" },
     refining: { color: "fbca04", description: "spf watch has claimed this spec and is decomposing it into issues" },
     refined: { color: "c2e0c6", description: "generated by spf watch's refine lane — promote to spf:ready when it's worth building" },
+    "needs-feedback": { color: "d93f0b", description: "spf's refiner needs a human answer before it can finish decomposing this spec" },
+    "continue-refinement": { color: "0e8a16", description: "add this once you've answered — spf will resume refining from where it left off" },
 };
 const TYPE_LABEL_META = {
     epic: { color: "5319e7", description: "a container generated by spf watch's refine lane — not directly workable" },
@@ -221,8 +234,12 @@ export class GitHubProvider {
             body: JSON.stringify({ sub_issue_id: Number(child.internal_id) }),
         });
     }
+    /** The single fetch every comment-reading method (`findMarkerComment`, `listComments`) builds on. */
+    async fetchComments(issueId) {
+        return this.gh(`/repos/${this.repo}/issues/${issueId}/comments?per_page=100`);
+    }
     async findMarkerComment(issueId) {
-        const comments = await this.gh(`/repos/${this.repo}/issues/${issueId}/comments?per_page=100`);
+        const comments = await this.fetchComments(issueId);
         let found = null;
         for (const c of comments) {
             const match = MARKER_RE.exec(c.body || "");
@@ -251,4 +268,18 @@ export class GitHubProvider {
             await this.gh(`/repos/${this.repo}/issues/${issue.id}/comments`, { method: "POST", body: JSON.stringify({ body }) });
         }
     }
+    /** Oldest-first (GitHub's own comment order), the hidden marker comment filtered out. */
+    async listComments(issue) {
+        const comments = await this.fetchComments(issue.id);
+        return comments
+            .filter((c) => !MARKER_RE.test(c.body || ""))
+            .map((c) => ({ id: String(c.id), author: c.user?.login ?? "unknown", created_at: c.created_at, body: c.body || "" }));
+    }
+    /** `state_reason: "completed"` — the refine lane's own reason for closing a spec once it's fully decomposed; see `finishSpec` in `watch.ts`. */
+    async closeIssue(issue) {
+        await this.gh(`/repos/${this.repo}/issues/${issue.id}`, {
+            method: "PATCH",
+            body: JSON.stringify({ state: "closed", state_reason: "completed" }),
+        });
+    }
 }

package/dist/core/issues/jira_provider.d.ts

@@ -40,7 +40,7 @@
  * `issue_provider: jira` fails loudly at startup rather than silently
  * running a refine lane that can never publish anything.
  */
-import type { EnsureLabelsResult, Issue, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
+import type { EnsureLabelsResult, Issue, IssueComment, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
 export declare class JiraProvider implements IssueProvider {
     private readonly baseUrl;
     private readonly projectKey;
@@ -79,7 +79,11 @@ export declare class JiraProvider implements IssueProvider {
     }): Promise<boolean>;
     transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
     comment(issue: Issue, body: string): Promise<void>;
+    /** The single fetch every comment-reading method (`findMarkerComment`, `listComments`) builds on. */
+    private fetchComments;
     private findMarkerComment;
+    /** Oldest-first (Jira's own comment order), the hidden `[spf-watch-marker]` comment filtered out. */
+    listComments(issue: Issue): Promise<IssueComment[]>;
     readMarker(issue: Issue): Promise<WatchMarker | null>;
     writeMarker(issue: Issue, marker: WatchMarker): Promise<void>;
 }

package/dist/core/issues/jira_provider.js

@@ -1,4 +1,15 @@
-const STATES = ["ready", "working", "review", "done", "blocked", "spec-ready", "refining", "refined"];
+const STATES = [
+    "ready",
+    "working",
+    "review",
+    "done",
+    "blocked",
+    "spec-ready",
+    "refining",
+    "refined",
+    "needs-feedback",
+    "continue-refinement",
+];
 const MARKER_RE = /\[spf-watch-marker\]\s*(\{.*?\})/s;
 function toAdf(text) {
     return {
@@ -129,10 +140,15 @@ export class JiraProvider {
     async comment(issue, body) {
         await this.jira(`/rest/api/3/issue/${issue.id}/comment`, { method: "POST", body: JSON.stringify({ body: toAdf(body) }) });
     }
-    async findMarkerComment(issueId) {
+    /** The single fetch every comment-reading method (`findMarkerComment`, `listComments`) builds on. */
+    async fetchComments(issueId) {
         const result = await this.jira(`/rest/api/3/issue/${issueId}/comment?maxResults=100`);
+        return result.comments;
+    }
+    async findMarkerComment(issueId) {
+        const comments = await this.fetchComments(issueId);
         let found = null;
-        for (const c of result.comments) {
+        for (const c of comments) {
             const match = MARKER_RE.exec(adfToText(c.body));
             if (!match)
                 continue;
@@ -145,6 +161,13 @@ export class JiraProvider {
         }
         return found;
     }
+    /** Oldest-first (Jira's own comment order), the hidden `[spf-watch-marker]` comment filtered out. */
+    async listComments(issue) {
+        const comments = await this.fetchComments(issue.id);
+        return comments
+            .filter((c) => !MARKER_RE.test(adfToText(c.body)))
+            .map((c) => ({ id: c.id, author: c.author?.displayName ?? "unknown", created_at: c.created, body: adfToText(c.body) }));
+    }
     async readMarker(issue) {
         const found = await this.findMarkerComment(issue.id);
         return found?.marker ?? null;

package/dist/core/issues/provider.d.ts

@@ -29,13 +29,26 @@
  * `refined` is not a lane state at all — it never appears on the left of a
  * `transition()` call. It is the terminal label a generated LEAF issue
  * (story/bug/task) gets, marking it awaiting a human's promotion to `ready`.
- * All eight still live in one `WatchState` union (not two separate unions)
+ *
+ * `needs-feedback`/`continue-refinement` are the refine lane's human-in-the-
+ * loop loop, layered onto the same three states: a `refining` run whose
+ * refiner raised material ambiguity (see `RefineOutput.questions`) posts its
+ * questions and moves the spec to `needs-feedback` (`watch.ts`'s
+ * `escalateSpec`) instead of either finishing or blocking. A human answers in
+ * the issue's comments, then adds `continue-refinement` — `claimSpecs`
+ * accepts an optional `from` state precisely so it can claim
+ * `continue-refinement -> refining` the same way it claims
+ * `spec-ready -> refining`, resuming the SAME `adw_id` (deterministic from
+ * the issue id) with the comment thread folded into the prompt. This can
+ * loop any number of rounds; there is no cap.
+ *
+ * All ten still live in one `WatchState` union (not several separate unions)
  * because `transition()`'s "strip every `<prefix>:<state>` label, then add
  * one" logic (see `github_provider.ts`/`jira_provider.ts`) has to know about
  * every one of them to strip correctly, and `ensureLabels()` seeds all of
  * them from one `STATES` array.
  */
-export type WatchState = "ready" | "working" | "review" | "done" | "blocked" | "spec-ready" | "refining" | "refined";
+export type WatchState = "ready" | "working" | "review" | "done" | "blocked" | "spec-ready" | "refining" | "refined" | "needs-feedback" | "continue-refinement";
 export interface Issue {
     /** Opaque tracker identifier: a GitHub issue number stringified ("42"), a Jira key ("PROJ-123"). */
     id: string;
@@ -53,6 +66,15 @@ export interface Issue {
      */
     internal_id?: string;
 }
+/** One comment on an issue, as read back for the refine lane's escalation loop — see `IssueProvider.listComments`. */
+export interface IssueComment {
+    id: string;
+    /** Display handle — GitHub's `user.login`, Jira's `author.displayName`. */
+    author: string;
+    /** ISO 8601, verbatim from the tracker. */
+    created_at: string;
+    body: string;
+}
 export interface PrRef {
     number: number;
     branch: string;
@@ -73,6 +95,14 @@ export interface PrStatus {
  * whose marker already lists them skips creation entirely — `to-tickets`
  * (the skill this lane's prompt is ported from) has no such guard and
  * duplicates every ticket on a re-run; this is what closes that gap.
+ *
+ * `feedback` is the refine lane's human-in-the-loop cursor: `rounds` counts
+ * how many times this spec has been escalated (so a resumed run's summary
+ * comment can say "answered after 2 rounds"), and `asked_at` is the ISO
+ * timestamp of the most recent question comment — `watch.ts`'s
+ * `buildSpecPrompt` uses it to split the issue's comment thread into
+ * "answers to the open questions" versus "earlier discussion" when building
+ * the resumed run's prompt.
  */
 export interface WatchMarker {
     worktree?: string;
@@ -80,6 +110,10 @@ export interface WatchMarker {
     pr?: number;
     attempt?: number;
     refined?: string[];
+    feedback?: {
+        rounds: number;
+        asked_at: string;
+    };
 }
 /** What `ensureLabels()` actually did, per label — for `spf watch init`'s report. */
 export interface EnsureLabelsResult {
@@ -133,6 +167,23 @@ export interface IssueProvider {
     comment(issue: Issue, body: string): Promise<void>;
     readMarker(issue: Issue): Promise<WatchMarker | null>;
     writeMarker(issue: Issue, marker: WatchMarker): Promise<void>;
+    /**
+     * Oldest-first, the hidden marker comment excluded — the refine lane's
+     * escalation loop reads a human's answers back out of the thread (see
+     * `watch.ts`'s `buildSpecPrompt`). Every other seam on this interface is
+     * write-only towards comments (`comment()`, and `transition()`'s own
+     * `detail`); this is the one read.
+     */
+    listComments(issue: Issue): Promise<IssueComment[]>;
+    /**
+     * Close the issue as completed, where the tracker has such a concept.
+     * Optional, like `IssueAuthoringProvider`'s methods below: the label IS the
+     * state machine (see `transition()` above), and closing is a courtesy on
+     * top of `<prefix>:done`, never something `spf watch` itself reads back —
+     * a tracker (or a caller) that skips this leaves the spec `done` and open,
+     * exactly as every state before this feature existed already behaved.
+     */
+    closeIssue?(issue: Issue): Promise<void>;
 }
 /**
  * The PR-lifecycle seam, independent of `IssueProvider` — see the module

package/dist/core/notify/channel.d.ts

@@ -11,7 +11,7 @@
  * predicate a `Notifier` applies — no separate per-kind severity table to
  * keep in sync with this list.
  */
-export type NotifyKind = "run_started" | "run_finished" | "run_failed" | "phase_failed" | "phase_retry" | "watch_started" | "watch_stopped" | "watch_error" | "issue_claimed" | "pr_opened" | "issue_done" | "issue_blocked" | "spec_refined";
+export type NotifyKind = "run_started" | "run_finished" | "run_failed" | "phase_failed" | "phase_retry" | "watch_started" | "watch_stopped" | "watch_error" | "issue_claimed" | "pr_opened" | "issue_done" | "issue_blocked" | "spec_refined" | "spec_needs_feedback";
 export interface NotifyEvent {
     kind: NotifyKind;
     /** "error" sends under both `events: errors` and `events: all`; "info" only under `all`. */

package/dist/core/notify/notifier.d.ts

@@ -27,6 +27,14 @@ export declare class Notifier {
     send(event: NotifyEvent): void;
     /** Await every in-flight send — call before process exit so a slow webhook isn't dropped mid-flight. */
     flush(): Promise<void>;
+    /**
+     * Bounded drain: race `flush()` against `budgetMs`, never throwing. Mirrors
+     * `otel.ts`'s `OtelExporter.drain()` discipline — for the signal handler in
+     * `session.ts`, which is racing a hard ^C deadline shorter than any single
+     * channel's own `AbortSignal.timeout(timeoutMs)`, so a webhook to an
+     * unreachable host cannot hold the process open past `budgetMs`.
+     */
+    drain(budgetMs: number): Promise<void>;
 }
 /**
  * Build a `Notifier` from `cfg.notifications`, or `null` if it's off or no
@@ -40,3 +48,11 @@ export declare function resolveNotifier(cfg: SFConfig, opts?: {
 }): Notifier | null;
 /** Await every Notifier this process has created — call once, from the CLI's shutdown path. */
 export declare function flushAll(): Promise<void>;
+/**
+ * Bounded drain of every Notifier this process created, under one shared
+ * budget — the signal-handler twin of `flushAll()`. Called from
+ * `session.ts`'s SIGTERM/SIGINT handler, alongside `otel.flushAll()`, so a
+ * killed run's in-flight Slack/Teams/webhook sends get the same
+ * timeout-and-swallow chance the otel drain already had. Never throws.
+ */
+export declare function drainAll(budgetMs: number): Promise<void>;

package/dist/core/notify/notifier.js

@@ -47,6 +47,32 @@ export class Notifier {
     async flush() {
         await Promise.all([...this.pending]);
     }
+    /**
+     * Bounded drain: race `flush()` against `budgetMs`, never throwing. Mirrors
+     * `otel.ts`'s `OtelExporter.drain()` discipline — for the signal handler in
+     * `session.ts`, which is racing a hard ^C deadline shorter than any single
+     * channel's own `AbortSignal.timeout(timeoutMs)`, so a webhook to an
+     * unreachable host cannot hold the process open past `budgetMs`.
+     */
+    async drain(budgetMs) {
+        let deadline = null;
+        const budget = new Promise((resolve) => {
+            deadline = setTimeout(resolve, budgetMs);
+            deadline.unref?.();
+        });
+        try {
+            await Promise.race([this.flush(), budget]);
+        }
+        catch {
+            // unreachable in practice — every send() task is pre-caught into the log
+            // line above, so flush() never rejects — but a drain that can throw
+            // would break the shutdown path it exists to protect.
+        }
+        finally {
+            if (deadline)
+                clearTimeout(deadline);
+        }
+    }
 }
 function makeChannel(kind, url, name) {
     switch (kind) {
@@ -98,3 +124,13 @@ export function resolveNotifier(cfg, opts = {}) {
 export async function flushAll() {
     await Promise.all(LIVE.map((n) => n.flush()));
 }
+/**
+ * Bounded drain of every Notifier this process created, under one shared
+ * budget — the signal-handler twin of `flushAll()`. Called from
+ * `session.ts`'s SIGTERM/SIGINT handler, alongside `otel.flushAll()`, so a
+ * killed run's in-flight Slack/Teams/webhook sends get the same
+ * timeout-and-swallow chance the otel drain already had. Never throws.
+ */
+export async function drainAll(budgetMs) {
+    await Promise.all(LIVE.map((n) => n.drain(budgetMs)));
+}

package/dist/core/otel.d.ts

@@ -92,15 +92,41 @@
  * silently (see `parseTraceparent`) — a malformed variable must degrade to
  * "own root", never to an error.
  *
- * LIFECYCLE (copied from `notify/notifier.ts`'s discipline). A module-level
- * LIVE registry holds every exporter this process created; `flushAll()` is
- * awaited in `src/cli/index.ts`'s existing `finally` block next to
- * `notify.flushAll()`, AND `session.ts`'s signal handler runs a bounded,
- * timeout-capped drain before its `process.exit(128+n)` (notify does NOT do
- * that second one today — its in-flight webhooks are dropped on SIGTERM; only
- * the otel path is fixed here, on purpose, to keep this change to one seam).
- * Send failures log ONE line for the life of the exporter, with the endpoint
- * and every header VALUE redacted, and are then swallowed.
+ * LIFECYCLE (copied from `notify/notifier.ts`'s discipline, with one
+ * addition `notify` doesn't need — see RUN-SCOPED CLEANUP below). A
+ * module-level LIVE registry holds every exporter this process created;
+ * `flushAll()` is awaited in `src/cli/index.ts`'s existing `finally` block
+ * next to `notify.flushAll()`, AND `session.ts`'s signal handler runs a
+ * bounded, timeout-capped drain before its `process.exit(128+n)` (notify
+ * drains there too, via `drainAll()`, both racing the same budget
+ * concurrently — see #25). Send failures log ONE line for the life of the exporter,
+ * with the endpoint and every header VALUE redacted, and are then swallowed.
+ *
+ * RUN-SCOPED CLEANUP (#26). `notify`'s `LIVE` array has the same
+ * unbounded-growth problem under a long-lived daemon (tracked as #31, not
+ * fixed here). `spf watch` breaks the one-session-per-process assumption
+ * both registries were written under: its daemon loop runs many sessions
+ * in-process, one per claimed issue, and every one of them calls
+ * `resolveOtelExporter` — with no removal path, that was one exporter (plus
+ * its bounded span queue, its buffered-event maps, its open-agent-call
+ * tracking) held forever per issue processed, for the life of the daemon.
+ * `LIVE` is therefore keyed by adw_id (not a plain array) so a finished run
+ * can be found and dropped by id, and `releaseOtelExporter(adwId)` — called
+ * from `chains/index.ts`'s `runChain()`, the one call site every dispatch
+ * (one-shot CLI and `spf watch` alike) passes through on its way out,
+ * success or thrown error alike — drains that one exporter and removes it.
+ * Draining BEFORE removing matters: the removal itself must never be the
+ * reason a run's final root span goes unsent (that guarantee is what
+ * `flushAll()` already gave the one-shot CLI path, and this must not weaken
+ * it). And it must not run any EARLIER than "this run's own dispatch has
+ * fully settled" — a signal can still land while the run is in flight, and
+ * `session.ts`'s handler drains the GLOBAL registry, so an exporter removed
+ * before its run is actually done would silently stop being reachable from
+ * that drain. A one-shot invocation with no explicit `--adw-id` is a
+ * harmless no-op here (the registry key is the RESOLVED id `session.ensure`
+ * mints, which `runChain()`'s caller never sees) — that process exits right
+ * after anyway, so the existing end-of-process `flushAll()` still covers it
+ * exactly as it always did.
  *
  * BACKPRESSURE. `tracer.event()` fires per tool call on a hot path, so raw
  * promise-per-span fire-and-forget is a memory bug, not a style choice.
@@ -334,6 +360,14 @@ export declare class OtelExporter {
  * call site is `otel?.record...()` and never a conditional branch. `null` is
  * the default for every repo that has not configured an endpoint, and no
  * environment variable can change that (see EXPLICIT CONFIG ONLY).
+ *
+ * Registered under `opts.adwId` — the RESOLVED id (`session.ensure`'s own
+ * `id`, never a caller's possibly-null `ctx.adw_id`) — which is exactly the
+ * key `releaseOtelExporter` below looks it up by. A second registration
+ * under an id that's still live (in practice: a bug elsewhere, since adw_id
+ * is meant to be unique per in-flight run) replaces the map entry; the
+ * orphaned exporter's own queue still drains itself on its own unref'd
+ * timer, just unreachable from `flushAll()` from that point on.
  */
 export declare function resolveOtelExporter(cfg: SFConfig, opts: {
     adwId: string;
@@ -348,5 +382,26 @@ export declare function resolveOtelExporter(cfg: SFConfig, opts: {
  * handler. Never throws.
  */
 export declare function flushAll(budgetMs?: number): Promise<void>;
+/**
+ * The counterpart to `resolveOtelExporter`: drain and forget the one
+ * exporter registered for `adwId`, so a long-lived process (`spf watch`'s
+ * daemon loop) doesn't hold one exporter per run forever (see #26 / the
+ * RUN-SCOPED CLEANUP note above). Called from `chains/index.ts`'s
+ * `runChain()` once a run's own dispatch has fully settled — success or
+ * thrown error alike.
+ *
+ * A no-op, not an error, when `adwId` is falsy (a one-shot invocation with
+ * no explicit `--adw-id` — its caller never learns the id `session.ensure`
+ * actually minted, so it cannot ask for this by id; that process exits
+ * right after anyway and `flushAll()` still covers it) or when nothing is
+ * registered under it (otel unconfigured, or already released). Draining
+ * BEFORE deleting the map entry, never after: this run's exporter must stay
+ * reachable from a concurrent `flushAll()` (a signal landing on some OTHER
+ * still-in-flight run, under `spf watch`'s concurrency) for the full
+ * duration of ITS OWN drain, and removing the entry first would let that
+ * concurrent drain skip an exporter that has not actually finished sending
+ * yet.
+ */
+export declare function releaseOtelExporter(adwId: string | null | undefined, budgetMs?: number): Promise<void>;
 /** Tests only: forget every registered exporter so cases cannot leak into each other. */
 export declare function resetLiveForTest(): void;

package/dist/core/otel.js

@@ -92,15 +92,41 @@
  * silently (see `parseTraceparent`) — a malformed variable must degrade to
  * "own root", never to an error.
  *
- * LIFECYCLE (copied from `notify/notifier.ts`'s discipline). A module-level
- * LIVE registry holds every exporter this process created; `flushAll()` is
- * awaited in `src/cli/index.ts`'s existing `finally` block next to
- * `notify.flushAll()`, AND `session.ts`'s signal handler runs a bounded,
- * timeout-capped drain before its `process.exit(128+n)` (notify does NOT do
- * that second one today — its in-flight webhooks are dropped on SIGTERM; only
- * the otel path is fixed here, on purpose, to keep this change to one seam).
- * Send failures log ONE line for the life of the exporter, with the endpoint
- * and every header VALUE redacted, and are then swallowed.
+ * LIFECYCLE (copied from `notify/notifier.ts`'s discipline, with one
+ * addition `notify` doesn't need — see RUN-SCOPED CLEANUP below). A
+ * module-level LIVE registry holds every exporter this process created;
+ * `flushAll()` is awaited in `src/cli/index.ts`'s existing `finally` block
+ * next to `notify.flushAll()`, AND `session.ts`'s signal handler runs a
+ * bounded, timeout-capped drain before its `process.exit(128+n)` (notify
+ * drains there too, via `drainAll()`, both racing the same budget
+ * concurrently — see #25). Send failures log ONE line for the life of the exporter,
+ * with the endpoint and every header VALUE redacted, and are then swallowed.
+ *
+ * RUN-SCOPED CLEANUP (#26). `notify`'s `LIVE` array has the same
+ * unbounded-growth problem under a long-lived daemon (tracked as #31, not
+ * fixed here). `spf watch` breaks the one-session-per-process assumption
+ * both registries were written under: its daemon loop runs many sessions
+ * in-process, one per claimed issue, and every one of them calls
+ * `resolveOtelExporter` — with no removal path, that was one exporter (plus
+ * its bounded span queue, its buffered-event maps, its open-agent-call
+ * tracking) held forever per issue processed, for the life of the daemon.
+ * `LIVE` is therefore keyed by adw_id (not a plain array) so a finished run
+ * can be found and dropped by id, and `releaseOtelExporter(adwId)` — called
+ * from `chains/index.ts`'s `runChain()`, the one call site every dispatch
+ * (one-shot CLI and `spf watch` alike) passes through on its way out,
+ * success or thrown error alike — drains that one exporter and removes it.
+ * Draining BEFORE removing matters: the removal itself must never be the
+ * reason a run's final root span goes unsent (that guarantee is what
+ * `flushAll()` already gave the one-shot CLI path, and this must not weaken
+ * it). And it must not run any EARLIER than "this run's own dispatch has
+ * fully settled" — a signal can still land while the run is in flight, and
+ * `session.ts`'s handler drains the GLOBAL registry, so an exporter removed
+ * before its run is actually done would silently stop being reachable from
+ * that drain. A one-shot invocation with no explicit `--adw-id` is a
+ * harmless no-op here (the registry key is the RESOLVED id `session.ensure`
+ * mints, which `runChain()`'s caller never sees) — that process exits right
+ * after anyway, so the existing end-of-process `flushAll()` still covers it
+ * exactly as it always did.
  *
  * BACKPRESSURE. `tracer.event()` fires per tool call on a hot path, so raw
  * promise-per-span fire-and-forget is a memory bug, not a style choice.
@@ -755,14 +781,23 @@ function clip(value, limit = 200) {
     const text = String(value ?? "");
     return text.length <= limit ? text : text.slice(0, limit);
 }
-// ── module-level lifecycle (mirrors notify/notifier.ts's LIVE + flushAll) ───
-const LIVE = [];
+// ── module-level lifecycle (mirrors notify/notifier.ts's LIVE + flushAll,
+//    keyed by adw_id — see RUN-SCOPED CLEANUP above) ─────────────────────────
+const LIVE = new Map();
 /**
  * Build an exporter from `cfg.observability.otel`, or `null` when it is
  * absent — the same optional-dependency shape as `resolveNotifier`, so every
  * call site is `otel?.record...()` and never a conditional branch. `null` is
  * the default for every repo that has not configured an endpoint, and no
  * environment variable can change that (see EXPLICIT CONFIG ONLY).
+ *
+ * Registered under `opts.adwId` — the RESOLVED id (`session.ensure`'s own
+ * `id`, never a caller's possibly-null `ctx.adw_id`) — which is exactly the
+ * key `releaseOtelExporter` below looks it up by. A second registration
+ * under an id that's still live (in practice: a bug elsewhere, since adw_id
+ * is meant to be unique per in-flight run) replaces the map entry; the
+ * orphaned exporter's own queue still drains itself on its own unref'd
+ * timer, just unreachable from `flushAll()` from that point on.
  */
 export function resolveOtelExporter(cfg, opts) {
     const otel = cfg.observability.otel;
@@ -775,7 +810,7 @@ export function resolveOtelExporter(cfg, opts) {
         log: opts.log,
         env: opts.env,
     });
-    LIVE.push(exporter);
+    LIVE.set(opts.adwId, exporter);
     return exporter;
 }
 /**
@@ -785,9 +820,38 @@ export function resolveOtelExporter(cfg, opts) {
  * handler. Never throws.
  */
 export async function flushAll(budgetMs) {
-    await Promise.all(LIVE.map((exporter) => exporter.drain(budgetMs)));
+    await Promise.all([...LIVE.values()].map((exporter) => exporter.drain(budgetMs)));
+}
+/**
+ * The counterpart to `resolveOtelExporter`: drain and forget the one
+ * exporter registered for `adwId`, so a long-lived process (`spf watch`'s
+ * daemon loop) doesn't hold one exporter per run forever (see #26 / the
+ * RUN-SCOPED CLEANUP note above). Called from `chains/index.ts`'s
+ * `runChain()` once a run's own dispatch has fully settled — success or
+ * thrown error alike.
+ *
+ * A no-op, not an error, when `adwId` is falsy (a one-shot invocation with
+ * no explicit `--adw-id` — its caller never learns the id `session.ensure`
+ * actually minted, so it cannot ask for this by id; that process exits
+ * right after anyway and `flushAll()` still covers it) or when nothing is
+ * registered under it (otel unconfigured, or already released). Draining
+ * BEFORE deleting the map entry, never after: this run's exporter must stay
+ * reachable from a concurrent `flushAll()` (a signal landing on some OTHER
+ * still-in-flight run, under `spf watch`'s concurrency) for the full
+ * duration of ITS OWN drain, and removing the entry first would let that
+ * concurrent drain skip an exporter that has not actually finished sending
+ * yet.
+ */
+export async function releaseOtelExporter(adwId, budgetMs) {
+    if (!adwId)
+        return;
+    const exporter = LIVE.get(adwId);
+    if (!exporter)
+        return;
+    await exporter.drain(budgetMs);
+    LIVE.delete(adwId);
 }
 /** Tests only: forget every registered exporter so cases cannot leak into each other. */
 export function resetLiveForTest() {
-    LIVE.length = 0;
+    LIVE.clear();
 }

package/dist/core/runner.d.ts

@@ -12,6 +12,7 @@ import { type GitHandle } from "./git_helper.ts";
 import { Console } from "./console.ts";
 import { Tracer } from "./tracer.ts";
 import { type AgentCall, type EnvelopeBase, type Phase, type PhaseParams, type SFConfig } from "./data_types.ts";
+import type { TierResolution } from "./tiering.ts";
 import type { Notifier } from "./notify/notifier.ts";
 interface AgentMapEntry {
     session_id: string;
@@ -59,6 +60,13 @@ export declare class Run {
     session_dir: string;
     context_handoff_dir: string;
     agent_map: Record<string, AgentMapEntry>;
+    /**
+     * Set once by `startRun` (`src/chains/steps.ts`), before any phase opens —
+     * `null` until then. Not a `RunInit` field: it is computed FROM the `Run`
+     * (it needs `run.tracer`/`run.console` to trace and print its own
+     * finding), not passed into its construction. See `core/tiering.ts`.
+     */
+    tiering: TierResolution | null;
     private seq;
     private agentMapPath;
     constructor(init: RunInit);

package/dist/core/runner.js

@@ -64,6 +64,13 @@ export class Run {
     session_dir;
     context_handoff_dir;
     agent_map;
+    /**
+     * Set once by `startRun` (`src/chains/steps.ts`), before any phase opens —
+     * `null` until then. Not a `RunInit` field: it is computed FROM the `Run`
+     * (it needs `run.tracer`/`run.console` to trace and print its own
+     * finding), not passed into its construction. See `core/tiering.ts`.
+     */
+    tiering = null;
     seq; // a joined run continues the sequence
     agentMapPath;
     constructor(init) {

package/dist/core/session.d.ts

@@ -7,6 +7,31 @@
  */
 import { Run } from "./runner.ts";
 import type { SFConfig } from "./data_types.ts";
+/**
+ * The symmetric teardown for `finalizeWhenKilled()` above: drop `adwId` from
+ * `ACTIVE` (so a later signal can no longer reach it) and close its Tracer's
+ * sqlite handle. Call once a run's own dispatch has fully settled — success
+ * or thrown error alike; `chains/index.ts`'s `runChain()` finally is the one
+ * seam every dispatch path (one-shot CLI and `spf watch` alike) shares on
+ * the way out, exactly where `otel.releaseOtelExporter()` already lives for
+ * the identical reason (see otel.ts's RUN-SCOPED CLEANUP note / #26).
+ *
+ * Without this, `spf watch` held every finished run's `Run` (and its
+ * Tracer, its open sqlite handle, and its Notifier) strongly reachable from
+ * the signal listener for the rest of the daemon's life — the listener
+ * closes over the `run` a fresh `finalizeWhenKilled()` call captured, but
+ * since #26 only that one listener installs once now, and `ACTIVE` is the
+ * only thing keeping a finished run reachable from it.
+ *
+ * A one-shot invocation with no explicit `--adw-id` makes `adwId` here the
+ * caller's `ctx.adw_id` (`null`) rather than the id `session.ensure()`
+ * actually minted, so this is a harmless no-op for it — same caveat as
+ * `releaseOtelExporter`, and harmless for the same reason: that process
+ * exits right after anyway.
+ */
+export declare function finalize(adwId: string | null | undefined): void;
+/** Tests only: which adw_ids the process-wide signal handler currently considers active. */
+export declare function activeRunIdsForTest(): string[];
 /**
  * `cwd` anchors this run's repo_root and data_dir — it is NOT where the
  * process happened to start; it is an explicit decision, threaded down from