@gr8ful/spf 0.3.0 → 0.5.0

package/dist/cli/index.js

@@ -8,8 +8,10 @@ import path from "node:path";
 import * as agentCc from "../core/agent_cc.js";
 import * as agentFlue from "../core/agent_flue.js";
 import * as notify from "../core/notify/notifier.js";
+import * as otel from "../core/otel.js";
 import * as paths from "../core/paths.js";
-import { findChain } from "../chains/index.js";
+import { findChain, registerRepoChains, repoChainProblems } from "../chains/index.js";
+import { loadRepoChains } from "../chains/repo_chains.js";
 import { dispatchChain, usageFor } from "./commands/run.js";
 import { listCommand } from "./commands/list.js";
 import { initCommand } from "./commands/init.js";
@@ -28,8 +30,8 @@ const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
 
   spf list                                  the chain registry — names, phases, what each needs
   spf <chain> "<prompt>" [options]          run a chain (spf run <chain> ... works identically)
-  spf init [--force] [--yes] [--template <name>]  interview to seed .spf/spf.config.yaml + .env (--yes/--template skip the interview)
-  spf install-skill [--user] [--force]      install the Claude Code skill (repo-local by default)
+  spf init [--force] [--yes] [--template <name>] [--no-skills]  interview to seed .spf/spf.config.yaml + .env, and install the Claude Code skill unless --no-skills (--yes/--template skip the interview, not the skill install)
+  spf install-skill [--user] [--force]      (re)install the Claude Code skill by hand — spf init already does this
   spf migrate [--apply] [--force]           move an old stamped adws/ tree onto .spf/ (dry run by default)
   spf eject [--target <dir>] [--force]      copy the installed engine out for reference/hand-editing
   spf doctor [--json]                       check everything that fails silently otherwise
@@ -42,13 +44,33 @@ const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
   spf abort <adw_id>                        signal a run's process to stop
   spf version                               print the installed version
 
-Chain options: [--config <path>] [--adw-id <id>] [--cwd <dir>] [--agent <name>] [--base <ref>]
+Chain options: [--config <path>] [--adw-id <id>] [--cwd <dir>] [--agent <name>] [--base <ref>] [--issue <id>]
 Run \`spf list\` to see every chain and what it needs.`;
 /** A raw scan for `--cwd`, ahead of any command-specific argv parsing — every command that takes it means the same thing by it. */
 function findCwdFlag(argv) {
     const idx = argv.indexOf("--cwd");
     return idx !== -1 ? argv[idx + 1] : undefined;
 }
+/**
+ * The moment someone types a chain name that doesn't resolve is the highest-
+ * traffic place a broken `.spf/chains/*.yaml` file is ever discovered — and,
+ * before this, the one place its load problem was withheld (`spf list` and
+ * `spf doctor` report it; this "unknown chain"/"unknown command or chain"
+ * path printed only the full HELP text). A file named for exactly the chain
+ * someone typed is surfaced first, ahead of any other broken file, since
+ * that's the one they're actually looking for right now.
+ */
+function reportUnresolvedChain(typedName) {
+    const problems = repoChainProblems();
+    if (problems.length === 0)
+        return;
+    const matching = typedName ? problems.filter((p) => path.basename(p.file).startsWith(typedName)) : [];
+    const rest = problems.filter((p) => !matching.includes(p));
+    const ordered = [...matching, ...rest];
+    console.error(`${problems.length} repo chain file(s) failed to load — one of these may be what you meant:`);
+    for (const p of ordered)
+        console.error(`  ! ${p.file}: ${p.message}`);
+}
 export async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     // `process.loadEnvFile()` with no argument reads from `process.cwd()` —
