dorfl 0.11.0 → 0.11.2

package/dist/arbiter-refs.d.ts

@@ -0,0 +1,139 @@
+/**
+ * **The ONE arbiter-ref refresh + authoritative-read seam** (observation
+ * `checkpoint-path-reports-its-own-write-as-absent`).
+ *
+ * Every "did my own write land?" / "is the branch on the arbiter?" question in
+ * the checkpoint + surface paths used to be answered the same wrong way: run a
+ * PLAIN `git fetch <arbiter>`, then `git rev-parse <arbiter>/<branch>` — i.e.
+ * read a REMOTE-TRACKING ref (`refs/remotes/<arbiter>/…`) and trust it. That is
+ * unsound in the configuration dorfl itself creates for `--isolated` runs, and
+ * it produced two field defects where dorfl reported its OWN successful write as
+ * absent:
+ *
+ *  1. A job worktree is `git worktree add`ed from the BARE HUB MIRROR
+ *     (`workspace.ts` `createJob` → `repo-mirror.ts` `ensureMirror`), whose
+ *     `origin` carries the MIRROR-style refspec `+refs/heads/*:refs/heads/*`.
+ *     So a plain fetch there writes `refs/heads/main`, and **never populates**
+ *     `refs/remotes/origin/main` at all. `rev-parse origin/main` then returns
+ *     whatever a PRIOR explicit-refspec fetch happened to leave behind — a value
+ *     that PREDATES the write being verified. A push that genuinely landed reads
+ *     back as "not our commit ⇒ rejected".
+ *  2. Worse, in that same worktree a plain `git fetch origin` **fails outright**
+ *     (`fatal: refusing to fetch into branch 'refs/heads/work/<slug>' checked out
+ *     at …`), because the mirror refspec's destination IS the branch the worktree
+ *     has checked out. So it refreshes NOTHING, and a follow-up
+ *     `rev-parse <arbiter>/work/<slug>` fails against a ref that never existed —
+ *     reported as "no work branch on <arbiter>" while the branch (and an hour of
+ *     agent work) sits on the arbiter.
+ *
+ * Both call sites now route through this module, which fixes the class rather
+ * than the two instances:
+ *
+ *   - {@link refreshArbiterRefs} prune-fetches with an EXPLICIT, per-branch
+ *     refspec into the `refs/remotes/<arbiter>/…` namespace the readers actually
+ *     read, tolerating the checked-out-branch refusal instead of being silently
+ *     defeated by it.
+ *   - {@link resolveArbiterBranch} answers the sha question from the ARBITER
+ *     ITSELF (`git ls-remote`), so no local ref-namespace/refspec accident can
+ *     make a landed write look absent. The local tracking ref is only a FALLBACK,
+ *     used when the arbiter cannot be reached at all.
+ *
+ * The `ls-remote`-is-authoritative stance is not new — it is the same one
+ * `continue-branch.ts` (`branchAheadOfArbiter`), `workspace.ts`, `integrator.ts`
+ * and `reap-branches.ts` already take for continue-detection and branch reaping.
+ * This module makes it the SHARED default for the post-write verification too,
+ * instead of each site re-deciding.
+ */
+/** How a {@link ResolvedArbiterBranch} sha was obtained — the read's PROVENANCE. */
+export type ArbiterRefAuthority = 
+/** Read from the arbiter itself (`git ls-remote`): AUTHORITATIVE. */
+'arbiter'
+/**
+ * The arbiter could not be reached (offline / broken remote), so the local
+ * remote-tracking ref was used. Best-effort: it may be stale, so a caller
+ * deciding "did MY write land?" must NOT treat a mismatch here as proof of
+ * a loss (see {@link ResolvedArbiterBranch.trustworthy}).
+ */
+ | 'local-fallback'
+/** Neither the arbiter nor any local ref has this branch. */
+ | 'absent';
+/** The resolved state of ONE branch on the arbiter (a single, coherent read). */
+export interface ResolvedArbiterBranch {
+    /** The unqualified branch name that was resolved (e.g. `main`, `work/task-x`). */
+    branch: string;
+    /** Its sha, or `undefined` when the branch exists nowhere we could look. */
+    sha?: string;
+    /** Where {@link sha} came from. */
+    authority: ArbiterRefAuthority;
+    /**
+     * True iff the arbiter answered (`authority` is `arbiter` or `absent` off a
+     * REACHABLE arbiter). When false the read is a stale-capable local fallback,
+     * so a mismatch proves nothing and callers must not report a loss from it.
+     */
+    trustworthy: boolean;
+    /** The `ls-remote` stderr when the arbiter could not be reached (diagnostics). */
+    unreachableDetail?: string;
+}
+/**
+ * PRUNE-FETCH the named arbiter branches into `refs/remotes/<arbiter>/<branch>`
+ * — the namespace every reader in this codebase actually reads — using an
+ * EXPLICIT per-branch refspec.
+ *
+ * Three properties matter, and all three are the reason this is not just
+ * `git fetch <arbiter>`:
+ *
+ *  - **Explicit refspec.** A bare-hub-mirror worktree's `origin` maps
+ *    `+refs/heads/*:refs/heads/*`, so a plain fetch never writes
+ *    `refs/remotes/<arbiter>/*`. Naming the destination makes the refresh work
+ *    identically in a normal clone AND in a mirror worktree.
+ *  - **`--prune`.** A branch DELETED on the arbiter (a `requeue --reset`, a
+ *    merge-reap, a cross-machine `gc`) must disappear from our view too;
+ *    otherwise a stale tracking ref answers a liveness question with a ghost.
+ *  - **Per-branch and SOFT.** Fetching branch-at-a-time means the one refspec
+ *    git refuses (the destination that is checked out in THIS worktree — see the
+ *    module doc) cannot abort the refresh of the others, which is exactly how the
+ *    single combined fetch silently refreshed nothing. Every failure is
+ *    tolerated and reported rather than thrown: this is a REFRESH, and the
+ *    authoritative answer comes from {@link resolveArbiterBranch} anyway.
+ *
+ * Returns the branches that could not be refreshed (for diagnostics only — a
+ * caller should not gate on it, because the authoritative read does not depend
+ * on the refresh succeeding).
+ */
+export declare function refreshArbiterRefs(params: {
+    cwd: string;
+    arbiter: string;
+    /** Unqualified branch names to refresh (e.g. `['main', 'work/task-x']`). */
+    branches: readonly string[];
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    failed: string[];
+}>;
+/**
+ * Resolve ONE branch's sha on the arbiter, ARBITER-AUTHORITATIVELY.
+ *
+ * `git ls-remote --heads <arbiter> <branch>` asks the arbiter directly, so the
+ * answer cannot be defeated by a local refspec/namespace accident — which is the
+ * whole point: this is the read a post-write verification uses to decide whether
+ * its OWN push landed, and that decision must never be made from a view that
+ * predates the push.
+ *
+ * Decision order:
+ *   - `ls-remote` exits 0 with a sha ⇒ `{sha, authority: 'arbiter'}` (trustworthy).
+ *   - `ls-remote` exits 0 with EMPTY output ⇒ the arbiter genuinely does not have
+ *     the branch ⇒ `{authority: 'absent'}` (trustworthy: a definite "no").
+ *   - `ls-remote` exits non-zero (unreachable / no such remote) ⇒ fall back to the
+ *     local `refs/remotes/<arbiter>/<branch>`, flagged `trustworthy: false` so a
+ *     caller cannot mistake a stale local read for proof of anything.
+ *
+ * Always call {@link refreshArbiterRefs} first when the caller ALSO needs the
+ * objects locally (a CAS base, a `merge-base` / `rev-list` comparison): a sha
+ * from `ls-remote` names a commit this repo may not have yet.
+ */
+export declare function resolveArbiterBranch(params: {
+    cwd: string;
+    arbiter: string;
+    branch: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<ResolvedArbiterBranch>;
+//# sourceMappingURL=arbiter-refs.d.ts.map

package/dist/arbiter-refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arbiter-refs.d.ts","sourceRoot":"","sources":["../src/arbiter-refs.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,oFAAoF;AACpF,MAAM,MAAM,mBAAmB;AAC9B,qEAAqE;AACnE,SAAS;AACX;;;;;GAKG;GACD,gBAAgB;AAClB,6DAA6D;GAC3D,QAAQ,CAAC;AAEZ,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACrC,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,SAAS,EAAE,mBAAmB,CAAC;IAC/B;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,kFAAkF;IAClF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB,GAAG,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAC,CAAC,CAqB9B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAsDjC"}

package/dist/arbiter-refs.js

@@ -0,0 +1,114 @@
+import { runAsync } from './git.js';
+/** The explicit refspec that maps an arbiter branch into the namespace we READ. */
+function trackingRefspec(arbiter, branch) {
+    return `+refs/heads/${branch}:refs/remotes/${arbiter}/${branch}`;
+}
+/**
+ * PRUNE-FETCH the named arbiter branches into `refs/remotes/<arbiter>/<branch>`
+ * — the namespace every reader in this codebase actually reads — using an
+ * EXPLICIT per-branch refspec.
+ *
+ * Three properties matter, and all three are the reason this is not just
+ * `git fetch <arbiter>`:
+ *
+ *  - **Explicit refspec.** A bare-hub-mirror worktree's `origin` maps
+ *    `+refs/heads/*:refs/heads/*`, so a plain fetch never writes
+ *    `refs/remotes/<arbiter>/*`. Naming the destination makes the refresh work
+ *    identically in a normal clone AND in a mirror worktree.
+ *  - **`--prune`.** A branch DELETED on the arbiter (a `requeue --reset`, a
+ *    merge-reap, a cross-machine `gc`) must disappear from our view too;
+ *    otherwise a stale tracking ref answers a liveness question with a ghost.
+ *  - **Per-branch and SOFT.** Fetching branch-at-a-time means the one refspec
+ *    git refuses (the destination that is checked out in THIS worktree — see the
+ *    module doc) cannot abort the refresh of the others, which is exactly how the
+ *    single combined fetch silently refreshed nothing. Every failure is
+ *    tolerated and reported rather than thrown: this is a REFRESH, and the
+ *    authoritative answer comes from {@link resolveArbiterBranch} anyway.
+ *
+ * Returns the branches that could not be refreshed (for diagnostics only — a
+ * caller should not gate on it, because the authoritative read does not depend
+ * on the refresh succeeding).
+ */
+export async function refreshArbiterRefs(params) {
+    const { cwd, arbiter, branches, env } = params;
+    const failed = [];
+    for (const branch of branches) {
+        const fetched = await runAsync('git', [
+            'fetch',
+            '--quiet',
+            '--prune',
+            arbiter,
+            trackingRefspec(arbiter, branch),
+        ], cwd, { env });
+        if (fetched.status !== 0) {
+            failed.push(branch);
+        }
+    }
+    return { failed };
+}
+/**
+ * Resolve ONE branch's sha on the arbiter, ARBITER-AUTHORITATIVELY.
+ *
+ * `git ls-remote --heads <arbiter> <branch>` asks the arbiter directly, so the
+ * answer cannot be defeated by a local refspec/namespace accident — which is the
+ * whole point: this is the read a post-write verification uses to decide whether
+ * its OWN push landed, and that decision must never be made from a view that
+ * predates the push.
+ *
+ * Decision order:
+ *   - `ls-remote` exits 0 with a sha ⇒ `{sha, authority: 'arbiter'}` (trustworthy).
+ *   - `ls-remote` exits 0 with EMPTY output ⇒ the arbiter genuinely does not have
+ *     the branch ⇒ `{authority: 'absent'}` (trustworthy: a definite "no").
+ *   - `ls-remote` exits non-zero (unreachable / no such remote) ⇒ fall back to the
+ *     local `refs/remotes/<arbiter>/<branch>`, flagged `trustworthy: false` so a
+ *     caller cannot mistake a stale local read for proof of anything.
+ *
+ * Always call {@link refreshArbiterRefs} first when the caller ALSO needs the
+ * objects locally (a CAS base, a `merge-base` / `rev-list` comparison): a sha
+ * from `ls-remote` names a commit this repo may not have yet.
+ */
+export async function resolveArbiterBranch(params) {
+    const { cwd, arbiter, branch, env } = params;
+    const ls = await runAsync('git', ['ls-remote', '--heads', arbiter, branch], cwd, { env });
+    if (ls.status === 0) {
+        // `<sha>\t<ref>` lines. `--heads <branch>` can match several refs when the
+        // name is a glob-ish prefix, so take the line whose ref is EXACTLY ours.
+        const sha = ls.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line !== '')
+            .map((line) => line.split(/\s+/))
+            .find(([, ref]) => ref === `refs/heads/${branch}`)?.[0];
+        if (sha !== undefined && sha !== '') {
+            return { branch, sha, authority: 'arbiter', trustworthy: true };
+        }
+        // Reachable arbiter that does NOT have the branch: a definite, trustworthy
+        // "absent" (a stale local ref must not be able to resurrect it).
+        return { branch, authority: 'absent', trustworthy: true };
+    }
+    // Unreachable arbiter: best-effort local read, explicitly NOT trustworthy.
+    const local = await runAsync('git', [
+        'rev-parse',
+        '--verify',
+        '--quiet',
+        `refs/remotes/${arbiter}/${branch}^{commit}`,
+    ], cwd, { env });
+    const localSha = local.status === 0 ? local.stdout.trim() : '';
+    const unreachableDetail = ls.stderr.trim() || `git ls-remote exit ${ls.status}`;
+    if (localSha !== '') {
+        return {
+            branch,
+            sha: localSha,
+            authority: 'local-fallback',
+            trustworthy: false,
+            unreachableDetail,
+        };
+    }
+    return {
+        branch,
+        authority: 'absent',
+        trustworthy: false,
+        unreachableDetail,
+    };
+}
+//# sourceMappingURL=arbiter-refs.js.map

package/dist/arbiter-refs.js.map

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

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;AAwH1C,OAAO,EAAiB,KAAK,YAAY,EAAC,MAAM,sBAAsB,CAAC;AAwCvE,OAAO,EAAgB,KAAK,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAgyB5E;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,OAAO,GACb,MAAM,CAoCR;AA6RD,wBAAgB,YAAY,IAAI,OAAO,CAwgHtC;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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAC,OAAO,EAAS,MAAM,WAAW,CAAC;AAyH1C,OAAO,EAAiB,KAAK,YAAY,EAAC,MAAM,sBAAsB,CAAC;AAwCvE,OAAO,EAAgB,KAAK,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AA8yB5E;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,OAAO,GACb,MAAM,CAoCR;AA6RD,wBAAgB,YAAY,IAAI,OAAO,CAiiHtC;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

@@ -35,7 +35,7 @@ import { shouldUseColor } from './output.js';
 import { resolveRepoConfig, resolveRepoConfigFromLoaded, loadRepoConfigFromContent, REPO_CONFIG_FILENAME, } from './repo-config.js';
 import { ensureMirrorMain, readRepoConfigFromMirrorMain, encodeRepoKey, } from './repo-mirror.js';
 import { identityEnv } from './identity.js';
-import { harnessFlagOverrides, doFlagOverrides, doNeedsAgentCmd, NO_AGENT_CMD_MESSAGE, reviewFlagOverrides, freshWorktreeGateFlagOverrides, mergeRetriesFlagOverrides, noPRFlagOverrides, } from './do-config.js';
+import { harnessFlagOverrides, doFlagOverrides, doNeedsAgentCmd, NO_AGENT_CMD_MESSAGE, reviewFlagOverrides, freshWorktreeGateFlagOverrides, mergeRetriesFlagOverrides, noPRFlagOverrides, triageModelFlagOverrides, } from './do-config.js';
 import { harnessReviewGate, harnessTaskAcceptanceGate } from './review-gate.js';
 import { harnessSurfaceGate } from './surface-gate.js';
 import { harnessTriageGate } from './triage-gate.js';
@@ -43,7 +43,7 @@ import { harnessApplyDecider } from './apply-decide.js';
 import { harnessTaskReviewGate } from './tasker-review-loop.js';
 import { runVerify } from './verify.js';
 import { renderPrompt } from './prompt.js';
-import { resolvePromptGuidance } from './config.js';
+import { resolvePromptGuidance, applyModelFallbacks } from './config.js';
 import { gc, resolveArbiterKeyFromCwd, enumerateWorkspaceArbiters, RETAIN_REASON_TEXT, } from './gc.js';
 import { runPrdToSpec, } from './prd-to-spec.js';
 import { resyncProtocol } from './resync-protocol.js';
@@ -107,7 +107,9 @@ function flagOverrides(flags, command) {
  * `resolveRepoConfig` instead.
  */
 function resolveGlobalConfig(fileConfig, flags) {
-    return mergeConfig({ ...fileConfig, ...envOverrides(), ...flags });
+    const config = mergeConfig({ ...fileConfig, ...envOverrides(), ...flags });
+    applyModelFallbacks(config);
+    return config;
 }
 /**
  * Load BOTH the global config file AND the per-machine `config.override.json`
@@ -274,7 +276,7 @@ function buildRegistrySetAdvanceTick(options) {
                 noPR: config.noPR,
                 harness,
                 agentCmd: config.agentCmd,
-                model: config.model,
+                model: config.buildModel,
                 sessionsDir: config.sessionsDir,
                 review: config.review,
                 reviewModel: config.reviewModel,
@@ -299,12 +301,12 @@ function buildRegistrySetAdvanceTick(options) {
                 arbiter: arbiter ?? config.defaultArbiter,
                 doOptions,
                 surfaceGate: harnessSurfaceGate({ harness, agentCmd: config.agentCmd }),
-                surfaceModel: config.model,
+                surfaceModel: config.triageModel,
                 applyDecide: harnessApplyDecider({ harness, agentCmd: config.agentCmd }),
-                applyModel: config.model,
+                applyModel: config.triageModel,
                 observationTriage: config.observationTriage,
                 triageGate: harnessTriageGate({ harness, agentCmd: config.agentCmd }),
-                triageModel: config.model,
+                triageModel: config.triageModel,
                 // The ANSWERED-MERGE LAND DISPATCH context (task
                 // `apply-rung-merge-disposition`, spec `land-time-reverify-and-parallel-
                 // merge-ceiling`): the dispatcher cuts a per-job worktree via
@@ -396,6 +398,8 @@ function runFlagOverrides(flags, command) {
     // flag > env > per-repo > global > default — mirroring the `do` command (the
     // fleet inherits the review gate via the converged `performIntegration` core).
     Object.assign(overrides, reviewFlagOverrides(flags));
+    // `--triage-model` (the advance lifecycle gates' model) rides the SAME chain.
+    Object.assign(overrides, triageModelFlagOverrides(flags));
     // `--fresh-worktree-gate`/`--no-fresh-worktree-gate` rides the SAME chain: gate
     // the REBASED tip in a clean throwaway worktree (ON by default). The `run` fleet
     // caller additionally downgrades it to today's gate at `perRepoMax > 1` (the
@@ -872,6 +876,7 @@ export function buildProgram() {
         .option('--no-pr', 'propose without opening a PR: push the branch but deliberately skip the review request, even on an authed GitHub arbiter (the explicit suppress-PR intent). Resolved flag > env > per-repo > global > default off.')
         .option('--agent-cmd <cmd>', 'command to run one agent on a task prompt')
         .option('--model <id>', 'model the agent runs on (routing intent; auth/keys stay the harness\u2019s job). pi: passed as --model; null/shell: substitutes a {model} placeholder in agentCmd. Resolved flag > env > per-repo > global > default (unset).')
+        .option('--build-model <id>', 'model the BUILD agent runs on (the builder-specific override of --model). Unset at every level inherits --model. Resolved flag > env > per-repo > global > fallback to model > default (unset).')
         .option('--harness <adapter>', 'harness adapter that launches the agent + reports liveness: null (default, shells out to agentCmd) or pi (the pi CLI)')
         .option('--pi-bin <path>', 'pi CLI binary the pi harness invokes (default: pi on PATH)')
         .option('--sessions-dir <dir>', 'HOST-ONLY root folder under which pi session files are generated (--session <dir>/<id>.jsonl). Default: pi per-cwd folder under ~/.pi/agent/sessions. Resolved flag > env > global > default (no per-repo).')
@@ -879,6 +884,7 @@ export function buildProgram() {
         .option('--review', 'run Gate 2 (PR/code review) after verify, before the done-move, on every item (overrides config). Resolved flag > env > per-repo > global > default off.')
         .option('--no-review', 'do NOT run Gate 2 this tick (overrides config)')
         .option('--review-model <id>', 'model the Gate-2 review agent runs on (de-correlated from the builder; routing intent). Resolved flag > env > per-repo > global > default.')
+        .option('--triage-model <id>', 'model the advance lifecycle gates (surface, apply, triage) run on. Unset at every level inherits --model. Resolved flag > env > per-repo > global > fallback to model > default (unset).')
         .option('--review-max-rounds <n>', 'bound the revise/review loop; on exhaustion force needs-attention (default 2)')
         .option('--fresh-worktree-gate', 'run the acceptance gate (prepare then verify) against the REBASED tip in a CLEAN throwaway worktree (the tree that integrates). ON by default; the `run` fleet uses it only when same-repo concurrency is off (perRepoMax=1), else today\u2019s in-build-worktree gate.')
         .option('--no-fresh-worktree-gate', 'run the acceptance gate in the build worktree (the pre-rebase tree) — the opt-out for when the per-gate install cost is too high')
@@ -1420,6 +1426,7 @@ export function buildProgram() {
         .option('--allow-backlog', 'do task:<slug> ONLY: also FIND, CLAIM, and COMPLETE a task that lives in tasks/backlog/ (staging), driving it in place WITHOUT promoting it to the pool (so no advance leg / run daemon can claim it out from under you). The done-move goes tasks/backlog/ -> tasks/done/ directly (your explicit drive IS the promotion). EXPLICIT-INVOCATION-ONLY: default off, never set by run/auto-pick/advance or config/env.')
         .option('--agent-cmd <cmd>', 'command to run the agent on the task prompt')
         .option('--model <id>', 'model the agent runs on (routing intent; resolved flag > env > per-repo > global > default)')
+        .option('--build-model <id>', 'model the BUILD agent runs on (the builder-specific override of --model). Unset at every level inherits --model. Resolved flag > env > per-repo > global > fallback to model > default (unset).')
         .option('--harness <adapter>', 'harness adapter that launches the agent: null (default, shells out to agentCmd) or pi (the pi CLI)')
         .option('--pi-bin <path>', 'pi CLI binary the pi harness invokes (default: pi on PATH)')
         .option('--sessions-dir <dir>', 'HOST-ONLY root folder under which the pi session file is generated (--session <dir>/<id>.jsonl). Default: pi per-cwd folder under ~/.pi/agent/sessions. Resolved flag > env > global > default (no per-repo).')
@@ -1427,6 +1434,7 @@ export function buildProgram() {
         .option('--review', 'run Gate 2 (PR/code review) after verify, before the done-move (overrides config). Resolved flag > env > per-repo > global > default off.')
         .option('--no-review', 'do NOT run Gate 2 this invocation (overrides config)')
         .option('--review-model <id>', 'model the Gate-2 review agent runs on (de-correlated from the builder; routing intent). Resolved flag > env > per-repo > global > default.')
+        .option('--triage-model <id>', 'model the advance lifecycle gates (surface, apply, triage) run on. Unset at every level inherits --model. Resolved flag > env > per-repo > global > fallback to model > default (unset).')
         .option('--review-max-rounds <n>', 'bound the revise/review loop; on exhaustion force needs-attention (default 2)')
         .option('--tasker-loop', 'run the tasker IMPROVER loop on `do spec:<slug>` (review→edit→converge over the produced task set). ON by default; --no-tasker-loop skips it. DISTINCT from the acceptance gate (--review).')
         .option('--no-tasker-loop', 'skip the tasker improver loop on `do spec:<slug>`')
@@ -1649,7 +1657,7 @@ export function buildProgram() {
                 noPR: remoteConfig.noPR,
                 harness: remoteHarness,
                 agentCmd: remoteConfig.agentCmd,
-                model: remoteConfig.model,
+                model: remoteConfig.buildModel,
                 sessionsDir: remoteConfig.sessionsDir,
                 review: remoteConfig.review,
                 reviewModel: remoteConfig.reviewModel,
@@ -1820,7 +1828,7 @@ export function buildProgram() {
             noPR: config.noPR,
             harness,
             agentCmd: config.agentCmd,
-            model: config.model,
+            model: config.buildModel,
             // The HOST-ONLY sessions root (resolved Config → DoOptions bridge, like
             // model/agentCmd): the path generator turns it into
             // `<sessionsDir>/<id>.jsonl` for `--session`. Without this map the key
@@ -2082,7 +2090,7 @@ export function buildProgram() {
                 noPR: remoteConfig.noPR,
                 harness: isoHarness,
                 agentCmd: remoteConfig.agentCmd,
-                model: remoteConfig.model,
+                model: remoteConfig.buildModel,
                 sessionsDir: remoteConfig.sessionsDir,
                 review: remoteConfig.review,
                 reviewModel: remoteConfig.reviewModel,
@@ -2122,18 +2130,18 @@ export function buildProgram() {
                     harness: isoHarness,
                     agentCmd: remoteConfig.agentCmd,
                 }),
-                surfaceModel: remoteConfig.model,
+                surfaceModel: remoteConfig.triageModel,
                 applyDecide: harnessApplyDecider({
                     harness: isoHarness,
                     agentCmd: remoteConfig.agentCmd,
                 }),
-                applyModel: remoteConfig.model,
+                applyModel: remoteConfig.triageModel,
                 observationTriage: remoteConfig.observationTriage,
                 triageGate: harnessTriageGate({
                     harness: isoHarness,
                     agentCmd: remoteConfig.agentCmd,
                 }),
-                triageModel: remoteConfig.model,
+                triageModel: remoteConfig.triageModel,
                 note: (message) => console.error(`>> ${message}`),
                 env: process.env,
             };
@@ -2222,7 +2230,7 @@ export function buildProgram() {
             noPR: config.noPR,
             harness,
             agentCmd: config.agentCmd,
-            model: config.model,
+            model: config.buildModel,
             sessionsDir: config.sessionsDir,
             review: config.review,
             reviewModel: config.reviewModel,
@@ -2258,12 +2266,12 @@ export function buildProgram() {
             arbiter: flags.arbiter ?? config.defaultArbiter,
             doOptions,
             surfaceGate: harnessSurfaceGate({ harness, agentCmd: config.agentCmd }),
-            surfaceModel: config.model,
+            surfaceModel: config.triageModel,
             applyDecide: harnessApplyDecider({ harness, agentCmd: config.agentCmd }),
-            applyModel: config.model,
+            applyModel: config.triageModel,
             observationTriage: config.observationTriage,
             triageGate: harnessTriageGate({ harness, agentCmd: config.agentCmd }),
-            triageModel: config.model,
+            triageModel: config.triageModel,
             note: (message) => console.error(`>> ${message}`),
         };
         // `--watch` tails ONE pi session, so it only fits the single-named-item form
@@ -3076,6 +3084,7 @@ export function buildProgram() {
         .option('--tasks-land-in <where>', 'where an intake-authored TASK (emitted DIRECTLY from an issue) lands: `backlog` (staged, not agent-eligible) or `ready` (the agent POOL). The task twin of --specs-land-in: the EXPLICIT operator override at the top of the placement precedence (explicit flag > configured default > built-in staging; the caller selects the trusted-vs-untrusted default from the origin-trust stamp). Resolved flag > env (DORFL_TASKS_LAND_IN) > per-repo > global > built-in.')
         .option('--agent-cmd <cmd>', 'command to run the decision agent')
         .option('--model <id>', 'model the decision agent runs on (routing intent; resolved flag > env > per-repo > global > default)')
+        .option('--intake-model <id>', 'model the intake decision agent runs on (the builder-specific override of --model). Unset at every level inherits --model. Resolved flag > env > per-repo > global > fallback to model > default (unset).')
         .option('--harness <adapter>', 'harness adapter that launches the decision agent: null (default) or pi')
         .option('--pi-bin <path>', 'pi CLI binary the pi harness invokes (default: pi on PATH)')
         .option('--sessions-dir <dir>', 'HOST-ONLY root folder under which the pi session file is generated')
@@ -3097,6 +3106,11 @@ export function buildProgram() {
                 ...harnessFlagOverrides(flags),
                 // `--no-pr` (the PR-INTENT axis) rides the SAME chain.
                 ...noPRFlagOverrides(flags),
+                // `--intake-model` rides the SAME chain (falls back to `model`
+                // when unset at all levels via `applyModelFallbacks`).
+                ...(flags.intakeModel !== undefined
+                    ? { intakeModel: flags.intakeModel }
+                    : {}),
             },
         });
         if (resolved.message) {
@@ -3201,7 +3215,7 @@ export function buildProgram() {
             explicitTasksLandIn,
             harness,
             agentCmd: config.agentCmd,
-            model: config.model,
+            model: config.intakeModel,
             sessionsDir: config.sessionsDir,
             // Host-only runner IDENTITY — scopes intake's `gh`/git ops (not the
             // decision/review AGENT launches); absent ⇒ ambient.