@gr8ful/spf 0.2.1 → 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/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.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.
  *
@@ -52,6 +53,8 @@ export function ensure(cfg, adwId, cwd, chainName) {
         repoRoot: anchor.repo_root,
         sfDir: anchor.spf_dir,
         dataDir: dataPaths.data_dir,
+        chainName: chainName || "adw",
+        notifier: resolveNotifier(cfg),
     });
     const scriptPath = process.argv[1] || "adw";
     tracer.sessionStart(id, run.engineer, chainName || "adw");

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>;

package/dist/core/watch.js

@@ -92,6 +92,13 @@ export async function reconcileOrphans(deps, state) {
         }
         else {
             deps.log(`watch: ${issue.id} orphaned past ${MAX_ORPHAN_ATTEMPTS} attempts — blocked`);
+            deps.notify({
+                kind: "issue_blocked",
+                level: "error",
+                title: `issue ${issue.id} blocked`,
+                detail: `Gave up after ${MAX_ORPHAN_ATTEMPTS} orphaned attempts.`,
+                fields: [["issue", issue.id], ["title", issue.title]],
+            });
             if (!deps.dryRun) {
                 await deps.provider.transition(issue, "blocked", `Gave up after ${MAX_ORPHAN_ATTEMPTS} orphaned attempts.`);
                 cleanupWorktree(deps, marker);
@@ -109,6 +116,13 @@ export async function finishReviews(deps) {
         const status = await deps.codeHost.prStatus({ number: marker.pr, branch: marker.branch ?? "", url: "" });
         if (status.merged) {
             deps.log(`watch: ${issue.id}'s PR #${marker.pr} merged — done`);
+            deps.notify({
+                kind: "issue_done",
+                level: "info",
+                title: `issue ${issue.id} done`,
+                detail: `PR #${marker.pr} merged.`,
+                fields: [["issue", issue.id], ["title", issue.title], ["pr", `#${marker.pr}`]],
+            });
             if (!deps.dryRun) {
                 await deps.provider.transition(issue, "done");
                 cleanupWorktree(deps, marker);
@@ -116,6 +130,13 @@ export async function finishReviews(deps) {
         }
         else if (status.state === "closed") {
             deps.log(`watch: ${issue.id}'s PR #${marker.pr} closed without merging — blocked`);
+            deps.notify({
+                kind: "issue_blocked",
+                level: "error",
+                title: `issue ${issue.id} blocked`,
+                detail: `PR #${marker.pr} was closed without merging.`,
+                fields: [["issue", issue.id], ["title", issue.title], ["pr", `#${marker.pr}`]],
+            });
             if (!deps.dryRun) {
                 await deps.provider.transition(issue, "blocked", `PR #${marker.pr} was closed without merging.`);
                 cleanupWorktree(deps, marker);
@@ -147,13 +168,28 @@ async function runIssue(deps, issue) {
         const result = await deps.runChain({ prompt, cwd: worktreePath, adwId });
         if (!result.accepted) {
             deps.log(`watch: ${issue.id}: chain "${deps.chain}" did not succeed — blocked`);
-            await deps.provider.transition(issue, "blocked", result.detail || `Chain "${deps.chain}" (adw_id ${adwId}) did not complete successfully. Run \`spf phases ${adwId}\` for detail.`);
+            const detail = result.detail || `Chain "${deps.chain}" (adw_id ${adwId}) did not complete successfully. Run \`spf phases ${adwId}\` for detail.`;
+            deps.notify({
+                kind: "issue_blocked",
+                level: "error",
+                title: `issue ${issue.id} blocked`,
+                detail,
+                fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain], ["adw_id", adwId]],
+            });
+            await deps.provider.transition(issue, "blocked", detail);
             cleanupWorktree(deps, { worktree: worktreePath, branch });
             return;
         }
         const wtGit = deps.worktreeGit(worktreePath);
         if (wtGit.diffFiles(`origin/${deps.baseBranch}`).length === 0) {
             deps.log(`watch: ${issue.id}: chain succeeded but committed nothing — blocked`);
+            deps.notify({
+                kind: "issue_blocked",
+                level: "error",
+                title: `issue ${issue.id} blocked`,
+                detail: `Chain "${deps.chain}" (adw_id ${adwId}) completed but left no committed changes.`,
+                fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain], ["adw_id", adwId]],
+            });
             await deps.provider.transition(issue, "blocked", `Chain "${deps.chain}" (adw_id ${adwId}) completed but left no committed changes.`);
             cleanupWorktree(deps, { worktree: worktreePath, branch });
             return;
@@ -173,10 +209,24 @@ async function runIssue(deps, issue) {
         await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, pr: pr.number, attempt: 0 });
         await deps.provider.transition(issue, "review");
         deps.log(`watch: ${issue.id}: opened PR #${pr.number} — review`);
+        deps.notify({
+            kind: "pr_opened",
+            level: "info",
+            title: `PR #${pr.number} opened`,
+            fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain]],
+            url: pr.url || undefined,
+        });
     }
     catch (error) {
         const message = error.message;
         deps.log(`watch: ${issue.id}: error: ${message}`);
+        deps.notify({
+            kind: "watch_error",
+            level: "error",
+            title: `issue ${issue.id} errored`,
+            detail: message,
+            fields: [["issue", issue.id], ["title", issue.title]],
+        });
         await deps.provider.transition(issue, "blocked", `spf watch error: ${message}`).catch(() => undefined);
         cleanupWorktree(deps, { worktree: worktreePath, branch });
     }
@@ -201,13 +251,26 @@ export async function claimNewWork(deps, state) {
             continue;
         }
         deps.log(`watch: claimed ${issue.id}: ${issue.title}`);
+        deps.notify({
+            kind: "issue_claimed",
+            level: "info",
+            title: `issue ${issue.id} claimed`,
+            fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain]],
+        });
         state.inflight.add(issue.id);
         runIssue(deps, issue).finally(() => state.inflight.delete(issue.id));
     }
 }
