dorfl 0.7.0 → 0.8.0

package/dist/advance-drivers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"advance-drivers.d.ts","sourceRoot":"","sources":["../src/advance-drivers.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,MAAM,cAAc,CAAC;AAOtB,OAAO,EAAa,KAAK,kBAAkB,EAAC,MAAM,kBAAkB,CAAC;AAQrE,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,sBAAsB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,6EAA6E;AAC7E,MAAM,MAAM,iBAAiB,GAAG,CAC/B,OAAO,EAAE,kBAAkB,KACvB,OAAO,CAAC,aAAa,CAAC,CAAC;AAE5B,yEAAyE;AACzE,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,kBAAkB,CAAC;CAC1B;AAED,sEAAsE;AACtE,KAAK,oBAAoB,GAAG,cAAc,CAAC;AAE3C,MAAM,WAAW,0BAA2B,SAAQ,oBAAoB;IACvE;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,GAAG,CAAC,EAAE,iBAAiB,CAAC;IACxB,qFAAqF;IACrF,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IAClC,kEAAkE;IAClE,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;CAChB;AAUD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACvC,OAAO,EAAE,0BAA0B,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAmF7B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,0BAA0B,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAU7B;AAqCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,iCAAiC,CACtD,OAAO,EAAE,kBAAkB,EAC3B,GAAG,EAAE,iBAAiB,GACpB,OAAO,CAAC,aAAa,CAAC,CAqBxB;AA+CD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAIhE;AAED,YAAY,EAAC,cAAc,EAAC,CAAC"}
+{"version":3,"file":"advance-drivers.d.ts","sourceRoot":"","sources":["../src/advance-drivers.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,MAAM,cAAc,CAAC;AAOtB,OAAO,EAAa,KAAK,kBAAkB,EAAC,MAAM,kBAAkB,CAAC;AAQrE,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,sBAAsB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,6EAA6E;AAC7E,MAAM,MAAM,iBAAiB,GAAG,CAC/B,OAAO,EAAE,kBAAkB,KACvB,OAAO,CAAC,aAAa,CAAC,CAAC;AAE5B,yEAAyE;AACzE,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,kBAAkB,CAAC;CAC1B;AAED,sEAAsE;AACtE,KAAK,oBAAoB,GAAG,cAAc,CAAC;AAE3C,MAAM,WAAW,0BAA2B,SAAQ,oBAAoB;IACvE;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,GAAG,CAAC,EAAE,iBAAiB,CAAC;IACxB,qFAAqF;IACrF,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IAClC,kEAAkE;IAClE,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;CAChB;AAUD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACvC,OAAO,EAAE,0BAA0B,GACjC,OAAO,CAAC,kBAAkB,CAAC,CA4F7B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,0BAA0B,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAU7B;AAqCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,iCAAiC,CACtD,OAAO,EAAE,kBAAkB,EAC3B,GAAG,EAAE,iBAAiB,GACpB,OAAO,CAAC,aAAa,CAAC,CAqBxB;AA+CD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAIhE;AAED,YAAY,EAAC,cAAc,EAAC,CAAC"}

package/dist/advance-drivers.js

@@ -1,7 +1,7 @@
 import { performAdvance, } from './advance.js';
 import { pushTreelessResult, TREELESS_RUNGS, } from './advance-treeless-publish.js';
 import { scanRepoPaths } from './scan.js';
-import { heldTaskSlugs } from './item-lock.js';
+import { heldTaskSlugs, heldSpecSlugs } from './item-lock.js';
 import { ledgerRead } from './ledger-read.js';
 import { selectPrioritised, taskableSpecs, } from './select-priority.js';
 import { gatherLifecycleInPlace } from './lifecycle-gather.js';
@@ -41,6 +41,13 @@ export async function performAdvanceAuto(options) {
     // runs. `heldTaskSlugs` is the GRACEFUL variant (empty set on any read fault):
     // the follow-on claim CAS is still the load-bearing safety net locally.
     const heldSlugs = await heldTaskSlugs(cwd, options.arbiter);
+    // The held-SPEC set (fix
+    // `propose-tasking-releases-lock-so-spec-is-retasked-and-pr-force-pushed-every-tick`):
+    // a spec whose `spec-<slug>` lock is held has an in-flight tasking PR (propose keeps
+    // the lock across the open PR), so it must NOT be re-selected into the task rung.
+    // GRACEFUL variant (empty on read fault) — the tasking-lock CAS is the local safety
+    // net, matching `heldTaskSlugs` above.
+    const heldSpecs = await heldSpecSlugs(cwd, options.arbiter);
     // Pool 1 — eligible TASKS via the EXISTING scan/select path. `scoreItems`
     // inside `scanRepoPaths` gates eligibility on `autoBuild` (the build gate), so
     // with `autoBuild` off NO task is selected — the build rung is never reached
@@ -50,7 +57,9 @@ export async function performAdvanceAuto(options) {
     // `autoTask`). With `autoTask` off NO spec is selected — the task rung is
     // never reached by the bare/`-n` selection.
     const pool = read.resolveSpecPool({ repoPath: cwd });
-    const specCandidates = pool.specs.map((spec) => ({
+    const specCandidates = pool.specs
+        .filter((spec) => !heldSpecs.has(spec.slug))
+        .map((spec) => ({
         repoPath: cwd,
         slug: spec.slug,
         humanOnly: spec.humanOnly,

package/dist/advance-drivers.js.map

@@ -1 +1 @@
-{"version":3,"file":"advance-drivers.js","sourceRoot":"","sources":["../src/advance-drivers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"advance-drivers.js","sourceRoot":"","sources":["../src/advance-drivers.ts"],"names":[],"mappings":"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"}

package/dist/bootstrap-forward.d.ts

@@ -0,0 +1,224 @@
+/**
+ * The bootstrap self-forward (spec `dorfl-self-version-pinning-and-bootstrap-forward`
+ * §2/§4; task `dorfl-bootstrap-self-forward`, stories 1/4/5).
+ *
+ * The globally-installed `dorfl` is a thin BOOTSTRAP. On startup, BEFORE any
+ * command dispatch, it reads the nearest repo `dorfl.json`; if that repo declares
+ * a `dorflCmd` (and we are not already the forwarded process), it `exec`s that
+ * command with the ORIGINAL argv + env inherited, after a one-line STDERR notice,
+ * and returns the child's exit code (transparent passthrough).
+ *
+ * This module is the INJECTABLE seam: {@link decideForward} makes the pure
+ * decision (run-self / forward / error / opt-out) from argv + env + a config
+ * reader, and {@link performForward} does the exec through an injected spawn
+ * function — so the whole path is unit-testable WITHOUT re-execing a real second
+ * dorfl or hitting the network (mirroring how git/agent seams are injected in
+ * tests). {@link maybeForward} wires the two for the CLI entry point.
+ *
+ * Load-bearing safety fact (spec §2, task): the forward decision fires ONCE, at
+ * bare-`dorfl` startup, in the CHECKOUT ROOT — it is NOT recursive. The gate
+ * worktree that runs `prepare`/`verify` is created + prepared by the
+ * ALREADY-RUNNING dorfl, which runs the repo's commands via
+ * `spawn('bash', ['-c', cmd], {cwd: worktreeDir})` (`prepare.ts`/`verify.ts`) —
+ * it never launches a new `dorfl`, so a fresh worktree's empty `node_modules`
+ * never re-triggers the forward. Therefore a declared-but-ABSENT `dorflCmd` at
+ * the top level is almost always a MISCONFIGURATION (the repo's install did not
+ * run), and we FAIL LOUD (decision 2026-07-21, option B) rather than silently
+ * degrade to the global and run the WRONG version.
+ */
+/**
+ * The env marker set on the FORWARDED child so it does not forward AGAIN forever
+ * (loop-safe). The forwarded dorfl reads the SAME `dorfl.json` (same `dorflCmd`);
+ * seeing this marker it runs in-process instead of re-execing. `DORFL_` prefixed
+ * from the single brand identity so a rename flips it in lockstep.
+ */
+export declare const FORWARDED_ENV_MARKER: string;
+/**
+ * The opt-out env var (spec §4). `DORFL_NO_FORWARD=1` (or any truthy value)
+ * DISABLES forwarding AND suppresses the notice — the bootstrap/global runs
+ * as-is, so a user can always reach the bootstrap dorfl directly.
+ */
+export declare const NO_FORWARD_ENV: string;
+/**
+ * The opt-out CLI flag (spec §4). `--no-forward` DISABLES forwarding AND
+ * suppresses the notice, exactly like {@link NO_FORWARD_ENV}. It is honoured
+ * BEFORE command dispatch and STRIPPED from the argv commander parses (commander
+ * never sees it — it is a bootstrap-level flag, not a per-command option).
+ */
+export declare const NO_FORWARD_FLAG = "--no-forward";
+/** The pure forward DECISION — what the bootstrap should do at startup. */
+export type ForwardDecision = {
+    kind: 'run-self';
+    reason: 'no-cmd' | 'already-forwarded' | 'opted-out';
+} | {
+    kind: 'forward';
+    cmd: string;
+    configPath: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+/**
+ * Read the nearest repo's declared `dorflCmd` for `cwd`. Returns the resolved
+ * command (trimmed / empty⇒undefined via the config layer) and the `dorfl.json`
+ * path it was read from. A missing/config-less repo ⇒ `{cmd: undefined}`. The
+ * default reader; tests inject a stub instead of touching the filesystem.
+ */
+export interface RepoCmdReader {
+    (cwd: string): {
+        cmd: string | undefined;
+        configPath: string;
+    };
+}
+/** The default {@link RepoCmdReader}: read the cwd's `dorfl.json` `dorflCmd`. */
+export declare function defaultRepoCmdReader(cwd: string): {
+    cmd: string | undefined;
+    configPath: string;
+};
+/**
+ * True iff the ORIGINAL argv carries the {@link NO_FORWARD_FLAG} opt-out. Read
+ * from raw argv BEFORE commander parses (commander never sees this bootstrap
+ * flag). Only the exact `--no-forward` token counts.
+ */
+export declare function argvHasNoForward(argv: readonly string[]): boolean;
+/** True iff the env carries a truthy {@link NO_FORWARD_ENV} opt-out. */
+export declare function envHasNoForward(env: NodeJS.ProcessEnv): boolean;
+/** True iff the env carries the {@link FORWARDED_ENV_MARKER} (we ARE the child). */
+export declare function envIsForwarded(env: NodeJS.ProcessEnv): boolean;
+/**
+ * Return `argv` with EVERY {@link NO_FORWARD_FLAG} token removed, so commander
+ * (which does not declare `--no-forward` as an option) never sees it. Preserves
+ * order + all other tokens. Used to hand a clean argv to the in-process run when
+ * the opt-out is set.
+ */
+export declare function stripNoForwardFlag(argv: readonly string[]): string[];
+/**
+ * The PURE forward decision (no I/O beyond the injected `readRepoCmd`). Given the
+ * original argv + env + cwd, decide whether the bootstrap should run itself,
+ * forward to a `dorflCmd`, or (a declared-but-unusable command) surface an error.
+ * The forward is fired ONCE here at startup; the returned decision is acted on by
+ * {@link performForward}.
+ *
+ * Order of precedence:
+ *   1. OPT-OUT (`--no-forward` OR `DORFL_NO_FORWARD`) ⇒ run-self, silent.
+ *   2. ALREADY-FORWARDED (the child's env marker) ⇒ run-self, silent (loop-safe).
+ *   3. NO `dorflCmd` declared ⇒ run-self (onboarding-safe; never chicken-and-egg).
+ *   4. A `dorflCmd` is declared ⇒ forward to it.
+ *
+ * NOTE: this decision never itself resolves whether the target BINARY exists —
+ * that is the exec's job ({@link performForward}), which FAILS LOUD on a spawn
+ * error (the absent / present-but-broken pin). Keeping the decision pure lets a
+ * test drive every branch without a filesystem probe.
+ */
+export declare function decideForward(options: {
+    argv: readonly string[];
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    readRepoCmd: RepoCmdReader;
+}): ForwardDecision;
+/**
+ * The injected exec seam. Runs `cmd` (through the shell so `npx dorfl@x` /
+ * `mise exec dorfl@x --` / `node_modules/.bin/dorfl` all behave as written) with
+ * the given argv appended, the given env (which carries the
+ * {@link FORWARDED_ENV_MARKER} so the child does not forward again), inheriting
+ * stdio. Returns the child's exit code, or a spawn ERROR (target absent / not
+ * executable) which {@link performForward} turns into the loud, actionable error.
+ *
+ * Tests inject a stub that never touches a real process; the default
+ * ({@link defaultForwardSpawn}) uses `spawnSync('bash', ['-c', ...])`.
+ */
+export interface ForwardSpawn {
+    (options: {
+        cmd: string;
+        forwardedArgs: readonly string[];
+        env: NodeJS.ProcessEnv;
+    }): ForwardSpawnResult;
+}
+/** The result of the injected {@link ForwardSpawn}. */
+export type ForwardSpawnResult = {
+    kind: 'exited';
+    code: number;
+} | {
+    kind: 'spawn-error';
+    message: string;
+};
+/**
+ * The default {@link ForwardSpawn}: run `<cmd> <forwardedArgs...>` via
+ * `bash -c "<cmd> \"$@\"" bash <args...>` with inherited stdio, returning the
+ * child's exit code. A spawn error (`error` set — e.g. bash missing) or a shell
+ * "command not found" (exit 127) is reported as `spawn-error` so an absent /
+ * broken `dorflCmd` fails loud rather than silently degrading.
+ */
+export declare function defaultForwardSpawn(options: {
+    cmd: string;
+    forwardedArgs: readonly string[];
+    env: NodeJS.ProcessEnv;
+}): ForwardSpawnResult;
+/** The one-line STDERR notice announcing a forward (never stdout — must not
+ * corrupt `--json`). Shape per spec §4. */
+export declare function forwardNotice(cmd: string, configPath: string): string;
+/**
+ * The loud, actionable error for a declared-but-unusable `dorflCmd` (absent
+ * target, or a present binary that spawn-errors). Names the `dorflCmd` value +
+ * the `dorfl.json` path + the FIX (run the dependency install first) + the
+ * `--no-forward` / `DORFL_NO_FORWARD` bypass — so it is never a silent degrade to
+ * the global (which would run the WRONG version and defeat the pin).
+ */
+export declare function forwardFailureMessage(options: {
+    cmd: string;
+    configPath: string;
+    detail: string;
+}): string;
+/** What {@link performForward} tells the caller to do next. */
+export type ForwardOutcome = 
+/** A forward happened; exit the process with this code (transparent passthrough). */
+{
+    kind: 'forwarded';
+    exitCode: number;
+}
+/** The forward could not run; print `message` to stderr and exit non-zero. */
+ | {
+    kind: 'error';
+    message: string;
+    exitCode: number;
+}
+/** No forward — the caller runs the bootstrap itself with `argv`. */
+ | {
+    kind: 'run-self';
+    argv: string[];
+};
+/**
+ * Act on a {@link ForwardDecision}: for a `forward`, print the notice to STDERR,
+ * spawn the child (via the injected `spawn`) with the {@link FORWARDED_ENV_MARKER}
+ * set + the ORIGINAL argv appended, and return the child's exit code — or, on a
+ * spawn error, the loud actionable failure. For `run-self`, return the (opt-out-
+ * stripped) argv for the caller to parse in-process.
+ *
+ * `argv` here is the FULL process argv (`[node, script, ...userArgs]`); only the
+ * USER args (index 2+) are forwarded to the child, since the child provides its
+ * own node + script.
+ */
+export declare function performForward(options: {
+    decision: ForwardDecision;
+    argv: readonly string[];
+    env: NodeJS.ProcessEnv;
+    spawn: ForwardSpawn;
+    writeNotice: (line: string) => void;
+}): ForwardOutcome;
+/**
+ * The CLI-entry wiring: decide + (if forwarding) exec, all through the default
+ * seams. Returns the {@link ForwardOutcome} the entry point acts on — a
+ * `forwarded`/`error` outcome means "exit with this code now"; a `run-self`
+ * outcome means "continue into commander with this argv". Kept thin so the entry
+ * point stays a two-line hook; the testable logic lives in {@link decideForward}
+ * + {@link performForward}.
+ */
+export declare function maybeForward(options: {
+    argv?: readonly string[];
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    readRepoCmd?: RepoCmdReader;
+    spawn?: ForwardSpawn;
+    writeNotice?: (line: string) => void;
+}): ForwardOutcome;
+//# sourceMappingURL=bootstrap-forward.d.ts.map

package/dist/bootstrap-forward.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-forward.d.ts","sourceRoot":"","sources":["../src/bootstrap-forward.ts"],"names":[],"mappings":"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"}

package/dist/bootstrap-forward.js

@@ -0,0 +1,247 @@
+import { spawnSync } from 'node:child_process';
+import { brand } from './brand.js';
+import { resolveRepoConfigPath, loadRepoConfig, REPO_CONFIG_FILENAME, } from './repo-config.js';
+/**
+ * The bootstrap self-forward (spec `dorfl-self-version-pinning-and-bootstrap-forward`
+ * §2/§4; task `dorfl-bootstrap-self-forward`, stories 1/4/5).
+ *
+ * The globally-installed `dorfl` is a thin BOOTSTRAP. On startup, BEFORE any
+ * command dispatch, it reads the nearest repo `dorfl.json`; if that repo declares
+ * a `dorflCmd` (and we are not already the forwarded process), it `exec`s that
+ * command with the ORIGINAL argv + env inherited, after a one-line STDERR notice,
+ * and returns the child's exit code (transparent passthrough).
+ *
+ * This module is the INJECTABLE seam: {@link decideForward} makes the pure
+ * decision (run-self / forward / error / opt-out) from argv + env + a config
+ * reader, and {@link performForward} does the exec through an injected spawn
+ * function — so the whole path is unit-testable WITHOUT re-execing a real second
+ * dorfl or hitting the network (mirroring how git/agent seams are injected in
+ * tests). {@link maybeForward} wires the two for the CLI entry point.
+ *
+ * Load-bearing safety fact (spec §2, task): the forward decision fires ONCE, at
+ * bare-`dorfl` startup, in the CHECKOUT ROOT — it is NOT recursive. The gate
+ * worktree that runs `prepare`/`verify` is created + prepared by the
+ * ALREADY-RUNNING dorfl, which runs the repo's commands via
+ * `spawn('bash', ['-c', cmd], {cwd: worktreeDir})` (`prepare.ts`/`verify.ts`) —
+ * it never launches a new `dorfl`, so a fresh worktree's empty `node_modules`
+ * never re-triggers the forward. Therefore a declared-but-ABSENT `dorflCmd` at
+ * the top level is almost always a MISCONFIGURATION (the repo's install did not
+ * run), and we FAIL LOUD (decision 2026-07-21, option B) rather than silently
+ * degrade to the global and run the WRONG version.
+ */
+/**
+ * The env marker set on the FORWARDED child so it does not forward AGAIN forever
+ * (loop-safe). The forwarded dorfl reads the SAME `dorfl.json` (same `dorflCmd`);
+ * seeing this marker it runs in-process instead of re-execing. `DORFL_` prefixed
+ * from the single brand identity so a rename flips it in lockstep.
+ */
+export const FORWARDED_ENV_MARKER = `${brand.envPrefix}FORWARDED`;
+/**
+ * The opt-out env var (spec §4). `DORFL_NO_FORWARD=1` (or any truthy value)
+ * DISABLES forwarding AND suppresses the notice — the bootstrap/global runs
+ * as-is, so a user can always reach the bootstrap dorfl directly.
+ */
+export const NO_FORWARD_ENV = `${brand.envPrefix}NO_FORWARD`;
+/**
+ * The opt-out CLI flag (spec §4). `--no-forward` DISABLES forwarding AND
+ * suppresses the notice, exactly like {@link NO_FORWARD_ENV}. It is honoured
+ * BEFORE command dispatch and STRIPPED from the argv commander parses (commander
+ * never sees it — it is a bootstrap-level flag, not a per-command option).
+ */
+export const NO_FORWARD_FLAG = '--no-forward';
+/** The default {@link RepoCmdReader}: read the cwd's `dorfl.json` `dorflCmd`. */
+export function defaultRepoCmdReader(cwd) {
+    const configPath = resolveRepoConfigPath(cwd);
+    const loaded = loadRepoConfig(cwd);
+    // `loadRepoConfig` carries `dorflCmd` verbatim from the file; the config-layer
+    // trim/empty⇒unset normalisation runs at full resolution, but for the bootstrap
+    // decision we only need the raw presence + trimmed value, so normalise here too.
+    const raw = loaded.config.dorflCmd;
+    const cmd = typeof raw === 'string' && raw.trim() !== '' ? raw.trim() : undefined;
+    return { cmd, configPath: loaded.path ?? configPath };
+}
+/**
+ * True iff the ORIGINAL argv carries the {@link NO_FORWARD_FLAG} opt-out. Read
+ * from raw argv BEFORE commander parses (commander never sees this bootstrap
+ * flag). Only the exact `--no-forward` token counts.
+ */
+export function argvHasNoForward(argv) {
+    return argv.includes(NO_FORWARD_FLAG);
+}
+/** True iff the env carries a truthy {@link NO_FORWARD_ENV} opt-out. */
+export function envHasNoForward(env) {
+    const value = env[NO_FORWARD_ENV];
+    return value !== undefined && value !== '' && value !== '0';
+}
+/** True iff the env carries the {@link FORWARDED_ENV_MARKER} (we ARE the child). */
+export function envIsForwarded(env) {
+    const value = env[FORWARDED_ENV_MARKER];
+    return value !== undefined && value !== '' && value !== '0';
+}
+/**
+ * Return `argv` with EVERY {@link NO_FORWARD_FLAG} token removed, so commander
+ * (which does not declare `--no-forward` as an option) never sees it. Preserves
+ * order + all other tokens. Used to hand a clean argv to the in-process run when
+ * the opt-out is set.
+ */
+export function stripNoForwardFlag(argv) {
+    return argv.filter((token) => token !== NO_FORWARD_FLAG);
+}
+/**
+ * The PURE forward decision (no I/O beyond the injected `readRepoCmd`). Given the
+ * original argv + env + cwd, decide whether the bootstrap should run itself,
+ * forward to a `dorflCmd`, or (a declared-but-unusable command) surface an error.
+ * The forward is fired ONCE here at startup; the returned decision is acted on by
+ * {@link performForward}.
+ *
+ * Order of precedence:
+ *   1. OPT-OUT (`--no-forward` OR `DORFL_NO_FORWARD`) ⇒ run-self, silent.
+ *   2. ALREADY-FORWARDED (the child's env marker) ⇒ run-self, silent (loop-safe).
+ *   3. NO `dorflCmd` declared ⇒ run-self (onboarding-safe; never chicken-and-egg).
+ *   4. A `dorflCmd` is declared ⇒ forward to it.
+ *
+ * NOTE: this decision never itself resolves whether the target BINARY exists —
+ * that is the exec's job ({@link performForward}), which FAILS LOUD on a spawn
+ * error (the absent / present-but-broken pin). Keeping the decision pure lets a
+ * test drive every branch without a filesystem probe.
+ */
+export function decideForward(options) {
+    const { argv, env, cwd, readRepoCmd } = options;
+    if (argvHasNoForward(argv) || envHasNoForward(env)) {
+        return { kind: 'run-self', reason: 'opted-out' };
+    }
+    if (envIsForwarded(env)) {
+        return { kind: 'run-self', reason: 'already-forwarded' };
+    }
+    const { cmd, configPath } = readRepoCmd(cwd);
+    if (cmd === undefined) {
+        return { kind: 'run-self', reason: 'no-cmd' };
+    }
+    return { kind: 'forward', cmd, configPath };
+}
+/**
+ * The default {@link ForwardSpawn}: run `<cmd> <forwardedArgs...>` via
+ * `bash -c "<cmd> \"$@\"" bash <args...>` with inherited stdio, returning the
+ * child's exit code. A spawn error (`error` set — e.g. bash missing) or a shell
+ * "command not found" (exit 127) is reported as `spawn-error` so an absent /
+ * broken `dorflCmd` fails loud rather than silently degrading.
+ */
+export function defaultForwardSpawn(options) {
+    // `bash -c '<cmd> "$@"' bash <forwardedArgs...>` passes the ORIGINAL argv
+    // through as positional params (quoting-safe) AFTER the (possibly multi-token)
+    // dorflCmd — so `npx dorfl@x <args>` and `./bin/dorfl <args>` both work.
+    const result = spawnSync('bash', ['-c', `${options.cmd} "$@"`, 'bash', ...options.forwardedArgs], { env: options.env, stdio: 'inherit' });
+    if (result.error) {
+        return { kind: 'spawn-error', message: result.error.message };
+    }
+    // 127 is the shell's "command not found" — the ABSENT-target case (e.g.
+    // `node_modules/.bin/dorfl` before install). Surface it as a spawn error so it
+    // fails loud, NOT a silent passthrough of a misleading exit code.
+    if (result.status === 127) {
+        return { kind: 'spawn-error', message: `command not found: ${options.cmd}` };
+    }
+    if (result.signal) {
+        return {
+            kind: 'spawn-error',
+            message: `terminated by signal ${result.signal}`,
+        };
+    }
+    return { kind: 'exited', code: result.status ?? 1 };
+}
+/** The one-line STDERR notice announcing a forward (never stdout — must not
+ * corrupt `--json`). Shape per spec §4. */
+export function forwardNotice(cmd, configPath) {
+    return `${brand.bin}: forwarding to \`${cmd}\` (from ${configPath})`;
+}
+/**
+ * The loud, actionable error for a declared-but-unusable `dorflCmd` (absent
+ * target, or a present binary that spawn-errors). Names the `dorflCmd` value +
+ * the `dorfl.json` path + the FIX (run the dependency install first) + the
+ * `--no-forward` / `DORFL_NO_FORWARD` bypass — so it is never a silent degrade to
+ * the global (which would run the WRONG version and defeat the pin).
+ */
+export function forwardFailureMessage(options) {
+    const { cmd, configPath, detail } = options;
+    return (`${brand.bin}: could NOT run the repo-declared dorflCmd \`${cmd}\` ` +
+        `(from ${configPath}): ${detail}.\n` +
+        `This usually means the repo's dependencies are not installed yet ` +
+        `(e.g. \`${cmd}\` points at node_modules/.bin/dorfl before install). ` +
+        `Run the repo's dependency install first (e.g. \`pnpm install\`, or the ` +
+        `CI project-setup hook), then re-run.\n` +
+        `To bypass the forward and run the bootstrap ${brand.bin} directly, pass ` +
+        `${NO_FORWARD_FLAG} or set ${NO_FORWARD_ENV}=1 ` +
+        `(this runs whatever ${brand.bin} is on PATH — NOT the pinned version).`);
+}
+/**
+ * Act on a {@link ForwardDecision}: for a `forward`, print the notice to STDERR,
+ * spawn the child (via the injected `spawn`) with the {@link FORWARDED_ENV_MARKER}
+ * set + the ORIGINAL argv appended, and return the child's exit code — or, on a
+ * spawn error, the loud actionable failure. For `run-self`, return the (opt-out-
+ * stripped) argv for the caller to parse in-process.
+ *
+ * `argv` here is the FULL process argv (`[node, script, ...userArgs]`); only the
+ * USER args (index 2+) are forwarded to the child, since the child provides its
+ * own node + script.
+ */
+export function performForward(options) {
+    const { decision, argv, env, spawn, writeNotice } = options;
+    if (decision.kind === 'run-self') {
+        return { kind: 'run-self', argv: stripNoForwardFlag(argv) };
+    }
+    if (decision.kind === 'error') {
+        return { kind: 'error', message: decision.message, exitCode: 1 };
+    }
+    // A forward. The user args are everything after `[node, script]`.
+    const forwardedArgs = argv.slice(2);
+    writeNotice(forwardNotice(decision.cmd, decision.configPath));
+    const childEnv = { ...env, [FORWARDED_ENV_MARKER]: '1' };
+    const result = spawn({ cmd: decision.cmd, forwardedArgs, env: childEnv });
+    if (result.kind === 'spawn-error') {
+        return {
+            kind: 'error',
+            message: forwardFailureMessage({
+                cmd: decision.cmd,
+                configPath: decision.configPath,
+                detail: result.message,
+            }),
+            exitCode: 1,
+        };
+    }
+    return { kind: 'forwarded', exitCode: result.code };
+}
+/**
+ * The CLI-entry wiring: decide + (if forwarding) exec, all through the default
+ * seams. Returns the {@link ForwardOutcome} the entry point acts on — a
+ * `forwarded`/`error` outcome means "exit with this code now"; a `run-self`
+ * outcome means "continue into commander with this argv". Kept thin so the entry
+ * point stays a two-line hook; the testable logic lives in {@link decideForward}
+ * + {@link performForward}.
+ */
+export function maybeForward(options) {
+    const argv = options.argv ?? process.argv;
+    const env = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
+    const readRepoCmd = options.readRepoCmd ?? defaultRepoCmdReader;
+    const spawn = options.spawn ?? defaultForwardSpawn;
+    const writeNotice = options.writeNotice ??
+        ((line) => process.stderr.write(line + '\n'));
+    let decision;
+    try {
+        decision = decideForward({ argv, env, cwd, readRepoCmd });
+    }
+    catch (err) {
+        // A malformed `dorfl.json` (invalid JSON / non-string dorflCmd) surfaces as
+        // a loud error rather than a silent run-self, so a broken pin config is never
+        // masked. `REPO_CONFIG_FILENAME` names the file in the message.
+        return {
+            kind: 'error',
+            message: `${brand.bin}: could not read ${REPO_CONFIG_FILENAME} to decide the ` +
+                `bootstrap forward: ${err instanceof Error ? err.message : String(err)}. ` +
+                `Fix ${REPO_CONFIG_FILENAME}, or pass ${NO_FORWARD_FLAG} / set ` +
+                `${NO_FORWARD_ENV}=1 to run the bootstrap ${brand.bin} directly.`,
+            exitCode: 1,
+        };
+    }
+    return performForward({ decision, argv, env, spawn, writeNotice });
+}
+//# sourceMappingURL=bootstrap-forward.js.map

package/dist/bootstrap-forward.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-forward.js","sourceRoot":"","sources":["../src/bootstrap-forward.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -25,6 +25,15 @@ export declare function formatSkillsAddReport(result: InstallSkillsResult, local
  * so tests can build + introspect/parse the program WITHOUT triggering a real
  * argv parse + `process.exit` on import (the module-level bootstrap below only
  * fires when this file is the process entry point).
+ *
+ * BEFORE any command dispatch it runs the bootstrap SELF-FORWARD hook
+ * ({@link maybeForward}): if the nearest repo `dorfl.json` declares a `dorflCmd`
+ * (and we are not already the forwarded child / opted out), it execs that command
+ * with the ORIGINAL argv + env inherited and exits with the child's code
+ * (transparent passthrough). A declared-but-unusable `dorflCmd` FAILS LOUD. On
+ * the run-self branch (no `dorflCmd`, opted out, or the forwarded child) it parses
+ * the (opt-out-stripped) argv in-process, exactly as before. See
+ * `bootstrap-forward.ts` for the full model + the injectable seam.
  */
 export declare function runCli(argv?: string[]): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAC,OAAO,EAAS,MAAM,WAAW,CAAC;AAmH1C,OAAO,EAAiB,KAAK,YAAY,EAAC,MAAM,sBAAsB,CAAC;AAuCvE,OAAO,EAAgB,KAAK,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AA2xB5E;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,OAAO,GACb,MAAM,CAoCR;AA6RD,wBAAgB,YAAY,IAAI,OAAO,CA04GtC;AAaD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,OAAO,GACZ,MAAM,CAyBR;AA+FD;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAC,OAAO,EAAS,MAAM,WAAW,CAAC;AAmH1C,OAAO,EAAiB,KAAK,YAAY,EAAC,MAAM,sBAAsB,CAAC;AAwCvE,OAAO,EAAgB,KAAK,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AA2xB5E;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,OAAO,GACb,MAAM,CAoCR;AA6RD,wBAAgB,YAAY,IAAI,OAAO,CA04GtC;AAaD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,OAAO,GACZ,MAAM,CAyBR;AA+FD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBzE"}

package/dist/cli.js

@@ -60,6 +60,7 @@ import { dropSource } from './drop-source.js';
 import { arbiterStatus, DEFAULT_ARBITER_REMOTE } from './arbiter.js';
 import { resolveTaskOnlyArg, workBranchRef, SlugResolutionError, } from './slug-namespace.js';
 import { brand } from './brand.js';
+import { maybeForward } from './bootstrap-forward.js';
 import { installCI } from './install-ci.js';
 import { GitHubCIContext } from './install-ci-github.js';
 import { loadCapabilityRegistry } from './install-ci-core.js';
@@ -3485,11 +3486,30 @@ function promptMultiSelect(repos) {
  * so tests can build + introspect/parse the program WITHOUT triggering a real
  * argv parse + `process.exit` on import (the module-level bootstrap below only
  * fires when this file is the process entry point).
+ *
+ * BEFORE any command dispatch it runs the bootstrap SELF-FORWARD hook
+ * ({@link maybeForward}): if the nearest repo `dorfl.json` declares a `dorflCmd`
+ * (and we are not already the forwarded child / opted out), it execs that command
+ * with the ORIGINAL argv + env inherited and exits with the child's code
+ * (transparent passthrough). A declared-but-unusable `dorflCmd` FAILS LOUD. On
+ * the run-self branch (no `dorflCmd`, opted out, or the forwarded child) it parses
+ * the (opt-out-stripped) argv in-process, exactly as before. See
+ * `bootstrap-forward.ts` for the full model + the injectable seam.
  */
 export async function runCli(argv = process.argv) {
+    const outcome = maybeForward({ argv });
+    if (outcome.kind === 'forwarded') {
+        process.exit(outcome.exitCode);
+    }
+    if (outcome.kind === 'error') {
+        console.error(outcome.message);
+        process.exit(outcome.exitCode);
+    }
+    // run-self: parse the argv commander sees (with any `--no-forward` stripped,
+    // since commander does not declare that bootstrap-level flag).
     const program = buildProgram();
     try {
-        await program.parseAsync(argv);
+        await program.parseAsync(outcome.argv);
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));