@gr8ful/spf 0.9.2 → 0.10.0

package/README.md

@@ -441,6 +441,9 @@ watch:
     concurrency: 1          # this lane's own budget, independent of watch.concurrency
 ```
 
+(A third, independent budget lives at `watch.fanout.concurrency` — best-of-N
+attempts per claimed issue, not specs. See "Best-of-N per issue" below.)
+
 On Jira, every `RefinedIssue.kind` (`epic`/`feature`/`story`/`bug`/`task`) maps
 to a real Jira issue type through `watch.jira.issue_types` — defaults
 `epic`/`feature` → `Epic`, `story` → `Story`, `bug` → `Bug`, `task` → `Task`,
@@ -587,6 +590,59 @@ container/leaf shape that skill left as prose convention rather than a
 checked rule, now also enforcing that a refinement never publishes issues and
 raises questions in the same round.
 
+### Best-of-N per issue (`watch.fanout`)
+
+`spf fanout` runs N sibling attempts of one prompt and lets code pick the
+winner (`pickBest`: succeeded > fewest gate failures > most gate passes >
+lowest cost > fewest tokens > lowest wall time > adw_id, see the `spf fanout`
+section above). `watch.fanout` is that same mechanism pointed at `spf watch`'s
+per-issue dispatch: a claimed issue runs `n` sibling attempts instead of one,
+and everything downstream of the winner — push, PR, review digest, marker,
+transition, notify — is the same code that already runs for a single attempt.
+
+```yaml
+watch:
+  repo: owner/name
+  chain: plan-build-test    # must have a commit step once n > 1 — see below
+  concurrency: 2             # issues claimed and run at once — UNCHANGED meaning
+  fanout:
+    n: 1                     # attempts per claimed issue. 1 (the default) = today's single dispatch, no-op for the daemon
+    concurrency: 2            # attempts of ONE issue's fan-out in flight — NOT watch.concurrency
+```
+
+Two budgets, two names, on purpose: `watch.concurrency` counts **issues** in
+flight (unchanged); `watch.fanout.concurrency` counts **attempts of one
+issue's fan-out** in flight. They multiply rather than share one number — an
+operator who wants "2 issues at a time, 1 attempt each" (serialize attempts,
+keep issue-level parallelism) can say exactly that by setting
+`fanout.concurrency: 1`, which a single shared knob couldn't express. `spf
+doctor`'s `watch.fanout` line prints the product (`concurrency × fanout.concurrency`
+chain runs in flight) so nobody has to compute it by hand.
+
+**Disk, not just chain runs.** `fanout.concurrency` bounds attempts *in
+flight*; it does **not** bound worktrees *on disk*. A successful attempt's
+worktree is kept until every sibling in its fan-out has settled (it's still a
+selection candidate), so peak disk per wave is `watch.concurrency ×
+watch.fanout.n` full checkouts, not `watch.concurrency × watch.fanout.concurrency`
+— at `concurrency: 4, fanout.n: 8` that's 32 working copies at once under
+`worktreesDir` (`~/.spf/watch/<repo>/worktrees`). Plan disk against `n`, not
+against `fanout.concurrency`.
+
+`n > 1` requires `chain` to have a commit step — `spf watch` refuses to start
+otherwise. The reason is sharper than `spf fanout`'s own version of this
+check: best-of-N force-removes every losing attempt's worktree once a winner
+is picked, `--force` included, and a chain that never commits leaves its
+entire payload as uncommitted edits — fan-out would destroy N-1 candidates
+outright rather than just fail one attempt. `n: 1` has no such requirement (a
+chain that commits nothing is handled the same honest way it always has been:
+blocked, worktree cleaned, nothing discarded).
+
+`n: 1` (the default) changes nothing about a running daemon's observable
+behaviour — same adw_id, same branch, same worktree, same fetch semantics,
+same marker, same PR. `spf doctor` still prints one informational
+`watch.fanout` line either way, so the posture is visible even when best-of-N
+is off.
+
 ### GitHub (`issue_provider: github` and/or `code_host: github`)
 
 ```bash

package/assets/defaults/spf.config.yaml

@@ -120,6 +120,81 @@ tiering:
     refiner:    builder
     reviewer:   deep
 
