@gr8ful/spf 0.4.0 → 0.5.1

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}`);

package/dist/core/data_types.d.ts

@@ -376,6 +376,7 @@ export declare const AgentConfigSchema: v.ObjectSchema<{
     readonly harness_engineering: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
     readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
     readonly writes: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
+    readonly env_allowlist: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
 }, undefined>;
 export type AgentConfig = v.InferOutput<typeof AgentConfigSchema>;
 export declare const ConfigDefaultsSchema: v.ObjectSchema<{
@@ -389,9 +390,35 @@ export declare const ConfigDefaultsSchema: v.ObjectSchema<{
     readonly data_dir: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data">;
 }, undefined>;
 export type ConfigDefaults = v.InferOutput<typeof ConfigDefaultsSchema>;
+/**
+ * OpenTelemetry span export — OFF unless this block exists, and `endpoint` is
+ * required BY THIS SCHEMA rather than defaulted, because presence of the block
+ * IS the activation switch. No ambient environment variable can turn export on
+ * (notably NOT `OTEL_EXPORTER_OTLP_ENDPOINT`): an unrelated shell variable must
+ * never become a data-egress switch. See `core/otel.ts`'s header for the full
+ * set of constraints, including the attribute allowlist that keeps repo source
+ * code (tool args, prompts, envelopes, the request text) off the wire.
+ *
+ * `endpoint` is URL-validated so a typo fails at config load rather than as a
+ * silent per-run export failure. Either the full OTLP traces path
+ * (`https://collector:4318/v1/traces`) or a bare origin (`/v1/traces` is
+ * appended — see `resolveTracesUrl`). `headers` is where a collector's auth
+ * token goes; its VALUES are treated as secrets and never logged.
+ */
+export declare const OTelConfigSchema: v.ObjectSchema<{
+    readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
+    readonly headers: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+    readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+}, undefined>;
+export type OTelConfig = v.InferOutput<typeof OTelConfigSchema>;
 export declare const ObservabilityConfigSchema: v.ObjectSchema<{
     readonly db: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data/spf.db">;
     readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 500>;
+    readonly otel: v.OptionalSchema<v.ObjectSchema<{
+        readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
+        readonly headers: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+        readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+    }, undefined>, undefined>;
 }, undefined>;
 export type ObservabilityConfig = v.InferOutput<typeof ObservabilityConfigSchema>;
 /**
@@ -409,8 +436,25 @@ export type ObservabilityConfig = v.InferOutput<typeof ObservabilityConfigSchema
  * watch` startup, not here — an empty string parses fine (this schema has
  * no opinion on whether watch is even configured), matching the same
  * "fails loudly before anything spawns, not eagerly at parse time" pattern
- * `quality:` already uses. Its shape depends on `code_host`: "owner/name"
- * for github, "workspace/repo_slug" for bitbucket.
+ * `quality:` already uses. `repo` always names `code_host`'s own repo —
+ * its shape depends on `code_host`: "owner/name" for github,
+ * "workspace/repo_slug" for bitbucket. `resolveCodeHostProvider`
+ * (`cli/commands/watch.ts`) always reads it.
+ *
+ * `issue_repo` exists for exactly one combination where that single field
+ * stops being enough: `issue_provider: github` with `code_host: bitbucket`
+ * — GitHub-issues-against-a-Bitbucket-repo, a real setup this project
+ * explicitly supports, where the issue tracker and the code host are
+ * genuinely different repos in different systems, not the same repo worn
+ * two ways. Every other combination stays a single field: `issue_provider:
+ * github` + `code_host: github` is one repo by construction; `issue_provider:
+ * jira` never reads `repo` at all (it uses `jira.base_url`/`project_key`),
+ * so `repo` unambiguously belongs to whichever code host is configured.
+ * `resolveIssueProvider`'s github branch and `core/refine.ts`'s
+ * `resolveAuthoringProvider` (issue authoring always targets the issue
+ * tracker, never the code host) both read `issue_repo || repo` — leaving
+ * `issue_repo` unset is a complete no-op, so no existing config needs to
+ * change.
  */
 export declare const WatchIssueProviderSchema: v.PicklistSchema<["github", "jira"], undefined>;
 export type WatchIssueProviderKind = v.InferOutput<typeof WatchIssueProviderSchema>;