+function tickErrorHandler(deps, stage) {
+    return (error) => {
+        const message = error.message;
+        deps.log(`watch: ${stage} error: ${message}`);
+        deps.notify({ kind: "watch_error", level: "error", title: `watch: ${stage} error`, detail: message, fields: [] });
+    };
+}
 /** One poll tick: reconcile, finish, claim — each independently caught, so one phase's error never blocks the rest. */
 export async function tick(deps, state) {
-    await reconcileOrphans(deps, state).catch((error) => deps.log(`watch: reconcileOrphans error: ${error.message}`));
-    await finishReviews(deps).catch((error) => deps.log(`watch: finishReviews error: ${error.message}`));
-    await claimNewWork(deps, state).catch((error) => deps.log(`watch: claimNewWork error: ${error.message}`));
+    await reconcileOrphans(deps, state).catch(tickErrorHandler(deps, "reconcileOrphans"));
+    await finishReviews(deps).catch(tickErrorHandler(deps, "finishReviews"));
+    await claimNewWork(deps, state).catch(tickErrorHandler(deps, "claimNewWork"));
 }

package/dist/test/data_types.test.js

@@ -9,9 +9,13 @@
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import * as v from "valibot";
 import { toJsonSchema } from "@valibot/to-json-schema";
-import { AgentConfigSchema, BuildOutput, ChangesOutput, DocumentOutput, GenericOutput, PhaseParamsSchema, PlanOutput, ReviewOutput, ScoutOutput, VerifyOutput, makePhaseParams, } from "../core/data_types.js";
+import { AgentConfigSchema, BuildOutput, ChangesOutput, DocumentOutput, GenericOutput, NotificationsConfigSchema, PhaseParamsSchema, PlanOutput, ReviewOutput, ScoutOutput, VerifyOutput, makePhaseParams, } from "../core/data_types.js";
+import { loadConfig } from "../core/agents.js";
 test("writes: three-state semantics — absent, null, and [] all mean something different", () => {
     const base = { name: "builder", prompt_engineering: { system: "s.md", user: "u.md" } };
     const unrestricted = v.parse(AgentConfigSchema, base);
@@ -47,3 +51,32 @@ test("every envelope type still converts to JSON Schema (the sf_report tool wiri
 test("PhaseParamsSchema itself (the one schema WITH a rawTransform) correctly refuses JSON Schema conversion", () => {
     assert.throws(() => toJsonSchema(PhaseParamsSchema), /raw_transform/);
 });
+test("NotificationsConfigSchema defaults to off, no channels", () => {
+    const parsed = v.parse(NotificationsConfigSchema, {});
+    assert.equal(parsed.events, "off");
+    assert.equal(parsed.timeout_ms, 5_000);
+    assert.deepEqual(parsed.channels, []);
+});
+test("a channel's own `events` overrides the top-level scope; unset inherits it", () => {
+    const parsed = v.parse(NotificationsConfigSchema, {
+        events: "errors",
+        channels: [{ kind: "slack" }, { kind: "teams", events: "all" }],
+    });
+    assert.equal(parsed.channels[0].events, undefined, "unset per-channel scope stays undefined, not defaulted to the top-level value — the caller inherits at read time");
+    assert.equal(parsed.channels[1].events, "all");
+});
+test("notifications survives loadConfig's merge — key-by-key like observability/quality, channels replaced wholesale on override", () => {
+    const dir = mkdtempSync(join(tmpdir(), "spf-notify-merge-test-"));
+    try {
+        const base = join(dir, "base.yaml");
+        const override = join(dir, "override.yaml");
+        writeFileSync(base, "notifications:\n  events: off\n  channels:\n    - {kind: webhook, webhook_url_env: BASE_HOOK}\n");
+        writeFileSync(override, "notifications:\n  events: all\n  channels:\n    - {kind: slack, webhook_url_env: SLACK_WEBHOOK_URL}\n");
+        const cfg = loadConfig([base, override]);
+        assert.equal(cfg.notifications.events, "all", "events: key-by-key, override wins");
+        assert.deepEqual(cfg.notifications.channels.map((c) => c.kind), ["slack"], "channels: a whole-array replace, not an append — same semantics as quality.checks");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});