+# Remote sandbox backends (SPF #15) — everything below is optional; omitting
+# the whole block means backend: local, i.e. byte-identical to SPF before
+# this feature existed (every agent's tools run against the real working
+# tree, exactly as today). See config.md's "sandbox" section for the full
+# field-by-field rationale — this is the commented-out shape only.
+# sandbox:
+#   backend: local              # local | opensandbox | cloudflare   (default: local)
+#   scope: agent                # agent (DEFAULT) | run — see config.md: "run" is only safe
+#                                # when every dispatched agent resolves to the SAME env key set.
+#   workspace_dir: /workspace   # absolute path INSIDE the sandbox; the agent's cwd
+#   handoff_dir: /spf/handoff   # absolute path INSIDE the sandbox — MUST NOT be under
+#                                # workspace_dir (validate() rejects it if it is)
+#   scratch_dir: /spf/tmp       # the transport's own scratch plane — same rule as handoff_dir
+#   image: ""                   # opensandbox only. NO DEFAULT — required (must contain
+#                                # git + tar + base64) when the resolved backend is opensandbox
+#   setup: []                   # shell commands run ONCE per sandbox, after seeding
+#                                #   e.g. ["npm ci --omit=dev"]
+#   request_timeout_seconds: 960   # the SDK's client-side HTTP timeout on control-plane calls
+#   lifetime_seconds: 3600         # provider-side expiry, renewed while a lease is live
+#   max_total_lifetime_seconds: 21600  # hard ceiling from creation; renew refuses past it
+#   exec_timeout_seconds: 900      # the DEFAULT per-command deadline (not a ceiling — a
+#                                  # caller-supplied timeout is honored, never clamped)
+#   env_allowlist: []           # e.g. ["GH_TOKEN"] — DEFAULT IS EMPTY, deliberately NOT the
+#                                # operator env backend: local gets today. The set that
+#                                # actually reaches a container is this list INTERSECTED
+#                                # with that agent's own env_allowlist.
+#   credentials:
+#     broker: static             # static is the only REGISTERED broker in this build — an
+#                                # unrecognized name is a hard validate() failure, never a
+#                                # silent fallback to static
+#   egress:
+#     default: deny              # deny | allow
+#     allow: []                  # hostnames, e.g. ["registry.npmjs.org", "github.com"]
+#   transport:
+#     max_patch_bytes: 8388608     # 8 MiB — exceeding it FAILS the phase, never truncates
+#     max_seed_bytes: 134217728    # 128 MiB seed archive ceiling
+#     max_mirror_bytes: 4194304    # 4 MiB per handoff-mirror transfer, each direction
+#     mirror: []                  # extra repo-relative paths to sync out that git can't carry
+#   fanout: worktree             # worktree | sandbox — "sandbox" fans out THROUGH sandboxes
+#                                 # too: each attempt gets its own lease(s), keyed on its own
+#                                 # derived <base>-<i> adw_id. The winning branch/worktree stay
+#                                 # local either way.
+#   opensandbox:
+#     base_url: http://127.0.0.1:8090
+#     api_key_env: OPENSANDBOX_API_KEY   # env KEY NAME, never the key itself
+#     use_server_proxy: false
+#     metadata_prefix: spf
+#   cloudflare:
+#     bridge_url: ""                     # a deployed @cloudflare/sandbox bridge
+#     api_token_env: CLOUDFLARE_API_TOKEN
+#     sandbox_name: ""                   # optional stable name; default derives from the lease key
+#
+# Per-agent backend override, added to an `agents[]` entry alongside `writes`/
+# `env_allowlist` above — a bare backend name, never a nested block:
+#   agents:
+#     - name: builder
+#       sandbox: opensandbox      # unset -> inherit sandbox.backend; "local" -> force local
+
+# `spf watch` — off unless watch.repo is set. `watch.fanout` (best-of-N per
+# claimed issue) is one sub-key of it, shown here in isolation since it's the
+# one with its own budget math; see README.md's "spf watch" section and
+# config.md's "watch" table for the rest of the block (repo, chain,
+# label_prefix, ...). Not to be confused with `sandbox.fanout` above, a
+# different key entirely (worktree vs sandbox execution for `spf fanout`'s
+# own attempts).
+# watch:
+#   chain: plan-build-test       # must have a commit step once fanout.n > 1 — spf watch refuses to start otherwise
+#   concurrency: 2                # issues claimed and run at once — UNCHANGED by fanout
+#   fanout:
+#     n: 1                        # attempts per claimed issue. 1 (default) = single dispatch, a total no-op for the daemon
+#     concurrency: 2               # attempts of ONE issue's fan-out in flight — NOT watch.concurrency, which counts issues.
+#                                  # The two multiply (spf doctor prints the product); disk peak is concurrency x fanout.n,
+#                                  # not concurrency x fanout.concurrency — a kept attempt's worktree survives until every
+#                                  # sibling in its own fan-out has settled.
+
 agents:
   - name: planner
     model: fireworks/accounts/fireworks/models/kimi-k3

