@gr8ful/spf 0.1.7 → 0.3.0

package/dist/cli/interview.js

@@ -0,0 +1,417 @@
+/**
+ * The question flow behind `spf init`'s interactive interview. No filesystem
+ * writes happen here — `commands/init.ts` owns those, so this module stays
+ * unit-testable against a scripted `Asker` (see `src/test/interview.test.ts`)
+ * without touching disk beyond the read-only `DetectedContext` gather.
+ *
+ * Every section below mirrors an existing, already-shipped code path rather
+ * than inventing new vocabulary:
+ *   - coding agent          -> src/core/agent_cc.ts / agent_flue.ts, src/core/providers.ts
+ *   - quality checks        -> src/core/data_types.ts's QualityCheckSpecSchema
+ *   - watch ticket loop     -> src/cli/commands/watch.ts's resolveIssueProvider/resolveCodeHostProvider
+ *   - the pinned-roster fix -> assets/templates/ts-cc.spf.config.yaml, done by hand today
+ */
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { binaryOnPath } from "../core/utils.js";
+import { PROVIDER_ENV_KEYS } from "../core/providers.js";
+import { resolveModel } from "../core/agent_flue.js";
+import { ThinkingLevelSchema } from "../core/data_types.js";
+import { loadConfig } from "../core/agents.js";
+import { BUILTIN_CONFIG_PATH } from "../core/paths.js";
+import { DEFAULT_NOTIFY_ENV_KEY } from "../core/notify/notifier.js";
+import { CHAINS } from "../chains/index.js";
+function gitConfigValue(repoRoot, key) {
+    const result = spawnSync("git", ["config", key], { cwd: repoRoot, encoding: "utf-8" });
+    const value = result.status === 0 ? result.stdout.trim() : "";
+    return value || undefined;
+}
+/** Parses the common GitHub/Bitbucket remote URL shapes (https and ssh) into "owner/name". Best-effort — an unparseable or missing remote just means no default to offer. */
+function parseRemoteSlug(url) {
+    if (!url)
+        return undefined;
+    const match = /(?:[/:])([^/:]+\/[^/]+?)(?:\.git)?$/.exec(url.trim());
+    return match ? match[1] : undefined;
+}
+function readScripts(repoRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(repoRoot, "package.json"), "utf-8"));
+        return pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Best-effort — a corrupt/missing built-in config falls back to the three names the auto-override already knows about, rather than failing the whole interview. */
+function readRosterNames() {
+    try {
+        return loadConfig([BUILTIN_CONFIG_PATH]).agents.map((a) => a.name);
+    }
+    catch {
+        return ["planner", "builder", "scout", "reviewer", "documenter"];
+    }
+}
+export function gatherContext(repoRoot, existingEnv = new Map()) {
+    const remote = spawnSync("git", ["config", "--get", "remote.origin.url"], { cwd: repoRoot, encoding: "utf-8" });
+    const branch = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot, encoding: "utf-8" });
+    return {
+        repoSlug: parseRemoteSlug(remote.status === 0 ? remote.stdout.trim() : undefined),
+        currentBranch: branch.status === 0 && branch.stdout.trim() !== "HEAD" ? branch.stdout.trim() : "main",
+        gitEmail: gitConfigValue(repoRoot, "user.email"),
+        gitName: gitConfigValue(repoRoot, "user.name"),
+        scripts: readScripts(repoRoot),
+        claudeOnPath: binaryOnPath("claude"),
+        existingEnv,
+        rosterNames: readRosterNames(),
+    };
+}
+const QUALITY_TIMEOUTS = { typecheck: 60, lint: 60, build: 120, test: 180 };
+function splitArgv(command) {
+    return command.trim().split(/\s+/).filter(Boolean);
+}
+/**
+ * Runs the interview and returns the config/env to write, or `null` if the
+ * user declines the final confirmation. Throws `InterviewAborted` (from
+ * `./ask.ts`) on Ctrl-C/EOF — the caller decides the exit code for that.
+ */
+export async function runInterview(asker, ctx) {
+    const defaults = {};
+    const agentOverrides = [];
+    const env = {};
+    const envExampleKeys = [];
+    const notes = [];
+    // ── 1. coding agent ────────────────────────────────────────────────────────
+    asker.heading("Coding agent");
+    const codingAgent = await asker.select("Which backend runs each agent?", [
+        { value: "claude_code", label: "claude_code — shells out to the `claude` CLI you already use", hint: "cc" },
+        { value: "flue", label: "flue — in-process, provider/model-id (openai, anthropic, openrouter, ...)" },
+    ], "claude_code");
+    defaults.coding_agent = codingAgent;
+    if (codingAgent === "claude_code") {
+        if (!ctx.claudeOnPath) {
+            asker.note("warning: `claude` was not found on PATH — install it (or set a launch command below) before running spf.");
+        }
+        const launchCommand = await asker.text('Launch command for the `claude` CLI — e.g. "ollama launch claude" to route through a wrapper (SPF_CLAUDE_CMD)', { default: "claude" });
+        if (launchCommand !== "claude")
+            env["SPF_CLAUDE_CMD"] = launchCommand;
+        const model = await asker.select("Model (Claude Code's own vocabulary — not provider/model-id)", [
+            { value: "sonnet", label: "sonnet" },
+            { value: "opus", label: "opus" },
+            { value: "haiku", label: "haiku" },
+            { value: "custom", label: "custom — type an exact model name" },
+        ], "sonnet");
+        defaults.model = model === "custom" ? await asker.text("Exact model name") : model;
+        const auth = await asker.select("Authentication", [
+            { value: "login", label: "already logged in via `claude login`", hint: "writes nothing" },
+            { value: "key", label: "ANTHROPIC_API_KEY" },
+            { value: "endpoint", label: "custom endpoint (Ollama / Ollama Cloud / a proxy)" },
+        ], "login");
+        if (auth === "key") {
+            const current = ctx.existingEnv.get("ANTHROPIC_API_KEY");
+            const key = await asker.secret("ANTHROPIC_API_KEY", { current });
+            if (key)
+                env["ANTHROPIC_API_KEY"] = key;
+            envExampleKeys.push("ANTHROPIC_API_KEY");
+        }
+        else if (auth === "endpoint") {
+            const baseUrl = await asker.text("ANTHROPIC_BASE_URL", { default: "http://localhost:11434" });
+            env["ANTHROPIC_BASE_URL"] = baseUrl;
+            const token = await asker.secret("ANTHROPIC_AUTH_TOKEN", { current: ctx.existingEnv.get("ANTHROPIC_AUTH_TOKEN") });
+            env["ANTHROPIC_AUTH_TOKEN"] = token || "ollama";
+            envExampleKeys.push("ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN");
+            asker.note("spf doctor does not check these two — confirm the endpoint is reachable yourself.");
+        }
+        // The packaged roster pins planner/reviewer/documenter to their own
+        // Flue-style provider/model-id strings, which always win over
+        // defaults.model (agents.ts's back-fill only applies when an agent
+        // doesn't already set its own `model`). Left alone, switching the
+        // backend to claude_code sends those three straight to the `claude`
+        // CLI's `--model` flag as e.g. "fireworks/accounts/.../kimi-k3", which
+        // it cannot resolve. Override all three to the same model chosen above
+        // — exactly what assets/templates/ts-cc.spf.config.yaml does by hand.
+        for (const name of ["planner", "reviewer", "documenter"]) {
+            agentOverrides.push({ name, model: defaults.model });
+        }
+        notes.push("planner/reviewer/documenter pin their own model in the packaged roster and always win over defaults.model — overriding all three to match, since claude_code can't resolve their packaged Flue-style ids.");
+    }
+    else {
+        const provider = await asker.select("Provider", Object.keys(PROVIDER_ENV_KEYS).map((p) => ({ value: p, label: p })), "anthropic");
+        const modelId = await asker.text(`Model id (after "${provider}/")`, {
+            default: provider === "anthropic" ? "claude-sonnet-4-6" : "",
+            validate: (val) => (val.trim() ? null : "required"),
+        });
+        const model = `${provider}/${modelId}`;
+        try {
+            resolveModel(model);
+        }
+        catch (error) {
+            asker.note(`warning: ${error.message}`);
+        }
+        defaults.model = model;
+        const envKey = PROVIDER_ENV_KEYS[provider][0];
+        const key = await asker.secret(envKey, { current: ctx.existingEnv.get(envKey) });
+        if (key)
+            env[envKey] = key;
+        envExampleKeys.push(envKey);
+    }
+    // Declined (the default): today's behavior exactly — on claude_code, the
+    // three-agent auto-pin above stands unchanged; on flue, no agents: block
+    // at all. Accepted: ask every roster agent's model, defaulting to the one
+    // chosen above, and patch/append its override — `mergeAgentLists`
+    // (agents.ts:63-71) shallow-patches by name, so re-setting `model` on an
+    // already-pinned entry (claude_code's planner/reviewer/documenter) is
+    // exactly the right shape, no `prompt_engineering` needed (interview.ts's
+    // review-section comment explains why that's fine).
+    const customizeModels = await asker.confirm("Customize models per agent?", false);
+    if (customizeModels) {
+        asker.heading("Per-agent models");
+        for (const name of ctx.rosterNames) {
+            const answer = await asker.text(`  ${name}`, { default: String(defaults.model) });
+            if (codingAgent === "flue") {
+                try {
+                    resolveModel(answer);
+                }
+                catch (error) {
+                    asker.note(`warning: ${error.message}`);
+                }
+            }
+            const existing = agentOverrides.find((a) => a.name === name);
+            if (existing)
+                existing.model = answer;
+            else
+                agentOverrides.push({ name, model: answer });
+        }
+    }
+    // ── 2. quality checks ──────────────────────────────────────────────────────
+    asker.heading("Quality checks");
+    asker.note("a chain that gates on a suite (e.g. plan-build-test's `test`) fails loudly before anything runs if the suite is unconfigured.");
+    const checks = [];
+    const configuredNames = [];
+    for (const [checkName, operation, scriptGuess] of [
+        ["typecheck", "typecheck", "typecheck"],
+        ["lint", "lint", "lint"],
+        ["build", "build", "build"],
+        ["test", "build", "test"],
+    ]) {
+        const detectedScript = ctx.scripts[scriptGuess] ? `npm run ${scriptGuess}` : "";
+        const wantIt = await asker.confirm(`Add a "${checkName}" check?`, Boolean(detectedScript));
+        if (!wantIt)
+            continue;
+        const command = await asker.text(`  ${checkName} command`, { default: detectedScript || `npm run ${scriptGuess}` });
+        checks.push({ name: checkName, operation, argv: splitArgv(command), timeout_seconds: QUALITY_TIMEOUTS[checkName] });
+        configuredNames.push(checkName);
+    }
+    if (checks.length > 0) {
+        const suites = { all: configuredNames };
+        if (configuredNames.includes("test"))
+            suites.test = ["test"];
+        defaults["__quality__"] = { checks, suites };
+    }
+    // ── 3. watch ticket loop ────────────────────────────────────────────────────
+    asker.heading("Watch ticket loop (spf watch)");
+    const enableWatch = await asker.confirm("Enable spf watch (poll a tracker, run a chain per issue, open a PR)?", false);
+    let watch = null;
+    if (enableWatch) {
+        const issueProvider = await asker.select("Issue tracker", [
+            { value: "github", label: "GitHub Issues" },
+            { value: "jira", label: "Jira" },
+        ], "github");
+        const codeHost = await asker.select("Code host (where PRs open)", [
+            { value: "github", label: "GitHub" },
+            { value: "bitbucket", label: "Bitbucket" },
+        ], "github");
+        const repoHint = codeHost === "bitbucket" ? "workspace/repo_slug" : "owner/name";
+        const repo = await asker.text(`Repo (${repoHint})`, {
+            default: codeHost === "github" ? ctx.repoSlug ?? "" : "",
+            validate: (val) => (val.includes("/") && val.split("/").filter(Boolean).length === 2 ? null : `must be "${repoHint}"`),
+        });
+        const labelPrefix = await asker.text("Label prefix", { default: "spf" });
+        const baseBranch = await asker.text("Base branch", { default: ctx.currentBranch });
+        const chainChoices = CHAINS.map((c) => ({ value: c.name, label: c.name, hint: c.describe }));
+        const chain = await asker.select("Chain to run per issue", chainChoices, "plan-build-test");
+        watch = { issue_provider: issueProvider, code_host: codeHost, repo, label_prefix: labelPrefix, chain, base_branch: baseBranch };
+        if (issueProvider === "jira") {
+            const baseUrl = await asker.text("Jira base URL", {
+                default: "https://your-domain.atlassian.net",
+                validate: (val) => (/^https:\/\/.+/.test(val) ? null : "must start with https://"),
+            });
+            const projectKey = await asker.text("Jira project key", { validate: (val) => (val.trim() ? null : "required") });
+            watch.jira = { base_url: baseUrl.replace(/\/+$/, ""), project_key: projectKey.toUpperCase() };
+        }
+        const needsGithub = issueProvider === "github" || codeHost === "github";
+        if (needsGithub) {
+            asker.note('classic PAT, "repo" scope (private) or "public_repo" (public-only) — never "project".');
+            const token = await asker.secret("GITHUB_TOKEN", { current: ctx.existingEnv.get("GITHUB_TOKEN") });
+            if (token)
+                env["GITHUB_TOKEN"] = token;
+            envExampleKeys.push("GITHUB_TOKEN");
+        }
+        if (issueProvider === "jira") {
+            const email = await asker.text("JIRA_EMAIL", { default: ctx.gitEmail ?? "" });
+            if (email)
+                env["JIRA_EMAIL"] = email;
+            const token = await asker.secret("JIRA_API_TOKEN", { current: ctx.existingEnv.get("JIRA_API_TOKEN") });
+            if (token)
+                env["JIRA_API_TOKEN"] = token;
+            envExampleKeys.push("JIRA_EMAIL", "JIRA_API_TOKEN");
+            asker.note("id.atlassian.com -> Security -> API tokens");
+        }
+        if (codeHost === "bitbucket") {
+            const email = await asker.text("BITBUCKET_EMAIL", { default: ctx.gitEmail ?? "" });
+            if (email)
+                env["BITBUCKET_EMAIL"] = email;
+            const token = await asker.secret("BITBUCKET_API_TOKEN", { current: ctx.existingEnv.get("BITBUCKET_API_TOKEN") });
+            if (token)
+                env["BITBUCKET_API_TOKEN"] = token;
+            envExampleKeys.push("BITBUCKET_EMAIL", "BITBUCKET_API_TOKEN");
+            asker.note("Bitbucket app passwords are being removed — this needs an Atlassian API token instead.");
+        }
+    }
+    // ── 4. notifications ─────────────────────────────────────────────────────────
+    asker.heading("Notifications");
+    const enableNotify = await asker.confirm("Send notifications to Slack, Teams, or a webhook?", false);
+    let notifications = null;
+    if (enableNotify) {
+        const events = await asker.select("Notify on", [
+            { value: "errors", label: "errors — failed runs, blocked issues, watch errors" },
+            { value: "all", label: "all — every milestone (claimed, PR opened, done, ...) plus errors" },
+        ], "errors");
+        const channels = [];
+        for (;;) {
+            const kind = await asker.select("Channel", [
+                { value: "slack", label: "Slack — Incoming Webhook" },
+                { value: "teams", label: "Microsoft Teams — Workflows webhook" },
+                { value: "webhook", label: "generic webhook — POSTs the raw event as JSON" },
+            ], "slack");
+            const envKey = DEFAULT_NOTIFY_ENV_KEY[kind];
+            if (kind === "slack") {
+                asker.note("Slack app -> Incoming Webhooks -> Add New Webhook to Workspace.");
+                asker.note("Docs: https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks");
+            }
+            else if (kind === "teams") {
+                asker.note("In the target channel, add a Workflows webhook template (search for one like \"Post to a channel when a webhook request is received\"). The old Office 365 connector webhooks are retired — this is the only path now.");
+                asker.note("Docs: https://support.microsoft.com/en-us/office/post-a-workflow-when-a-webhook-request-is-received-in-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498");
+            }
+            else {
+                asker.note("Any endpoint that accepts a JSON POST — Discord, n8n, Zapier, your own.");
+            }
+            const url = await asker.secret(envKey, { current: ctx.existingEnv.get(envKey) });
+            if (url)
+                env[envKey] = url;
+            envExampleKeys.push(envKey);
+            channels.push({ kind, webhook_url_env: envKey });
+            const another = await asker.confirm("Add another channel?", false);
+            if (!another)
+                break;
+        }
+        notifications = { events, channels };
+    }
+    // ── 5. advanced (gated) ─────────────────────────────────────────────────────
+    const wantAdvanced = await asker.confirm("\nConfigure advanced settings (thinking level, tools, protected files, data dir, poll intervals, ...)?", false);
+    if (wantAdvanced) {
+        asker.heading("Advanced");
+        const thinkingChoices = ThinkingLevelSchema.options.map((o) => ({ value: o, label: o }));
+        const thinking = await asker.select("defaults.thinking", thinkingChoices, "medium");
+        if (thinking !== "medium")
+            defaults.thinking = thinking;
+        const dataDir = await asker.text("defaults.data_dir", { default: ".spf/data" });
+        if (dataDir !== ".spf/data")
+            defaults.data_dir = dataDir;
+        const protectedFiles = await asker.text("defaults.protected_files (comma-separated)", { default: ".spf/, spf.config.yaml" });
+        const protectedList = protectedFiles.split(",").map((s) => s.trim()).filter(Boolean);
+        if (protectedList.join(",") !== ".spf/,spf.config.yaml")
+            defaults.protected_files = protectedList;
+        const dbPath = await asker.text("observability.db", { default: ".spf/data/spf.db" });
+        const pollMs = await asker.text("observability.poll_ms", { default: "500" });
+        if (dbPath !== ".spf/data/spf.db" || pollMs !== "500") {
+            defaults["__observability__"] = { ...(dbPath !== ".spf/data/spf.db" ? { db: dbPath } : {}), ...(pollMs !== "500" ? { poll_ms: Number(pollMs) } : {}) };
+        }
+        if (watch) {
+            const watchPollMs = await asker.text("watch.poll_ms", { default: "60000" });
+            if (watchPollMs !== "60000")
+                watch.poll_ms = Number(watchPollMs);
+            const concurrency = await asker.text("watch.concurrency", { default: "2" });
+            if (concurrency !== "2")
+                watch.concurrency = Number(concurrency);
+        }
+        const engineerName = await asker.text("ENGINEER_NAME (falls back to `git config user.name`)", { default: ctx.gitName ?? "" });
+        if (engineerName && engineerName !== ctx.gitName)
+            env["ENGINEER_NAME"] = engineerName;
+        if (watch?.issue_provider === "jira") {
+            const debug = await asker.confirm("Enable SPF_JIRA_DEBUG (request/response logging)?", false);
+            if (debug)
+                env["SPF_JIRA_DEBUG"] = "1";
+        }
+        if (notifications) {
+            const timeoutMs = await asker.text("notifications.timeout_ms", { default: "5000" });
+            if (timeoutMs !== "5000")
+                notifications.timeout_ms = Number(timeoutMs);
+        }
+    }
+    // ── 6. review + confirm ─────────────────────────────────────────────────────
+    const observability = defaults["__observability__"];
+    delete defaults["__observability__"];
+    const quality = defaults["__quality__"];
+    delete defaults["__quality__"];
+    const config = { defaults };
+    if (agentOverrides.length > 0)
+        config.agents = agentOverrides;
+    if (quality)
+        config.quality = quality;
+    if (watch)
+        config.watch = watch;
+    if (observability)
+        config.observability = observability;
+    if (notifications)
+        config.notifications = notifications;
+    // No schema validation here on purpose: `config.agents` overrides are
+    // intentionally PARTIAL (name + model only, no prompt_engineering) — valid
+    // only once merged by name into the packaged roster (agents.ts's
+    // mergeAgentLists), same as any hand-written override file. Validating
+    // this raw document against the full SFConfigSchema would flag every
+    // claude_code interview as broken. `commands/init.ts` runs the real
+    // merge-then-validate pipeline (agents.loadConfig + agents.validate,
+    // the same one `spf doctor` uses) after writing, and reports there.
+    asker.heading("Review");
+    console.log(renderPreview(config));
+    if (notes.length > 0) {
+        for (const n of notes)
+            asker.note(n);
+    }
+    if (Object.keys(env).length > 0) {
+        console.log("");
+        console.log(".env keys to write: " + Object.keys(env).join(", "));
+    }
+    const proceed = await asker.confirm("\nWrite .spf/spf.config.yaml and .env?", true);
+    if (!proceed)
+        return null;
+    return { config, env, envExampleKeys };
+}
+/** An array is worth recursing into only if it holds further objects (e.g. `agents:`, `quality.checks`) — an array of primitives (e.g. `argv: ["npm","run","test"]`) reads better printed inline than one bare, contentless line per entry. */
+function isArrayOfObjects(value) {
+    return Array.isArray(value) && value.some((item) => item && typeof item === "object");
+}
+function renderPreview(config) {
+    const lines = [];
+    const walk = (obj, indent) => {
+        for (const [key, value] of Object.entries(obj)) {
+            if (isArrayOfObjects(value)) {
+                lines.push(`${indent}${key}:`);
+                for (const item of value) {
+                    lines.push(`${indent}  -`);
+                    walk(item, indent + "    ");
+                }
+            }
+            else if (value && typeof value === "object" && !Array.isArray(value)) {
+                lines.push(`${indent}${key}:`);
+                walk(value, indent + "  ");
+            }
+            else {
+                lines.push(`${indent}${key}: ${JSON.stringify(value)}`);
+            }
+        }
+    };
+    walk(config, "");
+    return lines.join("\n");
+}

