@gr8ful/spf 0.5.1 → 0.7.0

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

@@ -9,19 +9,25 @@
  * interfaces, not one bundled seam — a tracker and a code host are
  * independent choices in practice (Jira issues against a Bitbucket repo is
  * a real setup, not a hypothetical one). `github_provider.ts`'s single
- * class implements both, since GitHub natively is both; `jira_provider.ts`
- * implements only `IssueProvider`, `bitbucket_provider.ts` only
- * `CodeHostProvider` — any tracker x host combination is just config
- * (`watch.issue_provider` x `watch.code_host`), never a poll-loop change.
+ * class implements all three (GitHub natively is a tracker, a code host,
+ * AND an authoring API); `jira_provider.ts` implements `IssueProvider` and
+ * `IssueAuthoringProvider` (Jira is a tracker and can author, but never
+ * opens PRs); `bitbucket_provider.ts` only `CodeHostProvider` — any tracker
+ * x host combination is just config (`watch.issue_provider` x
+ * `watch.code_host`), never a poll-loop change.
  * `IssueAuthoringProvider` (create/link, at the bottom of this file) is a
- * third, again separate — the refine lane's own need, optional per tracker,
- * and orthogonal to which one is the code host.
+ * third, again separate — the refine lane's own need, optional per tracker
+ * (not every tracker's write API can author + link a hierarchy), and
+ * orthogonal to which one is the code host. `isAuthoringProvider()` (below)
+ * is how the rest of the codebase asks "can this provider author?" without
+ * caring which concrete class answers yes.
  *
  * The label-as-state-machine design is deliberate, copied from that same
  * reference: `transition()` is the ONE mutator, so every state change is
  * traceable to one call site, and a provider can layer notifications
  * (Slack, a webhook, whatever) on top of it without the poll loop caring.
  */
+import type { RefinedIssue } from "../data_types.ts";
 /**
  * `spec-ready`/`refining` drive the SECOND lane's state machine (a product
  * spec being decomposed — see `reconcileRefining`/`claimSpecs` in
@@ -29,13 +35,36 @@
  * `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)
- * 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.
+ *
+ * `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.
+ *
+ * `spec-in-progress` is where a spec lands once it's been decomposed and
+ * published — deliberately NOT `done` yet: a product manager watching this
+ * spec's status must not see "done" until every issue the refiner produced
+ * (every story/bug/task, and every feature/epic container once its own
+ * children finish — see `rollUp` in `watch.ts`) is itself `<prefix>:done`.
+ * `announceRefined` (`watch.ts`) makes the move `refining -> spec-in-progress`
+ * once publish succeeds; `finishTrackedSpecs` (`watch.ts`) polls every
+ * `spec-in-progress` spec each tick and moves it the rest of the way,
+ * `-> done`, once `WatchMarker.refined` is entirely `<prefix>:done`.
+ *
+ * All eleven 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" | "spec-in-progress";
 export interface Issue {
     /** Opaque tracker identifier: a GitHub issue number stringified ("42"), a Jira key ("PROJ-123"). */
     id: string;
@@ -53,6 +82,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;
@@ -72,7 +110,18 @@ export interface PrStatus {
  * issue a completed publish pass created for this spec. A re-claimed spec
  * 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.
+ * duplicates every ticket on a re-run; this is what closes that gap. It does
+ * double duty once the spec reaches `spec-in-progress`: `finishTrackedSpecs`
+ * (`watch.ts`) reads this same list back to check whether every one of them
+ * is `<prefix>:done` yet — the gate on the spec's OWN move to `done`.
+ *
+ * `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 +129,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 {
@@ -100,6 +153,15 @@ export interface IssueProvider {
     ensureLabels(): Promise<EnsureLabelsResult>;
     /** Issues currently labeled `<prefix>:ready`. */
     listEligible(): Promise<Issue[]>;
+    /**
+     * One issue by its tracker-facing id, or `null` if it no longer exists
+     * (deleted, or — on a tracker where a closed item 404s a plain fetch —
+     * closed). The frontier check needs this on every tracker (`claimNewWork`
+     * in `watch.ts` calls it once per distinct `blocked_by` id per tick, to
+     * decide whether a leaf's blockers all carry `<prefix>:done`), so unlike
+     * `IssueAuthoringProvider`'s methods below, this is required, not optional.
+     */
+    getIssue(id: string): Promise<Issue | null>;
     /**
      * Issues currently in `state`. `includeAll` queries closed issues too —
      * required for `review` on a tracker where closing an issue is a side
@@ -133,6 +195,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
@@ -158,18 +237,44 @@ export interface CodeHostProvider {
  * provides (a tracker's read/claim/transition surface has no reason to
  * create new work items). Kept separate rather than folded into
  * `IssueProvider` for the same reason `CodeHostProvider` is separate: not
- * every tracker can do this (Jira could, in principle, via its native issue
- * types + `parent` field, but that is a real future implementation, not a
- * one-line stub — see `jira_provider.ts`'s module comment), and a tracker
- * that can't should be a `null` from `resolveIssueAuthoringProvider()`
- * (`cli/commands/watch.ts`), not a method that throws at call time.
+ * every tracker can do this — GitHub and Jira both implement it today
+ * (GitHub via sub-issues, Jira via native issue types + the `parent`
+ * field), Bitbucket does not — and a tracker that can't should be
+ * recognized as such via `isAuthoringProvider()` (below), not a method
+ * that throws at call time.
  */
 export interface IssueAuthoringProvider {
     createIssue(input: {
         title: string;
         body: string;
         labels: string[];
+        kind: RefinedIssue["kind"];
     }): Promise<Issue>;
-    /** Link `child` under `parent` using the tracker's native hierarchy — GitHub's sub-issues API today. */
+    /** Link `child` under `parent` using the tracker's native hierarchy — GitHub's sub-issues API, Jira's `parent` field. */
     linkChild(parent: Issue, child: Issue): Promise<void>;
+    /**
+     * Read back what `linkChild` wrote — every issue currently linked under
+     * `parent`. What makes container roll-up possible at all (`rollUp` in
+     * `watch.ts`: a container is `done` once every one of these carries
+     * `<prefix>:done`); lives here rather than on `IssueProvider` for the same
+     * reason `linkChild` does — a tracker's plain list/claim/transition surface
+     * has no reason to know about a hierarchy it may not even have. A tracker
+     * without this (Bitbucket-as-issue-tracker isn't a real combination this
+     * codebase supports, so in practice: any provider that isn't `IssueAuthoringProvider`
+     * at all) makes roll-up a logged no-op, not a startup failure the way
+     * `watch.refine.enabled` without ANY authoring support is
+     * (`cli/commands/watch.ts`) — the build lane still functions without
+     * roll-up, refine cannot function without authoring at all.
+     */
+    listChildren(parent: Issue): Promise<Issue[]>;
 }
+/**
+ * Structural, not nominal: checks for the three methods rather than
+ * `instanceof SomeConcreteClass` — so a new authoring-capable provider is
+ * recognized automatically everywhere this is used (today: `cli/commands/
+ * watch.ts`'s container-roll-up wiring) without an edit to an `instanceof`
+ * chain. Every current implementer (`GitHubProvider`, `JiraProvider`)
+ * satisfies `IssueProvider` too, so the intersection type is sound in
+ * practice, not just at the type level.
+ */
+export declare function isAuthoringProvider(provider: IssueProvider): provider is IssueProvider & IssueAuthoringProvider;

package/dist/core/issues/provider.js

@@ -9,17 +9,34 @@
  * interfaces, not one bundled seam — a tracker and a code host are
  * independent choices in practice (Jira issues against a Bitbucket repo is
  * a real setup, not a hypothetical one). `github_provider.ts`'s single
- * class implements both, since GitHub natively is both; `jira_provider.ts`
- * implements only `IssueProvider`, `bitbucket_provider.ts` only
- * `CodeHostProvider` — any tracker x host combination is just config
- * (`watch.issue_provider` x `watch.code_host`), never a poll-loop change.
+ * class implements all three (GitHub natively is a tracker, a code host,
+ * AND an authoring API); `jira_provider.ts` implements `IssueProvider` and
+ * `IssueAuthoringProvider` (Jira is a tracker and can author, but never
+ * opens PRs); `bitbucket_provider.ts` only `CodeHostProvider` — any tracker
+ * x host combination is just config (`watch.issue_provider` x
+ * `watch.code_host`), never a poll-loop change.
  * `IssueAuthoringProvider` (create/link, at the bottom of this file) is a
- * third, again separate — the refine lane's own need, optional per tracker,
- * and orthogonal to which one is the code host.
+ * third, again separate — the refine lane's own need, optional per tracker
+ * (not every tracker's write API can author + link a hierarchy), and
+ * orthogonal to which one is the code host. `isAuthoringProvider()` (below)
+ * is how the rest of the codebase asks "can this provider author?" without
+ * caring which concrete class answers yes.
  *
  * The label-as-state-machine design is deliberate, copied from that same
  * reference: `transition()` is the ONE mutator, so every state change is
  * traceable to one call site, and a provider can layer notifications
  * (Slack, a webhook, whatever) on top of it without the poll loop caring.
  */
-export {};
+/**
+ * Structural, not nominal: checks for the three methods rather than
+ * `instanceof SomeConcreteClass` — so a new authoring-capable provider is
+ * recognized automatically everywhere this is used (today: `cli/commands/
+ * watch.ts`'s container-roll-up wiring) without an edit to an `instanceof`
+ * chain. Every current implementer (`GitHubProvider`, `JiraProvider`)
+ * satisfies `IssueProvider` too, so the intersection type is sound in
+ * practice, not just at the type level.
+ */
+export function isAuthoringProvider(provider) {
+    const candidate = provider;
+    return typeof candidate.createIssue === "function" && typeof candidate.linkChild === "function" && typeof candidate.listChildren === "function";
+}

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" | "feature_done" | "spec_done";
 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/refine.d.ts

@@ -1,5 +1,5 @@
 import type { Issue, IssueAuthoringProvider } from "./issues/provider.ts";
-import type { RefinedIssue, SFConfig } from "./data_types.ts";
+import { type RefinedIssue, type RefinedPriority, type SFConfig } from "./data_types.ts";
 export interface PublishedIssue {
     /** The `RefinedIssue.key` this came from — a run-local id, never a tracker id. */
     key: string;
@@ -9,25 +9,62 @@ export interface PublishedIssue {
     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
+ * `IssueAuthoringProvider` has a real implementation on `GitHubProvider` and
+ * `JiraProvider` — any other `issue_provider` value fails here, defensively
+ * (the config schema's picklist already rejects it earlier). 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.
+ *
+ * Duplicates `cli/commands/watch.ts`'s own `resolveIssueProvider`
+ * construction logic for each provider — a pre-existing pattern for GitHub
+ * (this function has always rebuilt its own `GitHubProvider` rather than
+ * sharing one with the CLI layer's build-lane provider), mirrored for Jira
+ * rather than refactored away, to stay within this change's scope.
  */
 export declare function resolveAuthoringProvider(cfg: SFConfig): IssueAuthoringProvider;
+export interface RefineMarker {
+    /** The parent's real issue id, or `null` for a top-level node. */
+    parent: string | null;
+    /** Real issue ids — resolved from `blocked_by` `key`s at publish time, see `renderBody`. */
+    blocked_by: string[];
+    priority: RefinedPriority;
+}
+/**
+ * Pure and exported so it's directly unit-testable without a provider —
+ * `core/watch.ts`'s `claimNewWork` and `rollUp` are the real callers, reading
+ * it straight out of the `Issue.body` a `listEligible`/`getIssue` call
+ * already returned. Never throws: a body with no marker (any issue not
+ * created by this lane, or one whose marker a human stripped while editing)
+ * degrades to `NO_REFINE_MARKER`, same as malformed JSON inside one.
+ */
+export declare function parseRefineMarker(body: string): RefineMarker;
 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;
+    /**
+     * The spec's own priority (its `spf:priority:pN` label, read by
+     * `core/watch.ts`'s `runSpec`, or `spf refine`'s `--priority` flag for a
+     * bare manual run) — a CEILING, never a floor. Every node is clamped down
+     * to this if it outranks it (`clampPriority`), so a p3 "someday" spec
+     * cannot spawn p0 work that jumps the build lane's queue, regardless of
+     * what the refiner's own per-node judgment (or the gate's monotonicity
+     * check, which only sees the tree, never the spec) would otherwise allow.
+     * `null`/omitted — a bare run with nothing to inherit from — is a no-op:
+     * `clampPriority`'s own default.
+     */
+    priorityCeiling?: RefinedPriority | 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.
+ * `<prefix>:type:<kind>` and `<prefix>:priority:<pN>` labels (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` plus the
+ * hidden `spf-refine:` marker `parseRefineMarker` reads back. 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