package/assets/skill/references/config.md

@@ -12,10 +12,12 @@ always shows the resolved, merged result for the repo you're in.
 1. The packaged built-in default (`assets/defaults/spf.config.yaml` inside
    the installed CLI).
 2. `.spf/spf.config.yaml` in the target repo, if present — merged on top,
-   field by field (`env`/`defaults`/`observability`/`quality`/`watch`/`notifications`/`review`/`tiering`
+   field by field (`env`/`defaults`/`observability`/`quality`/`watch`/`notifications`/`review`/`tiering`/`sandbox`
    merge key-by-key — `notifications.channels` replaces wholesale, same as
-   `quality.checks` and `tiering.tiers`/`tiering.roles`; `agents` merges by
-   `name`: a matching name patches that entry, a new name appends).
+   `quality.checks`, `tiering.tiers`/`tiering.roles`, and `sandbox`'s own
+   nested blocks (`opensandbox`/`cloudflare`/`egress`/`transport`/
+   `credentials`); `agents` merges by `name`: a matching name patches that
+   entry, a new name appends).
 3. An explicit `--config <path>` replaces both — standalone, no built-in
    underneath it.
 
@@ -154,13 +156,15 @@ Full mechanism: the main README's "`spf watch`" section. Field reference:
 | `chain` | string | Which registered chain runs per claimed `<prefix>:ready` issue. Default `plan-build-test`. |
 | `base_branch` | string | Branch worktrees fork from and PRs target. Default `main`. |
 | `poll_ms` | int | Tick interval. Default `60000`. |