package/dist/core/agents.js

@@ -57,13 +57,16 @@ function mergeAgentLists(base, override) {
     }
     return merged;
 }
-/** `defaults`/`observability`/`quality` merge key-by-key; `agents` merges by name. */
+/** `defaults`/`observability`/`quality`/`watch`/`notifications` merge key-by-key; `agents` merges by name. */
 function mergeRawConfig(base, override) {
     return {
         defaults: { ...(base.defaults || {}), ...(override.defaults || {}) },
         observability: { ...(base.observability || {}), ...(override.observability || {}) },
         quality: { ...(base.quality || {}), ...(override.quality || {}) },
         watch: { ...(base.watch || {}), ...(override.watch || {}) },
+        // channels is a whole-array replace on override, same as quality.checks —
+        // you don't want an override's channels appended to the built-in's.
+        notifications: { ...(base.notifications || {}), ...(override.notifications || {}) },
         agents: mergeAgentLists(base.agents || [], override.agents || []),
     };
 }

package/dist/core/console.d.ts

@@ -7,6 +7,10 @@
  * so a CI log reads exactly like a terminal.
  */
 import type { EnvelopeBase, EventRecord, GateReport, Phase } from "./data_types.ts";
+import type { NotifyEvent } from "./notify/channel.ts";
+interface Notifier {
+    send(event: NotifyEvent): void;
+}
 export declare function paint(style: string, text: string): string;
 interface Tracer {
     event(record: EventRecord): string;
@@ -15,11 +19,19 @@ interface Tracer {
 export declare class Console {
     private tracer;
     private adwId;
+    /** `null` when notifications are off — every call site below guards with `?.`. */
+    private notifier;
+    /** The CLI chain name (`"plan-build-test"`), for a notification's title — see session.ts. */
+    private chainName;
     private phaseId;
     private phaseName;
     private results;
     private finished;
-    constructor(tracer: Tracer, adwId: string);
+    constructor(tracer: Tracer, adwId: string, 
+    /** `null` when notifications are off — every call site below guards with `?.`. */
+    notifier?: Notifier | null, 
+    /** The CLI chain name (`"plan-build-test"`), for a notification's title — see session.ts. */
+    chainName?: string);
     private emit;
     sessionStarted(adwId: string, engineer: string): void;
     sessionFinished(ok: boolean, tokens: number, cost: number, dbPath: string): void;

package/dist/core/console.js

@@ -45,13 +45,21 @@ function panel(lines, title, borderColor) {
 export class Console {
     tracer;
     adwId;
+    notifier;
+    chainName;
     phaseId = ""; // current lane — log events attach to it
     phaseName = "";
     results = []; // phase statuses, for the summary
     finished = false; // the summary panel prints once
-    constructor(tracer, adwId) {
+    constructor(tracer, adwId, 
+    /** `null` when notifications are off — every call site below guards with `?.`. */
+    notifier = null, 
+    /** The CLI chain name (`"plan-build-test"`), for a notification's title — see session.ts. */
+    chainName = "adw") {
         this.tracer = tracer;
         this.adwId = adwId;
+        this.notifier = notifier;
+        this.chainName = chainName;
     }
     // ── the one helper: print AND trace, always together ────────────────────
     emit(line, level = "info") {
@@ -67,6 +75,15 @@ export class Console {
     // ── session ─────────────────────────────────────────────────────────────
     sessionStarted(adwId, engineer) {
         this.emit(`${paint("bold cyan", "adw_id:")} ${paint("bold", adwId)}   ${paint("dim", "engineer")} ${engineer}`);
+        this.notifier?.send({
+            kind: "run_started",
+            level: "info",
+            title: `run started — ${this.chainName}`,
+            fields: [
+                ["adw_id", adwId],
+                ["engineer", engineer],
+            ],
+        });
     }
     sessionFinished(ok, tokens, cost, dbPath) {
         if (this.finished)
@@ -93,6 +110,17 @@ export class Console {
             name: this.phaseName || "console",
             payload: { message: plain, level: ok ? "info" : "error" },
         }));
+        this.notifier?.send({
+            kind: ok ? "run_finished" : "run_failed",
+            level: ok ? "info" : "error",
+            title: `run ${ok ? "finished" : "failed"} — ${this.chainName}`,
+            fields: [
+                ["adw_id", this.adwId],
+                ["phases", `${passed}/${this.results.length}`],
+                ["tokens", tokens.toLocaleString()],
+                ["cost", `$${cost.toFixed(4)}`],
+            ],
+        });
     }
     // ── phases ──────────────────────────────────────────────────────────────
     phaseStarted(phase) {
@@ -113,6 +141,19 @@ export class Console {
         if (!ok && phase.error)
             line += `  ${paint("red", clip(phase.error))}`;
         this.emit(line, ok ? "info" : "error");
+        if (!ok) {
+            this.notifier?.send({
+                kind: "phase_failed",
+                level: "error",
+                title: `phase failed — ${phase.params.name}`,
+                detail: phase.error ?? undefined,
+                fields: [
+                    ["adw_id", this.adwId],
+                    ["chain", this.chainName],
+                    ["owner", phase.params.owner],
+                ],
+            });
+        }
         this.phaseId = "";
         this.phaseName = "";
     }
@@ -129,6 +170,15 @@ export class Console {
     }
     retry(name, attempt, limit, reason) {
         this.emit(`  ${paint("yellow", "⟳")} ${name} retry ${attempt}/${limit} ${paint("dim", `— same session · ${clip(reason)}`)}`, "warn");
+        // info-level: routine self-healing, same as watch's own untracked
+        // orphan retries — visible under `events: all`, silent under `errors`.
+        this.notifier?.send({
+            kind: "phase_retry",
+            level: "info",
+            title: `retry ${attempt}/${limit} — ${name}`,
+            detail: reason,
+            fields: [["adw_id", this.adwId]],
+        });
     }
     // ── verification ────────────────────────────────────────────────────────
     /** A gate reports WHAT it checked, not just whether it passed. */

package/dist/core/data_types.d.ts

@@ -401,6 +401,42 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
     }>;
 }, undefined>;
 export type WatchConfig = v.InferOutput<typeof WatchConfigSchema>;
+/**
+ * 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 declare const NotifyScopeSchema: v.PicklistSchema<["off", "errors", "all"], undefined>;
+export type NotifyScope = v.InferOutput<typeof NotifyScopeSchema>;
+export declare const NotifyChannelKindSchema: v.PicklistSchema<["slack", "teams", "webhook"], undefined>;
+export type NotifyChannelKind = v.InferOutput<typeof NotifyChannelKindSchema>;
+export declare const NotifyChannelSchema: v.ObjectSchema<{
+    readonly kind: v.PicklistSchema<["slack", "teams", "webhook"], undefined>;
+    readonly webhook_url_env: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, undefined>, undefined>;
+    readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
+}, undefined>;
+export type NotifyChannel = v.InferOutput<typeof NotifyChannelSchema>;
+export declare const NotificationsConfigSchema: v.ObjectSchema<{
+    readonly events: v.OptionalSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, "off">;
+    readonly timeout_ms: v.OptionalSchema<v.NumberSchema<undefined>, 5000>;
+    readonly channels: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        readonly kind: v.PicklistSchema<["slack", "teams", "webhook"], undefined>;
+        readonly webhook_url_env: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, undefined>, undefined>;
+        readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    }, undefined>, undefined>, () => never[]>;
+}, undefined>;
+export type NotificationsConfig = v.InferOutput<typeof NotificationsConfigSchema>;
 export declare const SFConfigSchema: v.ObjectSchema<{
     readonly defaults: v.OptionalSchema<v.ObjectSchema<{
         readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
@@ -494,6 +530,25 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             project_key: string;
         };
     }>;
+    readonly notifications: v.OptionalSchema<v.ObjectSchema<{
+        readonly events: v.OptionalSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, "off">;
+        readonly timeout_ms: v.OptionalSchema<v.NumberSchema<undefined>, 5000>;
+        readonly channels: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly kind: v.PicklistSchema<["slack", "teams", "webhook"], undefined>;
+            readonly webhook_url_env: v.OptionalSchema<v.StringSchema<undefined>, "">;
+            readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, undefined>, undefined>;
+            readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        }, undefined>, undefined>, () => never[]>;
+    }, undefined>, () => {
+        events: "all" | "errors" | "off";
+        timeout_ms: number;
+        channels: {
+            kind: "slack" | "teams" | "webhook";
+            webhook_url_env: string;
+            events?: "all" | "errors" | "off" | null | undefined;
+            name: string;
+        }[];
+    }>;
 }, undefined>;
 export type SFConfig = v.InferOutput<typeof SFConfigSchema>;
 /** One traced event, always logged against adw_id + phase. */