@@ -442,6 +486,7 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
     readonly issue_provider: v.OptionalSchema<v.PicklistSchema<["github", "jira"], undefined>, "github">;
     readonly code_host: v.OptionalSchema<v.PicklistSchema<["github", "bitbucket"], undefined>, "github">;
     readonly repo: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly issue_repo: v.OptionalSchema<v.StringSchema<undefined>, "">;
     readonly label_prefix: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
     readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "plan-build-test">;
     readonly base_branch: v.OptionalSchema<v.StringSchema<undefined>, "main">;
@@ -501,6 +546,34 @@ export declare const NotificationsConfigSchema: v.ObjectSchema<{
     }, undefined>, undefined>, () => never[]>;
 }, undefined>;
 export type NotificationsConfig = v.InferOutput<typeof NotificationsConfigSchema>;
+/**
+ * `simple_sdlc`'s human-signoff gate — see the ACCEPTED ADVERSARIAL
+ * AMENDMENTS on the review-accountability thread. `simple_sdlc.ts`'s
+ * `commit_build` predicate is the ONLY place in this codebase where an AI
+ * reviewer's `approved` flag gates a commit; `decideSignoff` (same file)
+ * turns that PROPOSAL into a human's DISPOSAL wherever a human is at the
+ * keyboard, and reads these two knobs when there isn't one.
+ *
+ * `require_human_signoff` defaults to FALSE for this release, deliberately:
+ * flipping it to fail-closed-by-default would break every unattended
+ * `simple-sdlc` run (`spf watch`, CI) the day this shipped, before `spf
+ * watch` itself is signoff-aware (its own human gate today is the PR merge,
+ * now informed by the reviewer digest — see `cli/commands/watch.ts`). An
+ * unattended run instead proceeds on the AI verdict alone with a LOUD
+ * one-time warning (`decideSignoff`'s `AI_ONLY_SIGNOFF_WARNING`) until that
+ * changes. Set `true` and an unattended run fails the phase CLOSED instead —
+ * see `decideSignoff`'s fail-closed branch — rather than silently
+ * auto-approving because nobody typed at a prompt that was never shown.
+ *
+ * `signoff_timeout_seconds` bounds the interactive prompt itself: expiry
+ * means NOT accepted (the confirm's own default), never an unbounded stdin
+ * read inside `run.phase()` — see `cli/ask.ts`'s `confirm(..., {timeoutMs})`.
+ */
+export declare const ReviewConfigSchema: v.ObjectSchema<{
+    readonly require_human_signoff: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+    readonly signoff_timeout_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 300>;
+}, undefined>;
+export type ReviewConfig = v.InferOutput<typeof ReviewConfigSchema>;
 export declare const SFConfigSchema: v.ObjectSchema<{
     readonly defaults: v.OptionalSchema<v.ObjectSchema<{
         readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
@@ -524,9 +597,21 @@ export declare const SFConfigSchema: v.ObjectSchema<{
     readonly observability: v.OptionalSchema<v.ObjectSchema<{
         readonly db: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data/spf.db">;
         readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 500>;
+        readonly otel: v.OptionalSchema<v.ObjectSchema<{
+            readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
+            readonly headers: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+            readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+        }, undefined>, undefined>;
     }, undefined>, () => {
         db: string;
         poll_ms: number;
+        otel?: {
+            endpoint: string;
+            headers?: {
+                [x: string]: string;
+            } | undefined;
+            service_name: string;
+        } | undefined;
     }>;
     readonly agents: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
         readonly name: v.StringSchema<undefined>;
@@ -542,6 +627,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly harness_engineering: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
         readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
         readonly writes: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
+        readonly env_allowlist: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
     }, undefined>, undefined>, () => never[]>;
     readonly quality: v.OptionalSchema<v.ObjectSchema<{
         readonly checks: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
@@ -568,6 +654,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly issue_provider: v.OptionalSchema<v.PicklistSchema<["github", "jira"], undefined>, "github">;
         readonly code_host: v.OptionalSchema<v.PicklistSchema<["github", "bitbucket"], undefined>, "github">;
         readonly repo: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        readonly issue_repo: v.OptionalSchema<v.StringSchema<undefined>, "">;
         readonly label_prefix: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
         readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "plan-build-test">;
         readonly base_branch: v.OptionalSchema<v.StringSchema<undefined>, "main">;
@@ -593,6 +680,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         issue_provider: "github" | "jira";
         code_host: "bitbucket" | "github";
         repo: string;
+        issue_repo: string;
         label_prefix: string;
         chain: string;
         base_branch: string;
@@ -627,13 +715,24 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             name: string;
         }[];
     }>;
+    readonly review: v.OptionalSchema<v.ObjectSchema<{
+        readonly require_human_signoff: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+        readonly signoff_timeout_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 300>;
+    }, undefined>, () => {
+        require_human_signoff: boolean;
+        signoff_timeout_seconds: number;
+    }>;
 }, undefined>;
 export type SFConfig = v.InferOutput<typeof SFConfigSchema>;
