@gr8ful/spf 0.1.7 → 0.3.0

package/dist/core/data_types.js

@@ -310,12 +310,42 @@ export const WatchConfigSchema = v.object({
     concurrency: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 2),
     jira: v.optional(WatchJiraConfigSchema, () => v.parse(WatchJiraConfigSchema, {})),
 });
+/**
+ * Optional outbound push for unattended work (`spf watch`, any chain run) —
+ * everything else (`spf doctor`, `list`, `sessions`, ...) is interactive, so
+ * it stays console-only on purpose; see `core/notify/notifier.ts`.
+ *
+ * `events` is the whole filter: "off" sends nothing, "errors" sends only
+ * NotifyEvents whose `level` is "error", "all" sends every curated
+ * milestone. A channel's own `events` overrides the top-level scope for
+ * just that channel (e.g. Slack gets everything, Teams gets errors only).
+ *
+ * `webhook_url_env` names the .env key holding the secret URL — never the
+ * URL itself, matching GITHUB_TOKEN/JIRA_API_TOKEN. Empty = the kind's own
+ * default key (see core/notify/notifier.ts's DEFAULT_ENV_KEY).
+ */
+export const NotifyScopeSchema = v.picklist(["off", "errors", "all"]);
+export const NotifyChannelKindSchema = v.picklist(["slack", "teams", "webhook"]);
+export const NotifyChannelSchema = v.object({
+    kind: NotifyChannelKindSchema,
+    webhook_url_env: v.optional(v.string(), ""),
+    events: v.optional(v.nullable(NotifyScopeSchema)),
+    // Shown in warning lines / message footers to tell two channels of the
+    // same kind apart (e.g. two webhook: entries) — cosmetic only.
+    name: v.optional(v.string(), ""),
+});
+export const NotificationsConfigSchema = v.object({
+    events: v.optional(NotifyScopeSchema, "off"),
+    timeout_ms: v.optional(v.number(), 5_000),
+    channels: v.optional(v.array(NotifyChannelSchema), () => []),
+});
 export const SFConfigSchema = v.object({
     defaults: v.optional(ConfigDefaultsSchema, () => v.parse(ConfigDefaultsSchema, {})),
     observability: v.optional(ObservabilityConfigSchema, () => v.parse(ObservabilityConfigSchema, {})),
     agents: v.optional(v.array(AgentConfigSchema), () => []),
     quality: v.optional(QualityConfigSchema, () => v.parse(QualityConfigSchema, {})),
     watch: v.optional(WatchConfigSchema, () => v.parse(WatchConfigSchema, {})),
+    notifications: v.optional(NotificationsConfigSchema, () => v.parse(NotificationsConfigSchema, {})),
 });
 export function makeEventRecord(input) {
     return {

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

@@ -0,0 +1,32 @@
+/**
+ * The vocabulary a `NotificationChannel` speaks, and the seam itself —
+ * mirrors `core/issues/provider.ts`'s shape (an interface per concern,
+ * one small implementation module per backend).
+ *
+ * `NotifyKind` is a curated set of milestones, deliberately not the raw
+ * tracer event stream (`Tracer.event()` — see `core/tracer.ts`): a single
+ * chain run emits hundreds of `tool_call`/`log` events, which would need
+ * batching/rate-limiting to be a usable Slack message and would cut against
+ * the tracer's own "no push transport" design. `level` is the ENTIRE filter
+ * 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";
+export interface NotifyEvent {
+    kind: NotifyKind;
+    /** "error" sends under both `events: errors` and `events: all`; "info" only under `all`. */
+    level: "info" | "error";
+    /** One line, e.g. "run failed — plan-build-test". */
+    title: string;
+    /** The error text / PR body / block detail, if any. */
+    detail?: string;
+    /** Ordered label/value pairs — adw_id, chain, phase, tokens, cost, issue, pr, repo, ... */
+    fields: Array<[string, string]>;
+    /** A PR or issue link, when there is one. */
+    url?: string;
+}
+export interface NotificationChannel {
+    /** For warning lines — "slack", "teams (ops-bus)". */
+    readonly label: string;
+    send(event: NotifyEvent, timeoutMs: number): Promise<void>;
+}

package/dist/core/notify/channel.js

@@ -0,0 +1,14 @@
+/**
+ * The vocabulary a `NotificationChannel` speaks, and the seam itself —
+ * mirrors `core/issues/provider.ts`'s shape (an interface per concern,
+ * one small implementation module per backend).
+ *
+ * `NotifyKind` is a curated set of milestones, deliberately not the raw
+ * tracer event stream (`Tracer.event()` — see `core/tracer.ts`): a single
+ * chain run emits hundreds of `tool_call`/`log` events, which would need
+ * batching/rate-limiting to be a usable Slack message and would cut against
+ * the tracer's own "no push transport" design. `level` is the ENTIRE filter
+ * predicate a `Notifier` applies — no separate per-kind severity table to
+ * keep in sync with this list.
+ */
+export {};

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

@@ -0,0 +1,42 @@
+/**
+ * Filter, fan-out, and lifecycle for outbound notifications. A notification
+ * must never be able to break a run: `send()` never throws and never
+ * blocks — it fires the request and tracks it in a pending set, and a
+ * failure is swallowed after logging one line (the URL itself never
+ * appears in that line, or anywhere else — see `resolveNotifier` below).
+ *
+ * `resolveNotifier` returns `null` when notifications are off or no
+ * channel resolved, so every call site uses the same `notifier?.send(...)`
+ * shape as an optional dependency, not a conditional branch.
+ */
+import type { NotifyEvent, NotificationChannel } from "./channel.ts";
+import type { NotifyScope, SFConfig } from "../data_types.ts";
+/** Exported so `spf doctor` and the init interview can name the same key without duplicating this table. */
+export declare const DEFAULT_NOTIFY_ENV_KEY: Record<string, string>;
+export declare class Notifier {
+    private readonly channels;
+    private readonly timeoutMs;
+    private readonly dryRun;
+    private readonly log;
+    private pending;
+    constructor(channels: Array<{
+        channel: NotificationChannel;
+        scope: NotifyScope;
+    }>, timeoutMs: number, dryRun: boolean, log?: (message: string) => void);
+    /** Sync, fire-and-forget — every call site is sync and must stay that way. */
+    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>;
+}
+/**
+ * Build a `Notifier` from `cfg.notifications`, or `null` if it's off or no
+ * channel resolved. A channel whose env var isn't set is skipped with one
+ * warning naming the missing key — never a hard failure, since a broken
+ * notification setup shouldn't stop the work it's supposed to report on.
+ */
+export declare function resolveNotifier(cfg: SFConfig, opts?: {
+    dryRun?: boolean;
+    log?: (message: string) => void;
+}): Notifier | null;
+/** Await every Notifier this process has created — call once, from the CLI's shutdown path. */
+export declare function flushAll(): Promise<void>;

package/dist/core/notify/notifier.js

@@ -0,0 +1,100 @@
+import { SlackChannel } from "./slack_channel.js";
+import { TeamsChannel } from "./teams_channel.js";
+import { WebhookChannel } from "./webhook_channel.js";
+/** Exported so `spf doctor` and the init interview can name the same key without duplicating this table. */
+export const DEFAULT_NOTIFY_ENV_KEY = {
+    slack: "SLACK_WEBHOOK_URL",
+    teams: "TEAMS_WEBHOOK_URL",
+    webhook: "SPF_WEBHOOK_URL",
+};
+/** `errors` mode only sends `level: "error"`; `all` sends everything; `off` sends nothing. */
+function scopeAllows(scope, level) {
+    if (scope === "off")
+        return false;
+    if (scope === "all")
+        return true;
+    return level === "error";
+}
+export class Notifier {
+    channels;
+    timeoutMs;
+    dryRun;
+    log;
+    pending = new Set();
+    constructor(channels, timeoutMs, dryRun, log = (m) => console.error(m)) {
+        this.channels = channels;
+        this.timeoutMs = timeoutMs;
+        this.dryRun = dryRun;
+        this.log = log;
+    }
+    /** Sync, fire-and-forget — every call site is sync and must stay that way. */
+    send(event) {
+        for (const { channel, scope } of this.channels) {
+            if (!scopeAllows(scope, event.level))
+                continue;
+            if (this.dryRun) {
+                this.log(`spf: would notify (${channel.label}): ${event.title}`);
+                continue;
+            }
+            const task = channel.send(event, this.timeoutMs).catch((error) => {
+                this.log(`spf: ${channel.label} notification failed: ${error.message}`);
+            });
+            this.pending.add(task);
+            task.finally(() => this.pending.delete(task));
+        }
+    }
+    /** Await every in-flight send — call before process exit so a slow webhook isn't dropped mid-flight. */
+    async flush() {
+        await Promise.all([...this.pending]);
+    }
+}
+function makeChannel(kind, url, name) {
+    switch (kind) {
+        case "slack":
+            return new SlackChannel(url, name);
+        case "teams":
+            return new TeamsChannel(url, name);
+        case "webhook":
+            return new WebhookChannel(url, name);
+        default:
+            return null;
+    }
+}
+// Every live Notifier this process created — so the CLI's shutdown path can
+// flush all of them without threading a handle through every call site,
+// matching agent_flue.shutdown()/agent_cc.shutdown()'s module-level shape.
+const LIVE = [];
+/**
+ * Build a `Notifier` from `cfg.notifications`, or `null` if it's off or no
+ * channel resolved. A channel whose env var isn't set is skipped with one
+ * warning naming the missing key — never a hard failure, since a broken
+ * notification setup shouldn't stop the work it's supposed to report on.
+ */
+export function resolveNotifier(cfg, opts = {}) {
+    const nc = cfg.notifications;
+    if (nc.events === "off" || nc.channels.length === 0)
+        return null;
+    const log = opts.log ?? ((m) => console.error(m));
+    const resolved = [];
+    for (const entry of nc.channels) {
+        const envKey = entry.webhook_url_env || DEFAULT_NOTIFY_ENV_KEY[entry.kind];
+        const url = process.env[envKey];
+        if (!url) {
+            log(`spf: notifications.channels[kind=${entry.kind}] is configured but ${envKey} is not set — skipping this channel`);
+            continue;
+        }
+        const channel = makeChannel(entry.kind, url, entry.name);
+        if (!channel)
+            continue;
+        resolved.push({ channel, scope: entry.events ?? nc.events });
+    }
+    if (resolved.length === 0)
+        return null;
+    const notifier = new Notifier(resolved, nc.timeout_ms, Boolean(opts.dryRun), log);
+    LIVE.push(notifier);
+    return notifier;
+}
+/** Await every Notifier this process has created — call once, from the CLI's shutdown path. */
+export async function flushAll() {
+    await Promise.all(LIVE.map((n) => n.flush()));
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Slack Incoming Webhook — a plain `POST` of a Block Kit payload, via native
+ * `fetch()` (same no-dependency stance as `core/issues/github_provider.ts`).
+ * Set up: Slack app -> Incoming Webhooks -> "Add New Webhook to Workspace".
+ * https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks
+ */
+import type { NotificationChannel, NotifyEvent } from "./channel.ts";
+export declare class SlackChannel implements NotificationChannel {
+    private readonly webhookUrl;
+    readonly label: string;
+    constructor(webhookUrl: string, name?: string);
+    send(event: NotifyEvent, timeoutMs: number): Promise<void>;
+}

package/dist/core/notify/slack_channel.js

@@ -0,0 +1,30 @@
+export class SlackChannel {
+    webhookUrl;
+    label;
+    constructor(webhookUrl, name = "") {
+        this.webhookUrl = webhookUrl;
+        this.label = name ? `slack (${name})` : "slack";
+    }
+    async send(event, timeoutMs) {
+        const emoji = event.level === "error" ? ":x:" : ":white_check_mark:";
+        const fieldsText = event.fields.map(([k, v]) => `*${k}:* ${v}`).join("  ·  ");
+        const body = {
+            text: `${emoji} ${event.title}`,
+            blocks: [
+                { type: "section", text: { type: "mrkdwn", text: `${emoji} *${event.title}*` } },
+                ...(event.detail ? [{ type: "section", text: { type: "mrkdwn", text: event.detail.slice(0, 2900) } }] : []),
+                ...(fieldsText ? [{ type: "context", elements: [{ type: "mrkdwn", text: fieldsText }] }] : []),
+                ...(event.url ? [{ type: "section", text: { type: "mrkdwn", text: `<${event.url}|open>` } }] : []),
+            ],
+        };
+        const response = await fetch(this.webhookUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok) {
+            throw new Error(`slack webhook -> ${response.status}: ${(await response.text().catch(() => "")).slice(0, 300)}`);
+        }
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Microsoft Teams via a Power Automate "Workflows" webhook, posting an
+ * Adaptive Card. This is the ONLY supported path: the legacy Office 365
+ * connector webhook (a bare `MessageCard`/`@type` POST straight to a
+ * channel-configured URL) has been retired by Microsoft. Set up: in the
+ * target channel, add a Workflows webhook template (naming has shifted
+ * between Microsoft revisions — search for one along the lines of "Post to
+ * a channel when a webhook request is received") and copy the generated URL.
+ * https://support.microsoft.com/en-us/office/post-a-workflow-when-a-webhook-request-is-received-in-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498
+ */
+import type { NotificationChannel, NotifyEvent } from "./channel.ts";
+export declare class TeamsChannel implements NotificationChannel {
+    private readonly webhookUrl;
+    readonly label: string;
+    constructor(webhookUrl: string, name?: string);
+    send(event: NotifyEvent, timeoutMs: number): Promise<void>;
+}

package/dist/core/notify/teams_channel.js

@@ -0,0 +1,38 @@
+export class TeamsChannel {
+    webhookUrl;
+    label;
+    constructor(webhookUrl, name = "") {
+        this.webhookUrl = webhookUrl;
+        this.label = name ? `teams (${name})` : "teams";
+    }
+    async send(event, timeoutMs) {
+        const color = event.level === "error" ? "attention" : "good";
+        const facts = event.fields.map(([title, value]) => ({ title, value }));
+        const card = {
+            type: "AdaptiveCard",
+            $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+            version: "1.4",
+            body: [
+                { type: "TextBlock", text: event.title, weight: "bolder", size: "medium", color, wrap: true },
+                ...(event.detail ? [{ type: "TextBlock", text: event.detail.slice(0, 2900), wrap: true }] : []),
+                ...(facts.length > 0 ? [{ type: "FactSet", facts }] : []),
+            ],
+            ...(event.url
+                ? { actions: [{ type: "Action.OpenUrl", title: "Open", url: event.url }] }
+                : {}),
+        };
+        const body = {
+            type: "message",
+            attachments: [{ contentType: "application/vnd.microsoft.card.adaptive", contentUrl: null, content: card }],
+        };
+        const response = await fetch(this.webhookUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok) {
+            throw new Error(`teams webhook -> ${response.status}: ${(await response.text().catch(() => "")).slice(0, 300)}`);
+        }
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * A generic webhook: `POST` the `NotifyEvent` as raw JSON, no vendor shape.
+ * Covers Discord/n8n/Zapier/a homegrown receiver with no new channel module
+ * each time, and is what `notify.test.ts` posts against a real local
+ * `node:http` receiver instead of mocking `fetch`.
+ */
+import type { NotificationChannel, NotifyEvent } from "./channel.ts";
+export declare class WebhookChannel implements NotificationChannel {
+    private readonly url;
+    readonly label: string;
+    constructor(url: string, name?: string);
+    send(event: NotifyEvent, timeoutMs: number): Promise<void>;
+}

package/dist/core/notify/webhook_channel.js

@@ -0,0 +1,19 @@
+export class WebhookChannel {
+    url;
+    label;
+    constructor(url, name = "") {
+        this.url = url;
+        this.label = name ? `webhook (${name})` : "webhook";
+    }
+    async send(event, timeoutMs) {
+        const response = await fetch(this.url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(event),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok) {
+            throw new Error(`webhook -> ${response.status}: ${(await response.text().catch(() => "")).slice(0, 300)}`);
+        }
+    }
+}

package/dist/core/prompts.d.ts

@@ -1,4 +1,6 @@
 /** Prompt rendering: load system/user refs from config, replace {{placeholders}}. */
+/** Shared instructions for any documenter call fed a change.asEnvelope() capture. */
+export declare const DOCUMENT_NOTES = "Read diff_path in full before writing. Document only what the diff shows, then copy the write-up into app_docs/ as your task describes.";
 export declare function render(templatePath: string, variables: Record<string, string>): string;
 /** Save the exact prompt sent, before execution — the audit copy. */
 export declare function save(directory: string, name: string, content: string): string;

package/dist/core/prompts.js

@@ -1,6 +1,8 @@
 /** Prompt rendering: load system/user refs from config, replace {{placeholders}}. */
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
+/** Shared instructions for any documenter call fed a change.asEnvelope() capture. */
+export const DOCUMENT_NOTES = "Read diff_path in full before writing. Document only what the diff shows, then copy the write-up into app_docs/ as your task describes.";
 export function render(templatePath, variables) {
     let text = readFileSync(templatePath, "utf-8");
     for (const [key, value] of Object.entries(variables)) {

package/dist/core/providers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Common Flue providers' env var conventions — public knowledge (pi-ai's own
+ * resolution table is internal, unexported, and not something to reach into
+ * for this). Missing from this table just means "unknown provider, skipped
+ * the key check" — never a false failure.
+ *
+ * Shared by `spf doctor` (checks whichever key the configured model's
+ * provider prefix implies) and the `spf init` interview (asks for the key up
+ * front, keyed off the provider the user picked) — one table, so the two
+ * can never drift apart on what a provider needs.
+ */
+export declare const PROVIDER_ENV_KEYS: Record<string, string[]>;

package/dist/core/providers.js

@@ -0,0 +1,24 @@
+/**
+ * Common Flue providers' env var conventions — public knowledge (pi-ai's own
+ * resolution table is internal, unexported, and not something to reach into
+ * for this). Missing from this table just means "unknown provider, skipped
+ * the key check" — never a false failure.
+ *
+ * Shared by `spf doctor` (checks whichever key the configured model's
+ * provider prefix implies) and the `spf init` interview (asks for the key up
+ * front, keyed off the provider the user picked) — one table, so the two
+ * can never drift apart on what a provider needs.
+ */
+export const PROVIDER_ENV_KEYS = {
+    anthropic: ["ANTHROPIC_API_KEY"],
+    openai: ["OPENAI_API_KEY"],
+    google: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+    openrouter: ["OPENROUTER_API_KEY"],
+    fireworks: ["FIREWORKS_API_KEY"],
+    groq: ["GROQ_API_KEY"],
+    mistral: ["MISTRAL_API_KEY"],
+    xai: ["XAI_API_KEY"],
+    deepseek: ["DEEPSEEK_API_KEY"],
+    together: ["TOGETHER_API_KEY"],
+    cerebras: ["CEREBRAS_API_KEY"],
+};

package/dist/core/quality.d.ts

@@ -53,6 +53,15 @@ export declare function runSuite(run: RunLike, suiteName: string): QualityResult
 export declare function runTests(run: RunLike): QualityResult;
 /** Every configured check, across every configured suite's union — the `all` suite. */
 export declare function runQuality(run: RunLike): QualityResult;
+/**
+ * Log a deterministic block's verdict — the same shape every chain uses.
+ *
+ * Every quality/test phase in every chain reported this same summary by
+ * hand; one copy here instead of one per chain.
+ */
+export declare function record(ph: {
+    log: (payload: Record<string, unknown>) => void;
+}, result: QualityResult): void;
 /**
  * Wrap a deterministic result so an agent can be handed it directly.
  *

package/dist/core/quality.js

@@ -170,6 +170,16 @@ export function runTests(run) {
 export function runQuality(run) {
     return runSuite(run, "all");
 }
+/**
+ * Log a deterministic block's verdict — the same shape every chain uses.
+ *
+ * Every quality/test phase in every chain reported this same summary by
+ * hand; one copy here instead of one per chain.
+ */
+export function record(ph, result) {
+    const passed = result.checks.filter((c) => c.passed).length;
+    ph.log({ passed: result.passed, checks: `${passed}/${result.checks.length}`, artifacts: result.artifacts.join(", ") });
+}
 /**
  * Wrap a deterministic result so an agent can be handed it directly.
  *

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 { Notifier } from "./notify/notifier.ts";
 interface AgentMapEntry {
     session_id: string;
     model: string;
@@ -32,12 +33,18 @@ export interface RunInit {
     sfDir: string | null;
     /** Absolute. Resolved once, upstream, by paths.resolveDataPaths(). */
     dataDir: string;
+    /** The CLI chain name, for a notification's title — see session.ts. */
+    chainName?: string;
+    /** `null`/omitted when notifications are off (the default) or no channel resolved. */
+    notifier?: Notifier | null;
 }
 export declare class Run {
     cfg: SFConfig;
     adw_id: string;
     tracer: Tracer;
     console: Console;
+    /** `null` when notifications are off — `run.notify?.send(...)` at any future call site. */
+    notify: Notifier | null;
     engineer: string;
     phases: Phase[];
     tokens: number;

package/dist/core/runner.js

@@ -48,6 +48,8 @@ export class Run {
     adw_id;
     tracer;
     console;
+    /** `null` when notifications are off — `run.notify?.send(...)` at any future call site. */
+    notify;
     engineer;
     phases = [];
     tokens = 0;
@@ -68,7 +70,8 @@ export class Run {
         this.cfg = init.cfg;
         this.adw_id = init.adwId;
         this.tracer = init.tracer;
-        this.console = new Console(init.tracer, init.adwId);
+        this.notify = init.notifier ?? null;
+        this.console = new Console(init.tracer, init.adwId, this.notify, init.chainName || "adw");
         this.engineer = init.engineer;
         this.seq = init.tracer.maxPhaseSeq(init.adwId);
         this.repo_root = init.repoRoot;

package/dist/core/session.d.ts

@@ -12,5 +12,10 @@ import type { SFConfig } from "./data_types.ts";
  * process happened to start; it is an explicit decision, threaded down from
  * the CLI/chain context. Defaults to `process.cwd()` only for direct callers
  * (tests, scratch scripts) that have no anchor of their own to pass.
+ *
+ * `chainName` is the CLI name (`"plan-build-test"`, not a module basename) —
+ * every chain is a composed step list now, not its own file, so there is no
+ * longer a `process.argv[1]` basename that means anything. Direct callers
+ * that have no chain of their own fall back to `"adw"`.
  */
-export declare function ensure(cfg: SFConfig, adwId?: string | null, cwd?: string): Run;
+export declare function ensure(cfg: SFConfig, adwId?: string | null, cwd?: string, chainName?: string): Run;

package/dist/core/session.js

@@ -10,6 +10,7 @@ import * as paths from "./paths.js";
 import { Run } from "./runner.js";
 import { Tracer } from "./tracer.js";
 import { engineerName, newId } from "./utils.js";
+import { resolveNotifier } from "./notify/notifier.js";
 /**
  * A killed run still closes its own trace.
  *
@@ -33,8 +34,13 @@ function finalizeWhenKilled(run) {
  * process happened to start; it is an explicit decision, threaded down from
  * the CLI/chain context. Defaults to `process.cwd()` only for direct callers
  * (tests, scratch scripts) that have no anchor of their own to pass.
+ *
+ * `chainName` is the CLI name (`"plan-build-test"`, not a module basename) —
+ * every chain is a composed step list now, not its own file, so there is no
+ * longer a `process.argv[1]` basename that means anything. Direct callers
+ * that have no chain of their own fall back to `"adw"`.
  */
-export function ensure(cfg, adwId, cwd) {
+export function ensure(cfg, adwId, cwd, chainName) {
     const id = adwId || newId(8);
     const anchor = paths.resolveAnchor(cwd);
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
@@ -47,10 +53,11 @@ export function ensure(cfg, adwId, cwd) {
         repoRoot: anchor.repo_root,
         sfDir: anchor.spf_dir,
         dataDir: dataPaths.data_dir,
+        chainName: chainName || "adw",
+        notifier: resolveNotifier(cfg),
     });
     const scriptPath = process.argv[1] || "adw";
-    const adwName = path.basename(scriptPath, path.extname(scriptPath));
-    tracer.sessionStart(id, run.engineer, adwName);
+    tracer.sessionStart(id, run.engineer, chainName || "adw");
     // This process is the run. Record it before any phase opens, so a run that
     // hangs in its first agent call is still killable by adw_id.
     tracer.processStart(id, "adw", "", process.pid ?? -1, [path.basename(scriptPath), ...process.argv.slice(2)].join(" "));

package/dist/core/tracer.js

@@ -12,7 +12,7 @@ import { newId, nowIso } from "./utils.js";
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS sessions (
   adw_id        TEXT PRIMARY KEY,
-  adw_name      TEXT,                -- ADW script(s) run, e.g. "adw_plan + adw_build_test"
+  adw_name      TEXT,                -- chain(s) run, e.g. "plan + build-test"
   request       TEXT,
   status        TEXT,
   engineer      TEXT,

package/dist/core/utils.d.ts

@@ -1,8 +1,10 @@
 /**
  * Small shared helpers. Anything bigger belongs in its own module.
  *
- * Bun loads .env files automatically for anything run with `bun run`/`bun`,
- * so there is no load_dotenv() call to make here — that parity is free.
+ * `.env` loading lives in cli/index.ts's `main()`, via Node's built-in
+ * `process.loadEnvFile()` — anchored to the resolved repo root, not
+ * `process.cwd()`. Not here: this module has no anchor of its own to load
+ * relative to.
  */
 import path from "node:path";
 /**
@@ -22,6 +24,8 @@ export declare function nowIso(): string;
 export declare function ensureDir(dirPath: string): string;
 /** CLI prompt arg: a file path resolves to its contents, else inline text. */
 export declare function resolvePrompt(arg: string): string;
+/** True when `bin` resolves on PATH (or exists, if given as an absolute/relative path). Shared by `spf doctor` and the `spf init` interview so both agree on what's installed. */
+export declare function binaryOnPath(bin: string): boolean;
 export declare function engineerName(): string;
 /**
  * Minimal `--flag value` / `--bare-flag` CLI parsing — the CLI only ever

package/dist/core/utils.js

@@ -1,8 +1,10 @@
 /**
  * Small shared helpers. Anything bigger belongs in its own module.
  *
- * Bun loads .env files automatically for anything run with `bun run`/`bun`,
- * so there is no load_dotenv() call to make here — that parity is free.
+ * `.env` loading lives in cli/index.ts's `main()`, via Node's built-in
+ * `process.loadEnvFile()` — anchored to the resolved repo root, not
+ * `process.cwd()`. Not here: this module has no anchor of its own to load
+ * relative to.
  */
 import { randomBytes } from "node:crypto";
 import { spawnSync } from "node:child_process";
@@ -50,6 +52,13 @@ export function resolvePrompt(arg) {
     }
     return arg;
 }
+/** True when `bin` resolves on PATH (or exists, if given as an absolute/relative path). Shared by `spf doctor` and the `spf init` interview so both agree on what's installed. */
+export function binaryOnPath(bin) {
+    if (path.isAbsolute(bin) || bin.includes("/"))
+        return existsSync(bin);
+    const result = spawnSync(process.platform === "win32" ? "where" : "which", [bin], { encoding: "utf-8" });
+    return result.status === 0;
+}
 export function engineerName() {
     const name = (process.env.ENGINEER_NAME || "").trim();
     if (name)

package/dist/core/watch.d.ts

@@ -1,5 +1,6 @@
 import type { GitHandle } from "./git_helper.ts";
 import type { CodeHostProvider, Issue, IssueProvider } from "./issues/provider.ts";
+import type { NotifyEvent } from "./notify/channel.ts";
 export interface ChainRunResult {
     accepted: boolean;
     adwId: string;
@@ -36,6 +37,15 @@ export interface WatchDeps {
         adwId: string;
     }) => Promise<ChainRunResult>;
     log: (message: string) => void;
+    /**
+     * Structured push, alongside `log`'s plain string — a required field, like
+     * `log`, so a test must consciously supply one (a no-op fake is fine).
+     * Fired only at meaningful state transitions (claim, PR, done, blocked,
+     * error) — NOT at routine self-healing (an orphan resume/retry, a lost
+     * claim race, a cleanup warning), which recovers on its own and would
+     * just be noise in a channel.
+     */
+    notify: (event: NotifyEvent) => void;
 }
 export interface WatchRunState {
     inflight: Set<string>;