-| `concurrency` | int ≥1 | Max issues claimed and run at once, the build lane's own budget (independent of `refine.concurrency`). Default `2`. |
+| `concurrency` | int ≥1 | Max ISSUES claimed and run at once — not attempts; see `fanout.concurrency`. The build lane's own budget (independent of `refine.concurrency`). Default `2`. |
 | `chain_options` | map of string -> string | Options passed straight through to `chain` (and `refine.chain`) for every unattended dispatch — the same shape an interactive `spf <chain> --suite <name>` builds, e.g. `{suite: strict}` or `{agent: some-agent}`. Default `{}`. Only useful for a chain whose behavior actually reads the option (a step-derived chain's `--suite`; an imperative chain ignores an option it doesn't know about). |
 | `jira.base_url` / `jira.project_key` | string | Only consulted when `issue_provider: jira`. |
 | `jira.issue_types` | map: `epic`/`feature`/`story`/`bug`/`task` -> string | Only consulted when `issue_provider: jira` AND `refine.enabled`. What each `RefinedIssue.kind` creates as on Jira — defaults `epic`/`feature` → `Epic`, `story` → `Story`, `bug` → `Bug`, `task` → `Task`, overridable per kind. Validated against the real project by both `spf watch init` and `spf watch`'s own startup check. |
 | `refine.enabled` | bool | Turns on the second lane: decompose a `<prefix>:spec-ready` product spec into a feature/story-or-bug tree of real issues, instead of running `chain` against it directly (a spec isn't individually workable). Default `false` — off by default, so an existing `watch:` config is unaffected by upgrading. Needs `issue_provider: github` or `"jira"` — both implement issue authoring (create + link a hierarchy); any other value fails loudly at startup. |
 | `refine.chain` | string | Which registered chain runs per claimed spec. Default `refine`. |
 | `refine.concurrency` | int ≥1 | The refine lane's own budget, separate from `concurrency`. Default `1`. |
+| `fanout.n` | int, 1-8 | Best-of-N per claimed issue: run `n` sibling attempts of the same issue and let code pick a winner (`core/fanout.ts`'s `pickBest`, the same mechanism `spf fanout` uses standalone). Default `1` — single dispatch, byte-identical to `spf watch` before this key existed. `n > 1` requires `chain` to have a commit step (`spf watch` refuses to start otherwise — a chain with no commit step would have its N-1 losing attempts' uncommitted work destroyed by best-of-N's own cleanup). |
+| `fanout.concurrency` | int ≥1 | Attempts of ONE issue's fan-out IN FLIGHT at once — **not** `concurrency`, which counts issues. The two multiply: `concurrency: 2` × `fanout.concurrency: 2` is up to 4 chain runs in flight; `spf doctor`'s `watch.fanout` line prints the exact product. Does **not** bound worktrees on disk — a successful attempt's tree is kept until every sibling in its fan-out has settled, so disk peak is `concurrency × fanout.n`, not `concurrency × fanout.concurrency`. Default `2`. |
 
 ```yaml
 watch:
@@ -173,6 +177,9 @@ watch:
     enabled: true       # decompose spf:spec-ready specs into a feature/story tree
     chain: refine
     concurrency: 1
+  fanout:
+    n: 1                 # attempts per claimed issue. 1 = single dispatch (default) — no-op for the daemon
+    concurrency: 2        # attempts IN FLIGHT per issue — not watch.concurrency (issues in flight)
 ```
 
 Generated issues carry a second, independent label vocabulary —
@@ -413,6 +420,92 @@ dispatch:
   one), any degradation note, and — probed the same way `probeServedOllamaTags`
   does, fail-open — which `ollama/*` rungs are and aren't in `ollama list`.
 
+### `sandbox`
+
+Remote sandbox backends (SPF #15) — runs an agent's `bash`/`read`/`write`/
+`edit` tools inside an isolated remote container instead of the real working
+tree. **Absent, or `backend: local` (the default), is byte-identical to SPF
+before this feature existed**: every agent runs against the real working
+tree, exactly as today. Top-level, not nested under `defaults:` — same
+reasoning as `tiering` above (a stray copy onto `loadConfig`'s `defaults`
+back-fill loop would be silently *stripped*, not rejected). Nested blocks
+(`opensandbox`, `cloudflare`, `egress`, `transport`, `credentials`) are a
+**whole-object replace** on override, same rule as `observability.otel` — a
+half-merged `bridge_url`/`api_token_env` pair would authenticate to the
+wrong control plane; `sandbox`'s own scalar keys still merge key-by-key
+around them.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `backend` | `local` \| `opensandbox` \| `cloudflare` | Default `local`. Repo-wide default; an agent's own `sandbox:` field can override it. |
+| `scope` | `agent` \| `run` | Default `agent` — **the default because it is the only scope under which per-agent `env_allowlist` is honored by construction.** One sandbox per `(run, agent)`, created with exactly that agent's resolved env. `run` — one sandbox for the whole run (cheaper: one create, one seed, one `setup`), admitted only when every agent the chain dispatches resolves to the SAME backend and the SAME resolved env key set — `spf validate`/`spf doctor` hard-reject `scope: run` otherwise, naming the agents and keys that differ. |
+| `workspace_dir` | absolute path (in-sandbox) | Default `/workspace` — the agent's cwd inside the sandbox. |
+| `handoff_dir` | absolute path (in-sandbox) | Default `/spf/handoff` — the **root** of the handoff plane (session artifacts, `context_handoff_dir`'s remote counterpart). The per-run directory a rendered prompt actually sees is derived from it as `<handoff_dir>/sessions/<adw_id>/context_handoff`, mirroring the host's own `context_handoff_dir` shape — this is not cosmetic: the shipped `planner`/`documenter` prompts parse `<adw_id>` out of that exact shape to name `specs/<adw_id>_<slug>.md`/`app_docs/<adw_id>_<slug>.md`. **MUST NOT be under `workspace_dir`** — `validate()` rejects it if it is: nested, it would ride the extract's `git add -A` onto the host at a path `spf init`'s `.gitignore` entries don't cover, and `permissions.enforce` kills the run on a `protected_files` breach. |
+| `scratch_dir` | absolute path (in-sandbox) | Default `/spf/tmp` — the transport's OWN scratch plane (the seed archive, the in-flight patches). Same "not under `workspace_dir`" rule, same reason, same enforcement as `handoff_dir`; also must not equal `handoff_dir`. |
+| `image` | string | **`opensandbox` only. No default** — `validate()`/`spf doctor` reject an empty `image` when the resolved backend is `opensandbox`, naming the three required binaries. MUST contain `git`, `tar`, and `base64`: the workspace transport shells out to all three to keep the sandbox's tree byte-identical to the host's. A `git`-less base (`python:*-slim`, bare `alpine`) fails the mandatory create-time preflight unless `setup` installs `git` first. Meaningless (and not required) on `cloudflare`. |
+| `setup` | array of strings | Default `[]`. Shell commands run **once** per sandbox, right after seeding — e.g. `["npm ci --omit=dev"]`. |
+| `request_timeout_seconds` | number | Default `960`. The **client-side** HTTP timeout on control-plane calls (create/renew/kill/file ops) — raised well above the SDK's own default because a first-run image pull can take a while. **Not** the bound on a long agent command: `exec` streams, so a caller-supplied timeout is honored unclamped (see `exec_timeout_seconds`). Must stay `>= exec_timeout_seconds`. |
+| `lifetime_seconds` | number | Default `3600`. Provider-side expiry, renewed while a lease stays live — the teardown backstop that survives a `SIGKILL`ed `spf`. |
+| `max_total_lifetime_seconds` | number | Default `21600`. A hard ceiling from creation; renewal refuses past it rather than letting a long-lived `spf watch` daemon renew one lease forever. |
+| `exec_timeout_seconds` | number | Default `900`. The **default** per-command deadline, used only when the model's own tool call supplies none. **Not a ceiling** — a caller-supplied timeout (the model's own `timeout` argument to `bash`) passes through unmodified, exactly as `backend: local` behaves today; there is no clamp. |
+| `env_allowlist` | array of strings | Default `[]` — **deliberately empty**, unlike `backend: local`, which passes the whole operator environment through today. A secret going into a remote container is a change of kind, not degree. The set that actually reaches a given agent's container is this list **intersected with that agent's own `env_allowlist`** (unset = no further narrowing) — per-agent, which is exactly why `scope: agent` is the default. `spf doctor` prints the resulting key **names**, never values, one line per agent. |
+| `credentials.broker` | `static` | Default, and the only **registered** value in this release — plain env injection at create time, nothing really revocable yet (`revoke()` just clears SPF's own in-memory copy). An unrecognized name is a hard `validate()` failure naming the key, never a silent fallback to `static`. `spf doctor` prints the resulting grant's own honest one-liner per agent — key **names** only, never values. |
+| `egress.default` / `egress.allow` | `deny`\|`allow` / array of hostnames | Default `deny` / `[]`. Repo-wide network egress policy for a remote sandbox. |
+| `transport.max_patch_bytes` / `.max_seed_bytes` / `.max_mirror_bytes` | number | Defaults `8388608` (8 MiB) / `134217728` (128 MiB) / `4194304` (4 MiB, **each direction**, per file). Exceeding any of them **fails the phase**; none of them ever silently truncate. |
+| `transport.mirror` | array of repo-relative paths | Default `[]`. Extra paths to sync out of the sandbox that git cannot carry (gitignored build artifacts you still want back on the host). |
+| `fanout` | `worktree` \| `sandbox` | Default `worktree`. `sandbox` fans out **through** sandboxes too: each `spf fanout` attempt gets its own sandbox lease(s), keyed on that attempt's own derived `<base>-<i>` adw_id — never a session id, never shared across attempts. The local worktree and branch stay the record of truth either way; `spf fanout`'s output adds one line noting where the attempts ran (`attempts ran in <backend> sandboxes; branch is local`). See `sandbox.scope` above for the per-attempt sandbox count. |
+| `opensandbox.base_url` | string | Default `http://127.0.0.1:8090`. |
+| `opensandbox.api_key_env` | string | Default `OPENSANDBOX_API_KEY` — an env **key name**, never the key itself, same spelling as `GITHUB_TOKEN`. |
+| `opensandbox.use_server_proxy` | bool | Default `false`. |
+| `opensandbox.metadata_prefix` | string | Default `spf`. Best-effort create-time labelling only — the teardown sweep relies on SPF's own host-side lease record, not on reading this back. |
+| `cloudflare.bridge_url` | string | Default `""`. The base URL of a deployed `@cloudflare/sandbox` bridge — **required** when the resolved backend is `cloudflare` (`validate()`/`spf doctor` reject an empty value). SPF is a Node CLI, not a Worker, so it talks to the bridge's HTTP API rather than a `getSandbox()` binding. |
+| `cloudflare.api_token_env` | string | Default `CLOUDFLARE_API_TOKEN` — an env **key name**, never the key itself. |
+| `cloudflare.sandbox_name` | string | Default `""` (derives a stable name from the lease key instead). Optional stable name for the bridge-side sandbox. |
+
+```yaml
+sandbox:
+  backend: opensandbox
+  image: ghcr.io/you/spf-sandbox:debian-git   # must contain git + tar + base64
+  env_allowlist: ["GH_TOKEN"]
+  egress:
+    default: deny
+    allow: ["github.com", "registry.npmjs.org"]
+  opensandbox:
+    base_url: http://127.0.0.1:8090
+
+agents:
+  - name: builder
+    env_allowlist: ["GH_TOKEN"]   # this agent's own narrowing — see the table above
+  - name: reviewer
+    sandbox: local                # force this one agent back to the real working tree
+```
+
+**Env posture, stated plainly.** `backend: local` today hands an agent's
+subprocess the *entire* operator environment. A remote backend does the
+opposite by design: nothing crosses unless it is named in **both**
+`sandbox.env_allowlist` and (if set) that agent's own `env_allowlist`. This
+is why `scope: agent` is the default rather than `scope: run` — a
+container's process environment is fixed once, at creation, and there is no
+verb to change it afterward, so two agents with different allowlists cannot
+safely share one container.
+
+**`spf doctor`**, gated on the **resolved backend, per check** — not a
+coarse "not local": checks that only make sense for `opensandbox` (SDK
+presence, control-plane reachability, the `[docker].host_ip` gotcha, image
+pre-pull timing) fire only when some agent resolves to `opensandbox`;
+`cloudflare`'s config/bridge-reachability checks fire only when some agent
+resolves to `cloudflare` — a repo running only `cloudflare` never fails
+doctor over a missing OpenSandbox SDK it will never load. Backend-agnostic
+checks (the resolved sandbox count per chain, per-agent env injection
+posture, egress policy, live in-process leases, the `claude_code` x remote
+rejection, `image`/handoff-scratch-placement/`scope: run`/timeout-relation
+roster-wide static checks, a `.gitmodules` warning) run whenever any agent
+resolves to a non-local backend, regardless of which one.
+
+**Submodules are out of scope for this release** — the transport seeds,
+syncs, and extracts the superproject only; `spf doctor` warns (never fails)
+when `.gitmodules` is present.
+
 ### `agents[]`
 
 | Field | Required | Meaning |
@@ -424,6 +517,7 @@ dispatch:
 | `tools` | no | Allowlist. Omitting it means all tools usable. A capability list, not a boundary — see `writes`. |
 | `writes` | no | What this agent may modify **in the repo**, enforced after every call. `undefined`/`null` = unrestricted (still barred from `protected_files`); `[]` = no repo writes; a list = only those paths (trailing `/` = directory prefix, `*` = one path segment, `**` = crosses segments, anything else = exact path). |
 | `env_allowlist` | no | Opt-in filter on the environment handed to this agent's subprocess/sandbox. `undefined` (default) = the full operator environment, unchanged. A list = only those keys, plus the baseline (`PATH`, `HOME`, `USER`, `LANG`, `TERM`, `TMPDIR`) either backend keeps regardless. |
+| `sandbox` | no | Per-agent backend override — see `sandbox` below. `undefined`/`null` = inherit `sandbox.backend`; `"local"` = force local for this agent regardless of the repo-wide setting; a backend name = use that backend for this agent only. A bare name, never a nested block — everything else (`image`, `egress`, `transport`, credentials *policy*) stays repo-wide. |
 
 Output types are deliberately absent from config: an entry defines who an
 agent *is*; the call site defines how it's *used*.

package/dist/chains/index.d.ts

@@ -55,6 +55,8 @@ export interface ChainDefinition {
      */
     source?: string;
 }
+/** Chains eligible to fan out: their derived phase string must show at least one commit step. */
+export declare function hasCommitStep(phases: string): boolean;
 /**
  * Build a step-based ChainDefinition, deriving phases/requiredAgents/
  * requiredSuites from its steps.

package/dist/chains/index.js

@@ -2,6 +2,10 @@ import * as steps from "./steps.js";
 import * as simpleSdlc from "./simple_sdlc.js";
 import * as otel from "../core/otel.js";
 import * as session from "../core/session.js";
+/** Chains eligible to fan out: their derived phase string must show at least one commit step. */
+export function hasCommitStep(phases) {
+    return phases.includes("git(commit");
+}
 /**
  * Build a step-based ChainDefinition, deriving phases/requiredAgents/
  * requiredSuites from its steps.