+/** The full set of event kinds any tracer.event()/makeEventRecord() call site emits — kept in sync with src/ui/shared/types.ts's EventType. */
+export declare const EVENT_RECORD_TYPES: readonly ["phase_start", "agent_start", "tool_call", "handoff", "gate_pass", "gate_fail", "log", "agent_end", "phase_end", "error"];
+export declare const EventRecordTypeSchema: v.PicklistSchema<readonly ["phase_start", "agent_start", "tool_call", "handoff", "gate_pass", "gate_fail", "log", "agent_end", "phase_end", "error"], undefined>;
+export type EventRecordType = v.InferOutput<typeof EventRecordTypeSchema>;
 /** One traced event, always logged against adw_id + phase. */
 export interface EventRecord {
     adw_id: string;
     phase_id: string;
-    type: string;
+    type: EventRecordType;
     name: string;
     payload: Record<string, unknown>;
     parent_id: string;
@@ -643,7 +742,7 @@ export interface EventRecord {
 }
 export declare function makeEventRecord(input: Partial<EventRecord> & {
     adw_id: string;
-    type: string;
+    type: EventRecordType;
 }): EventRecord;
 /**
  * Everything one coding-agent dispatch+read turn needs, whichever backend
@@ -675,6 +774,7 @@ export interface AgentRequest {
     output_type_name: string;
     cwd: string;
     flue_db_path: string;
+    env?: Record<string, string>;
 }
 /**
  * Tokens and the dollars they cost, per component, summed over a call.

package/dist/core/data_types.js

@@ -281,6 +281,15 @@ export const AgentConfigSchema = v.object({
     //   [...]     -> only these. A trailing "/" means a directory prefix; a "*"
     //                makes it a glob; anything else is an exact path.
     writes: v.optional(v.nullable(v.array(v.string()))),
+    // Opt-in env allowlist for this agent's subprocess/sandbox environment.
+    // undefined/null (the default) -> unrestricted: the full operator
+    // environment is passed through, byte-identical to before this field
+    // existed — same three-state shape as `writes` above, so `null` (the
+    // spelling config.md teaches for "unrestricted") parses instead of
+    // rejecting. Set -> only these keys, plus the baseline
+    // (PATH/HOME/USER/LANG/TERM/TMPDIR) that agent_flue.ts's local() sandbox
+    // would keep anyway.
+    env_allowlist: v.optional(v.nullable(v.array(v.string()))),
 });
 export const ConfigDefaultsSchema = v.object({
     coding_agent: v.optional(v.picklist(["flue", "claude_code"]), "flue"),
@@ -296,9 +305,36 @@ export const ConfigDefaultsSchema = v.object({
     protected_files: v.optional(v.array(v.string()), () => [".spf/", "spf.config.yaml"]),
     data_dir: v.optional(v.string(), ".spf/data"),
 });
+/**
+ * OpenTelemetry span export — OFF unless this block exists, and `endpoint` is
+ * required BY THIS SCHEMA rather than defaulted, because presence of the block
+ * IS the activation switch. No ambient environment variable can turn export on
+ * (notably NOT `OTEL_EXPORTER_OTLP_ENDPOINT`): an unrelated shell variable must
+ * never become a data-egress switch. See `core/otel.ts`'s header for the full
+ * set of constraints, including the attribute allowlist that keeps repo source
+ * code (tool args, prompts, envelopes, the request text) off the wire.
+ *
+ * `endpoint` is URL-validated so a typo fails at config load rather than as a
+ * silent per-run export failure. Either the full OTLP traces path
+ * (`https://collector:4318/v1/traces`) or a bare origin (`/v1/traces` is
+ * appended — see `resolveTracesUrl`). `headers` is where a collector's auth
+ * token goes; its VALUES are treated as secrets and never logged.
+ */
+export const OTelConfigSchema = v.object({
+    endpoint: v.pipe(v.string(), v.url()),
+    headers: v.optional(v.record(v.string(), v.string()), undefined),
+    service_name: v.optional(v.string(), "spf"),
+});
 export const ObservabilityConfigSchema = v.object({
     db: v.optional(v.string(), ".spf/data/spf.db"),
     poll_ms: v.optional(v.number(), 500),
+    // Absent by default. `agents.ts`'s mergeRawConfig spreads `observability`
+    // field-by-field, so this nested object merges as a WHOLE-OBJECT replace on
+    // override — an override that sets `otel:` replaces the base's entirely,
+    // which is the semantics you want for an endpoint + its headers (a
+    // half-merged pair of the two would send tokens to the wrong collector).
+    // Pinned by a merge-survival test in src/test/data_types.test.ts.
+    otel: v.optional(OTelConfigSchema),
 });
 /**
  * `spf watch`'s configuration. `issue_provider` (the tracker) and
@@ -315,8 +351,25 @@ export const ObservabilityConfigSchema = v.object({
  * watch` startup, not here — an empty string parses fine (this schema has
  * no opinion on whether watch is even configured), matching the same
  * "fails loudly before anything spawns, not eagerly at parse time" pattern
- * `quality:` already uses. Its shape depends on `code_host`: "owner/name"
- * for github, "workspace/repo_slug" for bitbucket.
+ * `quality:` already uses. `repo` always names `code_host`'s own repo —
+ * its shape depends on `code_host`: "owner/name" for github,
+ * "workspace/repo_slug" for bitbucket. `resolveCodeHostProvider`
+ * (`cli/commands/watch.ts`) always reads it.
+ *
+ * `issue_repo` exists for exactly one combination where that single field
+ * stops being enough: `issue_provider: github` with `code_host: bitbucket`
+ * — GitHub-issues-against-a-Bitbucket-repo, a real setup this project
+ * explicitly supports, where the issue tracker and the code host are
+ * genuinely different repos in different systems, not the same repo worn
+ * two ways. Every other combination stays a single field: `issue_provider:
+ * github` + `code_host: github` is one repo by construction; `issue_provider:
+ * jira` never reads `repo` at all (it uses `jira.base_url`/`project_key`),
+ * so `repo` unambiguously belongs to whichever code host is configured.
+ * `resolveIssueProvider`'s github branch and `core/refine.ts`'s
+ * `resolveAuthoringProvider` (issue authoring always targets the issue
+ * tracker, never the code host) both read `issue_repo || repo` — leaving
+ * `issue_repo` unset is a complete no-op, so no existing config needs to
+ * change.
  */
 export const WatchIssueProviderSchema = v.picklist(["github", "jira"]);
 export const WatchCodeHostSchema = v.picklist(["github", "bitbucket"]);
@@ -344,6 +397,7 @@ export const WatchConfigSchema = v.object({
     issue_provider: v.optional(WatchIssueProviderSchema, "github"),
     code_host: v.optional(WatchCodeHostSchema, "github"),
     repo: v.optional(v.string(), ""),
+    issue_repo: v.optional(v.string(), ""),
     label_prefix: v.optional(v.string(), "spf"),
     chain: v.optional(v.string(), "plan-build-test"),
     base_branch: v.optional(v.string(), "main"),
@@ -381,6 +435,33 @@ export const NotificationsConfigSchema = v.object({
     timeout_ms: v.optional(v.number(), 5_000),
     channels: v.optional(v.array(NotifyChannelSchema), () => []),
 });
+/**
+ * `simple_sdlc`'s human-signoff gate — see the ACCEPTED ADVERSARIAL
+ * AMENDMENTS on the review-accountability thread. `simple_sdlc.ts`'s
+ * `commit_build` predicate is the ONLY place in this codebase where an AI
+ * reviewer's `approved` flag gates a commit; `decideSignoff` (same file)
+ * turns that PROPOSAL into a human's DISPOSAL wherever a human is at the
+ * keyboard, and reads these two knobs when there isn't one.
+ *
+ * `require_human_signoff` defaults to FALSE for this release, deliberately:
+ * flipping it to fail-closed-by-default would break every unattended
+ * `simple-sdlc` run (`spf watch`, CI) the day this shipped, before `spf
+ * watch` itself is signoff-aware (its own human gate today is the PR merge,
+ * now informed by the reviewer digest — see `cli/commands/watch.ts`). An
+ * unattended run instead proceeds on the AI verdict alone with a LOUD
+ * one-time warning (`decideSignoff`'s `AI_ONLY_SIGNOFF_WARNING`) until that
+ * changes. Set `true` and an unattended run fails the phase CLOSED instead —
+ * see `decideSignoff`'s fail-closed branch — rather than silently
+ * auto-approving because nobody typed at a prompt that was never shown.
+ *
+ * `signoff_timeout_seconds` bounds the interactive prompt itself: expiry
+ * means NOT accepted (the confirm's own default), never an unbounded stdin
+ * read inside `run.phase()` — see `cli/ask.ts`'s `confirm(..., {timeoutMs})`.
+ */
+export const ReviewConfigSchema = v.object({
+    require_human_signoff: v.optional(v.boolean(), false),
+    signoff_timeout_seconds: v.optional(v.pipe(v.number(), v.minValue(1)), 300),
+});
 export const SFConfigSchema = v.object({
     defaults: v.optional(ConfigDefaultsSchema, () => v.parse(ConfigDefaultsSchema, {})),
     observability: v.optional(ObservabilityConfigSchema, () => v.parse(ObservabilityConfigSchema, {})),
@@ -388,7 +469,23 @@ export const SFConfigSchema = v.object({
     quality: v.optional(QualityConfigSchema, () => v.parse(QualityConfigSchema, {})),
     watch: v.optional(WatchConfigSchema, () => v.parse(WatchConfigSchema, {})),
     notifications: v.optional(NotificationsConfigSchema, () => v.parse(NotificationsConfigSchema, {})),
+    review: v.optional(ReviewConfigSchema, () => v.parse(ReviewConfigSchema, {})),
 });
+// ── Tracing ──────────────────────────────────────────────────────────────────
+/** The full set of event kinds any tracer.event()/makeEventRecord() call site emits — kept in sync with src/ui/shared/types.ts's EventType. */
+export const EVENT_RECORD_TYPES = [
+    "phase_start",
+    "agent_start",
+    "tool_call",
+    "handoff",
+    "gate_pass",
+    "gate_fail",
+    "log",
+    "agent_end",
+    "phase_end",
+    "error",
+];
+export const EventRecordTypeSchema = v.picklist(EVENT_RECORD_TYPES);
 export function makeEventRecord(input) {
     return {
         phase_id: "",