@@ -58,13 +80,41 @@ export async function main() {
     // invoking shell's directory instead of the target repo's is exactly the
     // anchor-mismatch bug that principle exists to close. Resolve the same
     // way every command does, and load .env from the repo root it finds.
+    //
+    // Hoisted out of the try/catch below: resolveAnchor() cannot throw —
+    // findRepoRoot() (core/git_helper.ts) guards its own `git rev-parse
+    // --git-dir` probe with isRepoAt() and falls back to `cwd` itself when
+    // it's not a repo, AND guards the follow-up `--show-toplevel` call the
+    // same way (that one can fail even when isRepoAt() said yes — a bare repo
+    // or a `.git/` directory itself has no work tree), so it never throws
+    // either. findSfDir()'s walk is a plain existsSync/statSync loop with no
+    // failure path. The only thing in this block that CAN throw is
+    // loadEnvFile() (ENOENT when there's no .env), which is exactly what the
+    // catch below still guards.
+    const anchor = paths.resolveAnchor(findCwdFlag(rest));
     try {
-        const anchor = paths.resolveAnchor(findCwdFlag(rest));
         process.loadEnvFile(path.join(anchor.repo_root, ".env"));
     }
     catch {
         // no .env there — fine, nothing to load
     }
+    // Repo-local chains as DATA: a `.spf/chains/*.yaml` file names existing
+    // step factories, it never imports repo code — SPF's own dispatcher stays
+    // the one thing that ever executes. Registered here, before the command
+    // switch, so every dispatch path (`spf <chain>`, `spf run <chain>`, `spf
+    // list`, `spf doctor`, `spf watch`) sees the same merged registry without
+    // each of them re-scanning `.spf/chains/` on its own. This is also the
+    // ONCE in "`spf watch` registers chains from the main anchor once, at
+    // daemon start" — see the WATCH DIVERGENCE comment on `runChain` in
+    // `cli/commands/watch.ts` for what that means for a chain file edited on
+    // an issue branch mid-run. Zero filesystem cost when there's no `.spf/` at
+    // all (anchor.spf_dir is null for a repo that
+    // never ran `spf init`) — loadRepoChains() is only ever called once we
+    // know there's something to look at.
+    if (anchor.spf_dir) {
+        const { chains, problems } = loadRepoChains(anchor);
+        registerRepoChains(chains, problems);
+    }
     if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
         console.log(HELP);
         process.exitCode = 0;
@@ -81,6 +131,7 @@ export async function main() {
                 const chain = chainName ? findChain(chainName) : undefined;
                 if (!chain) {
                     console.error(`unknown chain: ${chainName ?? "(none given)"} — run \`spf list\` to see every chain`);
+                    reportUnresolvedChain(chainName);
                     process.exitCode = 1;
                     return;
                 }
@@ -103,7 +154,7 @@ export async function main() {
                 process.exitCode = ejectCommand(rest);
                 return;
             case "doctor":
-                process.exitCode = doctorCommand(rest);
+                process.exitCode = await doctorCommand(rest);
                 return;
             case "ui":
                 process.exitCode = await uiCommand(rest);
@@ -129,6 +180,7 @@ export async function main() {
                 const chain = findChain(cmd);
                 if (!chain) {
                     console.error(`unknown command or chain: ${cmd}\n`);
+                    reportUnresolvedChain(cmd);
                     console.error(HELP);
                     process.exitCode = 1;
                     return;
@@ -156,5 +208,10 @@ export async function main() {
         // A no-op if notifications are off/unconfigured — awaits any in-flight
         // webhook POST so a fast-exiting command doesn't drop it mid-flight.
         await notify.flushAll();
+        // A no-op if `observability.otel` is not configured — drains the bounded
+        // span queue and awaits any in-flight OTLP POST, under its own hard
+        // deadline, so a fast-exiting command neither drops spans mid-flight nor
+        // waits on an unreachable collector. Never throws (core/otel.ts).
+        await otel.flushAll();
     }
 }

package/dist/cli/interview.js

@@ -21,7 +21,7 @@ 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";
+import { allChains } 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() : "";
@@ -120,7 +120,7 @@ export async function runInterview(asker, ctx) {
             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.");
+            asker.note("spf doctor now probes ANTHROPIC_BASE_URL with a minimal POST /v1/messages (informational only, never a hard failure) and flags a base URL that already ends in \"/v1\" as a likely double-path mistake — the default above (without a trailing /v1) is exactly what that check is guarding against. It still cannot validate ANTHROPIC_AUTH_TOKEN itself.");
         }
         // The packaged roster pins planner/reviewer/documenter to their own
         // Flue-style provider/model-id strings, which always win over
@@ -149,11 +149,44 @@ export async function runInterview(asker, ctx) {
             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);
+        const envKeys = PROVIDER_ENV_KEYS[provider];
+        if (envKeys.length > 0) {
+            const envKey = envKeys[0];
+            const key = await asker.secret(envKey, { current: ctx.existingEnv.get(envKey) });
+            if (key)
+                env[envKey] = key;
+            envExampleKeys.push(envKey);
+        }
+        else {
+            asker.note(`${provider} is keyless — no API key to collect.`);
+            if (provider === "ollama") {
+                // Same shape as the claude_code branch's ANTHROPIC_BASE_URL prompt
+                // above: a local/cloud Ollama server has no key, just an address.
+                // The `/v1` suffix matches agent_flue.ts's own registration default
+                // (spike-verified: Ollama serves its OpenAI-compatible surface —
+                // the one Flue's pi-ai backend actually speaks — under `/v1`, not
+                // at the bare root `/api/...` Ollama also exposes).
+                const baseUrl = await asker.text("OLLAMA_BASE_URL", {
+                    default: "http://localhost:11434/v1",
+                    validate: (v) => (v.trim() ? null : "required"),
+                });
+                env["OLLAMA_BASE_URL"] = baseUrl;
+                envExampleKeys.push("OLLAMA_BASE_URL");
+                asker.note("spf doctor checks this one — a probe against OLLAMA_BASE_URL/models runs on every `spf doctor`.");
+                // Same problem the claude_code branch already solves above: the
+                // packaged roster pins planner/reviewer/documenter to their own
+                // fireworks/gemini/openai model strings, which always win over
+                // defaults.model. Left alone, this flow would produce a config
+                // where three of six agents are still routed at hosted providers
+                // whose keys this ollama flow never collects — `spf doctor` would
+                // immediately report missing FIREWORKS_API_KEY/GEMINI_API_KEY/
+                // OPENAI_API_KEY right after an interview that asked for neither.
+                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 the ollama model chosen above, or spf doctor would report missing FIREWORKS_API_KEY/GEMINI_API_KEY/OPENAI_API_KEY for providers this flow never asked about.");
+            }
+        }
     }
     // Declined (the default): today's behavior exactly — on claude_code, the
     // three-agent auto-pin above stands unchanged; on flue, no agents: block
@@ -222,15 +255,49 @@ export async function runInterview(asker, ctx) {
             { value: "bitbucket", label: "Bitbucket" },
         ], "github");
         const repoHint = codeHost === "bitbucket" ? "workspace/repo_slug" : "owner/name";
-        const repo = await asker.text(`Repo (${repoHint})`, {
+        // github issues + bitbucket code is the one combination where a single
+        // repo field is ambiguous — they're two different repos in two
+        // different systems, not one repo worn two ways (github+github is one
+        // repo by construction; jira never reads `repo` at all). Ask a second,
+        // explicitly-labeled question only in that one case.
+        const splitRepo = issueProvider === "github" && codeHost === "bitbucket";
+        const repo = await asker.text(splitRepo ? `Code repo, where PRs open (${repoHint})` : `Repo (${repoHint})`, {
             default: codeHost === "github" ? ctx.repoSlug ?? "" : "",
             validate: (val) => (val.includes("/") && val.split("/").filter(Boolean).length === 2 ? null : `must be "${repoHint}"`),
         });
+        let issueRepo = "";
+        if (splitRepo) {
+            asker.note("GitHub issues and the Bitbucket code repo are different repos here — spf watch needs both.");
+            issueRepo = await asker.text("Issue repo, where spf:ready issues live (owner/name)", {
+                default: ctx.repoSlug ?? "",
+                validate: (val) => (val.includes("/") && val.split("/").filter(Boolean).length === 2 ? null : `must be "owner/name"`),
+            });
+        }
         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 }));
+        // allChains(), not the built-in-only CHAINS: `registerRepoChains` already
+        // ran in main() before initCommand, so a pre-existing `.spf/chains/`
+        // repo chain is a legal watch.chain everywhere else (watch.ts resolves
+        // it via findChain, doctor.ts validates and labels it) — this picker is
+        // the one place a user chooses watch.chain, so it must offer the same
+        // set. The "(repo)" hint marker distinguishes it in the list.
+        const chainChoices = allChains().map((c) => ({ value: c.name, label: c.name, hint: c.source ? `${c.describe} (repo)` : 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 (issueRepo)
+            watch.issue_repo = issueRepo;
+        // Issue authoring (create + link a hierarchy) is only implemented on
+        // GitHubProvider today — see jira_provider.ts's module comment — so
+        // this lane isn't offered at all on a Jira tracker rather than asking a
+        // question that would just fail at `spf watch` startup.
+        if (issueProvider === "github") {
+            const enableRefine = await asker.confirm(`Also enable the refine lane (decompose a "${labelPrefix}:spec-ready" product spec into a feature/story-or-bug tree)?`, false);
+            if (enableRefine) {
+                const refineChainChoices = allChains().map((c) => ({ value: c.name, label: c.name, hint: c.source ? `${c.describe} (repo)` : c.describe }));
+                const refineChain = await asker.select("Chain to run per spec", refineChainChoices, "refine");
+                watch.refine = { enabled: true, chain: refineChain };
+            }
+        }
         if (issueProvider === "jira") {
             const baseUrl = await asker.text("Jira base URL", {
                 default: "https://your-domain.atlassian.net",
@@ -334,6 +401,11 @@ export async function runInterview(asker, ctx) {
             const concurrency = await asker.text("watch.concurrency", { default: "2" });
             if (concurrency !== "2")
                 watch.concurrency = Number(concurrency);
+            if (watch.refine?.enabled) {
+                const refineConcurrency = await asker.text("watch.refine.concurrency", { default: "1" });
+                if (refineConcurrency !== "1")
+                    watch.refine.concurrency = Number(refineConcurrency);
+            }
         }
         const engineerName = await asker.text("ENGINEER_NAME (falls back to `git config user.name`)", { default: ctx.gitName ?? "" });
         if (engineerName && engineerName !== ctx.gitName)

package/dist/core/agent_cc.d.ts

@@ -11,10 +11,49 @@
  * a wrapper, proxy server, or launcher (e.g., Ollama), set `SPF_CLAUDE_CMD`
  * before running spf. Space-separated command chains are supported:
  *   - `SPF_CLAUDE_CMD="claude"` (default)
- *   - `SPF_CLAUDE_CMD="ollama launch claude"` (Ollama launcher)
+ *   - `SPF_CLAUDE_CMD="ollama launch claude --model <tag>"` (Ollama launcher —
+ *     the `--model` is `ollama launch`'s OWN flag, and is mandatory in
+ *     headless mode; see below)
  * The command/launcher must support the full Claude Code CLI interface.
  * When unset, defaults to `claude`.
  *
+ * Wrapper contract for the flags this module appends (`-p`, `--json-schema`,
+ * `--model`, ...): a wrapper token chain is spawned as `[...cmdTokens,
+ * ...args]`, so a plain passthrough shim needs nothing special, and a
+ * cmdSpec that already contains its own literal `--` is left completely
+ * alone — `args` lands after it exactly as written. `ollama launch <cmd>
+ * [flags...]` is the one documented shape that does NOT self-supply that
+ * separator: it uses cobra flag parsing, which treats anything typed after
+ * `launch <cmd>` as ITS OWN flags unless a literal `--` says otherwise —
+ * spike-verified live: `SPF_CLAUDE_CMD="ollama launch claude"` alone dies
+ * with `unknown shorthand flag: 'p' in -p` before `claude` ever starts
+ * (scratchpad/ollama-spike/probe2-claudecode-ollama/run3_ollama_launch_claude.log).
+ *
+ * The `--` insertion below fixes THAT failure, but is NOT by itself
+ * sufficient to reach `claude` — it only trades one error for the next one.
+ * `ollama launch` also requires its OWN `--model <tag>` flag, typed BEFORE
+ * the `--` separator, whenever it's run headless: with no model flag it
+ * falls back to an interactive model picker, and SPF always spawns with
+ * piped (non-interactive) stdio, so that picker can never run. Spike-verified
+ * live: `--` alone (no `--model` anywhere) dies one step later with `Error:
+ * model selection requires an interactive terminal; use --model to run in
+ * headless mode` (.../run4_ollama_launch_claude_dashdash.log) — that log IS
+ * the "just add `--`" experiment, and it fails. Putting `--model <tag>`
+ * AFTER the separator doesn't help either: at that point it's parsed as
+ * `claude`'s own `--model`, not `ollama launch`'s, so `ollama launch` still
+ * sees no model and still fails the same way. Only supplying `ollama
+ * launch`'s `--model` BEFORE the separator succeeds end-to-end
+ * (.../run5_ollama_launch_claude_full.log). So the operator's `SPF_CLAUDE_CMD`
+ * itself must read `ollama launch claude --model <tag>` (tag from `ollama
+ * list`) — this module can insert the `--`, but cannot supply the model tag
+ * on the operator's behalf; `doctor.ts` hard-fails a `SPF_CLAUDE_CMD` that
+ * omits it, since this is a static, deterministic misconfiguration.
+ *
+ * This module special-cases exactly the `ollama launch ...` token shape
+ * (with no `--` already present) and inserts the separator automatically at
+ * that position — never for any other wrapper, and never a second `--` if
+ * the operator already wrote one themselves.
+ *
  * Every flag below was verified against a REAL local run of this exact
  * machine's `claude` CLI (v2.1.237) before being written — not assumed from
  * the SDK's docs, which describe a related but separately-versioned

package/dist/core/agent_cc.js

@@ -11,10 +11,49 @@
  * a wrapper, proxy server, or launcher (e.g., Ollama), set `SPF_CLAUDE_CMD`
  * before running spf. Space-separated command chains are supported:
  *   - `SPF_CLAUDE_CMD="claude"` (default)
- *   - `SPF_CLAUDE_CMD="ollama launch claude"` (Ollama launcher)
+ *   - `SPF_CLAUDE_CMD="ollama launch claude --model <tag>"` (Ollama launcher —
+ *     the `--model` is `ollama launch`'s OWN flag, and is mandatory in
+ *     headless mode; see below)
  * The command/launcher must support the full Claude Code CLI interface.
  * When unset, defaults to `claude`.
  *
+ * Wrapper contract for the flags this module appends (`-p`, `--json-schema`,
+ * `--model`, ...): a wrapper token chain is spawned as `[...cmdTokens,
+ * ...args]`, so a plain passthrough shim needs nothing special, and a
+ * cmdSpec that already contains its own literal `--` is left completely
+ * alone — `args` lands after it exactly as written. `ollama launch <cmd>
+ * [flags...]` is the one documented shape that does NOT self-supply that
+ * separator: it uses cobra flag parsing, which treats anything typed after
+ * `launch <cmd>` as ITS OWN flags unless a literal `--` says otherwise —
+ * spike-verified live: `SPF_CLAUDE_CMD="ollama launch claude"` alone dies
+ * with `unknown shorthand flag: 'p' in -p` before `claude` ever starts
+ * (scratchpad/ollama-spike/probe2-claudecode-ollama/run3_ollama_launch_claude.log).
+ *
+ * The `--` insertion below fixes THAT failure, but is NOT by itself
+ * sufficient to reach `claude` — it only trades one error for the next one.
+ * `ollama launch` also requires its OWN `--model <tag>` flag, typed BEFORE
+ * the `--` separator, whenever it's run headless: with no model flag it
+ * falls back to an interactive model picker, and SPF always spawns with
+ * piped (non-interactive) stdio, so that picker can never run. Spike-verified
+ * live: `--` alone (no `--model` anywhere) dies one step later with `Error:
+ * model selection requires an interactive terminal; use --model to run in
+ * headless mode` (.../run4_ollama_launch_claude_dashdash.log) — that log IS
+ * the "just add `--`" experiment, and it fails. Putting `--model <tag>`
+ * AFTER the separator doesn't help either: at that point it's parsed as
+ * `claude`'s own `--model`, not `ollama launch`'s, so `ollama launch` still
+ * sees no model and still fails the same way. Only supplying `ollama
+ * launch`'s `--model` BEFORE the separator succeeds end-to-end
+ * (.../run5_ollama_launch_claude_full.log). So the operator's `SPF_CLAUDE_CMD`
+ * itself must read `ollama launch claude --model <tag>` (tag from `ollama
+ * list`) — this module can insert the `--`, but cannot supply the model tag
+ * on the operator's behalf; `doctor.ts` hard-fails a `SPF_CLAUDE_CMD` that
+ * omits it, since this is a static, deterministic misconfiguration.
+ *
+ * This module special-cases exactly the `ollama launch ...` token shape
+ * (with no `--` already present) and inserts the separator automatically at
+ * that position — never for any other wrapper, and never a second `--` if
+ * the operator already wrote one themselves.
+ *
  * Every flag below was verified against a REAL local run of this exact
  * machine's `claude` CLI (v2.1.237) before being written — not assumed from
  * the SDK's docs, which describe a related but separately-versioned
@@ -240,9 +279,17 @@ export async function run(request, onEvent, onSpawn, onExit) {
         "--strict-mcp-config", // see the module doc comment — required, not optional
     ];
     const cmdSpec = process.env.SPF_CLAUDE_CMD || "claude";
-    const [cmd, ...cmdArgs] = cmdSpec.split(/\s+/);
-    const fullArgs = [...cmdArgs, ...args];
-    const child = spawn(cmd, fullArgs, { cwd: request.cwd, env: operatorEnv() });
+    const cmdTokens = cmdSpec.split(/\s+/).filter(Boolean);
+    const [cmd, ...cmdArgs] = cmdTokens;
+    // See the module doc comment for why `ollama launch ...` (and ONLY that
+    // shape) gets an auto-inserted `--`: cobra flag parsing otherwise consumes
+    // `args`' own flags (e.g. `-p`) as `ollama launch`'s, before `claude` is
+    // ever reached. Any cmdSpec that already contains a literal `--` token is
+    // left completely alone — `args` is appended after it exactly as written,
+    // never a second separator.
+    const needsOllamaLaunchSeparator = cmdTokens[0] === "ollama" && cmdTokens[1] === "launch" && !cmdArgs.includes("--");
+    const fullArgs = needsOllamaLaunchSeparator ? [...cmdArgs, "--", ...args] : [...cmdArgs, ...args];
+    const child = spawn(cmd, fullArgs, { cwd: request.cwd, env: request.env ?? operatorEnv() });
     // The prompt travels as a positional argv element, not stdin — closing it
     // immediately avoids a real, observed ~3s "no stdin data received" stall
     // where `claude` otherwise waits to see whether anything is piped in.

package/dist/core/agent_flue.js

@@ -25,6 +25,7 @@
 import { AgentRunError, createBashTool, createEditTool, createGlobTool, createGrepTool, createReadTool, createWriteTool, init, observe, useDataWriter, useModel, useSandbox, useTool, } from "@flue/runtime";
 import { local, sqlite, start } from "@flue/runtime/node";
 import { UsageBreakdown, makeAgentResult } from "./data_types.js";
+import { registerOllamaModel } from "./ollama_provider.js";
 import { nowIso, operatorEnv } from "./utils.js";
 const RESULT_SNIPPET_CHARS = 20_000; // tool output rides along whole; clip only guards pathological cases
 const ARG_VALUE_CHARS = 20_000; // args too — the UI scrolls, it must not be handed cut-off data
@@ -156,10 +157,12 @@ function resolveBuiltinTools(names) {
  * `undefined`/`null` toolNames = every builtin (Flue's own default when no
  * `tools` override is given — matches SPF's "unset = all tools usable").
  * `local()`'s env does NOT inherit process.env by default (only PATH/HOME/
- * USER/LANG/TERM/TMPDIR) — operatorEnv() restores today's actual behavior.
+ * USER/LANG/TERM/TMPDIR) — `env` is `request.env ?? operatorEnv()` from the
+ * caller, restoring today's actual behavior unless the agent's own
+ * `env_allowlist` narrowed it (see agents.ts).
  */
-function sandboxFor(toolNames, cwd) {
-    const base = local({ cwd, env: operatorEnv() });
+function sandboxFor(toolNames, cwd, env) {
+    const base = local({ cwd, env });
     if (!toolNames)
         return base;
     const factories = resolveBuiltinTools(toolNames);
@@ -188,7 +191,7 @@ function sfAgentRender({ id }) {
     if (!spec)
         throw new Error(`agent_flue: no render spec registered for conversation ${id} — run() must set it before dispatching`);
     useModel(spec.model, { thinkingLevel: spec.thinking });
-    useSandbox(sandboxFor(spec.toolNames, spec.cwd));
+    useSandbox(sandboxFor(spec.toolNames, spec.cwd, spec.env));
     const writeReport = useDataWriter("sf_report");
     useTool({
         name: "sf_report",
@@ -265,6 +268,26 @@ function contextTokensOf(usage) {
  * not attempted here.
  */
 export async function run(request, onEvent, onSpawn, onExit) {
+    // Ollama has no pi-ai/Flue built-in provider — it must be registered as a
+    // custom `createProvider(...)` before anything dispatches against it (see
+    // ollama_provider.ts's header comment for why: dummy api key, union
+    // re-registration, exact version pin). Doing this BEFORE `ensureRuntime()`
+    // means it's in place before that call's `start()` ever gets a chance to
+    // run its own default-provider registration — irrelevant today (pi-ai ships
+    // no "ollama" built-in to collide with) but keeps the ordering the one a
+    // future built-in couldn't quietly undermine. `resolveModel` is a cheap
+    // string split regardless of provider, so the check above costs nothing
+    // extra for a non-ollama agent — but `registerOllamaModel`'s own dynamic
+    // imports are NOT a load-time saving for the ollama case either (this
+    // module's own unconditional `@flue/runtime/node` import already pulls in
+    // pi-ai's full runtime for every run; see ollama_provider.ts's header
+    // comment for the measured numbers). What the lazy boundary actually buys
+    // is keeping ollama-only symbols off the module graph of anything that
+    // imports this module for `resolveModel()` alone (doctor.ts, interview.ts)
+    // without ever dispatching an ollama call.
+    const [provider, modelId] = resolveModel(request.model);
+    if (provider === "ollama")
+        await registerOllamaModel(modelId);
     await ensureRuntime(request.flue_db_path);
     REGISTRY.set(request.session_id, {
         model: request.model,
@@ -274,6 +297,7 @@ export async function run(request, onEvent, onSpawn, onExit) {
         systemText: request.system_prompt,
         outputSchema: request.output_schema,
         outputTypeName: request.output_type_name,
+        env: request.env ?? operatorEnv(),
     });
     const pid = process.pid ?? -1;
     onSpawn?.(pid);

package/dist/core/agents.d.ts

@@ -8,6 +8,14 @@
  * disposes.
  */
 import { GateReport, makeEventRecord, type AgentCall, type AgentConfig, type EnvelopeBase, type Phase, type SFConfig } from "./data_types.ts";
+/**
+ * `undefined` (no `env_allowlist` configured — the default) means "don't
+ * filter at all"; both backends treat that as `request.env ?? operatorEnv()`,
+ * i.e. today's unfiltered behavior, byte-identical. Configured, this filters
+ * the operator's own environment down to the named keys plus the baseline
+ * `local()` would keep anyway.
+ */
+export declare function agentEnv(agent: AgentConfig): Record<string, string> | undefined;
 export declare class GateFailure extends Error {
 }
 /**

package/dist/core/agents.js

@@ -17,8 +17,32 @@ import * as paths from "./paths.js";
 import * as permissions from "./permissions.js";
 import * as prompts from "./prompts.js";
 import { GateReport, UsageBreakdown, makeEventRecord, SFConfigSchema, } from "./data_types.js";
-import { newId } from "./utils.js";
+import { newId, operatorEnv } from "./utils.js";
 const JSON_FIX_ATTEMPTS = 2; // continue-with-correction attempts for malformed JSON
+// Kept alongside agent_flue.ts's own comment on this same list — `local()`'s
+// sandbox keeps these regardless of any `env` override, so an allowlist that
+// omitted them would silently lose them there but not on agent_cc.ts's plain
+// `spawn()`. Folding them in here keeps both backends' filtered env identical.
+const ENV_BASELINE_KEYS = ["PATH", "HOME", "USER", "LANG", "TERM", "TMPDIR"];
+/**
+ * `undefined` (no `env_allowlist` configured — the default) means "don't
+ * filter at all"; both backends treat that as `request.env ?? operatorEnv()`,
+ * i.e. today's unfiltered behavior, byte-identical. Configured, this filters
+ * the operator's own environment down to the named keys plus the baseline
+ * `local()` would keep anyway.
+ */
+export function agentEnv(agent) {
+    if (!agent.env_allowlist)
+        return undefined;
+    const operator = operatorEnv();
+    const keep = new Set([...ENV_BASELINE_KEYS, ...agent.env_allowlist]);
+    const env = {};
+    for (const key of keep) {
+        if (operator[key] !== undefined)
+            env[key] = operator[key];
+    }
+    return env;
+}
 export class GateFailure extends Error {
 }
 /**
@@ -57,7 +81,19 @@ function mergeAgentLists(base, override) {
     }
     return merged;
 }
-/** `defaults`/`observability`/`quality`/`watch`/`notifications` merge key-by-key; `agents` merges by name. */
+/**
+ * `defaults`/`observability`/`quality`/`watch`/`notifications`/`review` merge
+ * key-by-key; `agents` merges by name.
+ *
+ * THE SILENT-DROP TRAP (adversarial history, not a hypothetical): this
+ * function returns a FIXED-SHAPE object literal — every top-level `SFConfig`
+ * key has to be named on BOTH sides of every merged field here, by hand, or
+ * a `.spf/spf.config.yaml` value for it is silently discarded before
+ * `v.parse(SFConfigSchema, raw)` ever sees it. Adding a key to
+ * `SFConfigSchema` without adding it here is exactly that bug — see
+ * `data_types.test.ts`'s merge-survival test for `review`, which is the
+ * regression guard this comment is here to justify.
+ */
 function mergeRawConfig(base, override) {
     return {
         defaults: { ...(base.defaults || {}), ...(override.defaults || {}) },
@@ -67,6 +103,9 @@ function mergeRawConfig(base, override) {
         // 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 || {}) },
+        // review.require_human_signoff / review.signoff_timeout_seconds — see
+        // data_types.ts's ReviewConfigSchema doc comment for why this key exists.
+        review: { ...(base.review || {}), ...(override.review || {}) },
         agents: mergeAgentLists(base.agents || [], override.agents || []),
     };
 }
@@ -90,7 +129,7 @@ export function loadConfig(configPaths) {
     }
     const defaults = raw.defaults || {};
     for (const agent of raw.agents || []) {
-        for (const key of ["coding_agent", "model", "thinking", "color", "tools", "writes"]) {
+        for (const key of ["coding_agent", "model", "thinking", "color", "tools", "writes", "env_allowlist"]) {
             if (key in defaults && !(key in agent))
                 agent[key] = defaults[key];
         }
@@ -231,6 +270,7 @@ export async function execute(run, phase, call) {
             output_type_name: call.output_type.name,
             cwd: run.repo_root,
             flue_db_path: path.join(run.data_dir, "flue.db"),
+            env: agentEnv(agent),
         };
         const forward = eventForwarder(run, phase, agent.name, agent.coding_agent);
         const onSpawn = (pid) => run.tracer.processStart(run.adw_id, "agent", agent.name, pid, `${agent.coding_agent} ${agent.name} ${agent.model}`);