dorfl 0.0.0 → 0.1.0

package/dist/env-config.js

@@ -0,0 +1,272 @@
+import { brand, constantCase } from './brand.js';
+/**
+ * The environment-variable config layer.
+ *
+ * A per-machine context (a CI job, a developer's shell) can set ANY {@link Config}
+ * key via an `DORFL_*` environment variable WITHOUT committing a file —
+ * including the host-only keys (`piBin`, `agentCmd`, …) that the per-repo
+ * `.dorfl.json` deliberately rejects.
+ *
+ * Env is a legitimate *per-machine source* — exactly like a CLI flag or the
+ * global `~/.config/dorfl/config.json` — so it is NOT subject to the
+ * per-repo allow/reject split (that split only governs the *committed repo
+ * file*). This is the sharpened host-only principle (ADR §13): host-only keys
+ * must come from a per-machine source (flag, env, or global file), never the
+ * committed repo file; env is simply the per-machine source CI actually has
+ * without writing a file.
+ *
+ * Resolution chain (highest wins):
+ *
+ *   flag > ENV (DORFL_*) > per-repo > global > built-in default
+ *
+ * Naming: `DORFL_<SCREAMING_SNAKE(key)>` (mechanical camelCase →
+ * SCREAMING_SNAKE, prefixed with `DORFL_` to match the binary). E.g.
+ * `DORFL_AGENT_CMD`, `DORFL_PI_BIN`, `DORFL_DEFAULT_ARBITER`,
+ * `DORFL_PER_REPO_MAX`.
+ *
+ * Each value is coerced per the key's type and a typo/invalid value FAILS LOUDLY
+ * (never silently ignored) with a message naming the offending variable.
+ */
+/**
+ * The shared `DORFL_` prefix on every env config variable. Derived from
+ * the single brand identity (`constantCase(base) + '_'`) so a rename flips the
+ * prefix in lockstep with the binary name (see `brand.ts`).
+ */
+export const ENV_PREFIX = brand.envPrefix;
+/**
+ * The coercion to apply per env-settable {@link Config} key. The source of truth
+ * for which env vars exist and how their raw strings become typed values. EVERY
+ * SCALAR `Config` key appears here (host-only included) — env is a per-machine
+ * source, so no scalar key is off-limits. Keys not listed have no env var.
+ *
+ * The lone EXCLUSION is `identity`: it is a NESTED structured object (with its
+ * own `auth`/`providers` sub-objects), not a scalar a single env string can
+ * carry. A `tokenEnv` indirection already covers the one secret a CI/per-machine
+ * context legitimately injects via env (the `gh` token), so there is no JSON-in-
+ * env hack here. The mapped type is `Partial` precisely to ALLOW this exclusion.
+ */
+const KEY_COERCIONS = {
+    autoBuild: 'boolean',
+    autoTask: 'boolean',
+    // The observation-triage gate is a 3-state ENUM coercion (like `integration`),
+    // so `DORFL_OBSERVATION_TRIAGE=off|ask|auto` works and a typo FAILS
+    // LOUDLY naming the variable + the valid options.
+    observationTriage: { enum: ['off', 'ask', 'auto'] },
+    // The merge-question SURFACER gate is a 3-state ENUM coercion (mirrors
+    // `observationTriage`'s shape; SEPARATE axis with a HIGHER default, prd
+    // `land-time-reverify-and-parallel-merge-ceiling` Story 17 / task
+    // `merge-questions-gate-axis`), so `DORFL_MERGE_QUESTIONS=off|ask|auto`
+    // works and a typo FAILS LOUDLY naming the variable + the valid options.
+    mergeQuestions: { enum: ['off', 'ask', 'auto'] },
+    // The surface-blockers gate is a BOOLEAN coercion (like `autoBuild`), so
+    // `DORFL_SURFACE_BLOCKERS=true|false` works and a typo FAILS LOUDLY.
+    surfaceBlockers: 'boolean',
+    // `surfaceStaging` (the BOOLEAN gate-family member that widens the SURFACE
+    // candidate set to include STAGING — `tasks/backlog/` + `prds/proposed/` —
+    // not only the agent pool; prd
+    // `staging-surface-and-apply-promote-safety` F2) coerces as a BOOLEAN like
+    // `autoBuild`/`surfaceBlockers`, so `DORFL_SURFACE_STAGING=true|false`
+    // works and a typo FAILS LOUDLY. Resolution chain identical to the other
+    // gate-family members (flag > env > per-repo > global > built-in `true`).
+    surfaceStaging: 'boolean',
+    // `selectionOrder` coerces as a `'list'` (comma form
+    // `DORFL_SELECTION_ORDER=build,task,surface,triage`); a single-element
+    // list whose one entry is a preset keyword (`=drain`) is expanded by the
+    // resolver (`select-order.ts`). Subsumes the removed `prdsFirst` boolean.
+    selectionOrder: 'list',
+    maxParallel: 'number',
+    perRepoMax: 'number',
+    defaultArbiter: 'string',
+    workspacesDir: 'string',
+    arbitersDir: 'string',
+    humanWorktreesDir: 'string',
+    integration: { enum: ['propose', 'merge'] },
+    // `taskingIntegration` (the per-TRANSITION TASKING override) coerces as the SAME
+    // `propose`/`merge` enum as `integration`, so `DORFL_TASKING_INTEGRATION`
+    // works and a typo FAILS LOUDLY. Unset ⇒ the tasking transition falls back to
+    // `integration` (the flat value). It NEVER touches the build transition or intake.
+    taskingIntegration: { enum: ['propose', 'merge'] },
+    // `tasksLandIn` (the per-repo TASK-PLACEMENT default — prd
+    // `staging-pool-position-gate-and-trust-model` US #5) coerces as the
+    // `pre-backlog`/`ready` enum, so `DORFL_TASKS_LAND_IN=ready` works and a
+    // typo FAILS LOUDLY. Same
+    // precedence chain as `taskingIntegration` (flag > env > per-repo > global >
+    // built-in `pre-backlog`); fed into the runner-deterministic placement
+    // resolver (`src/placement.ts`) as the configured-default rung.
+    tasksLandIn: { enum: ['pre-backlog', 'ready'] },
+    // `specsLandIn` (the per-repo SPEC-PLACEMENT default — spec
+    // `staging-pool-position-gate-and-trust-model` US #2/#5) coerces as the
+    // `pre-proposed`/`ready` enum, so `DORFL_SPECS_LAND_IN=ready` works and a typo
+    // FAILS LOUDLY. Same precedence chain as `tasksLandIn` (flag > env > per-repo
+    // > global > built-in `pre-proposed`); fed into the shared placement resolver
+    // (`src/placement.ts`) as the configured-default rung for the spec lifecycle.
+    // The legacy `prdsLandIn` key / `DORFL_PRDS_LAND_IN` env are GONE after the
+    // prd → spec hard cutover (clean break).
+    specsLandIn: { enum: ['pre-proposed', 'ready'] },
+    // `noPR` (the PR-INTENT axis) is a BOOLEAN coercion (like `review`), so
+    // `DORFL_NO_PR=true|false` works and a typo FAILS LOUDLY. The removed
+    // `provider` override has NO env var (a stale `DORFL_PROVIDER` is ignored
+    // with a deprecation warning — see `envOverrides`).
+    noPR: 'boolean',
+    agentCmd: 'string',
+    model: 'string',
+    harness: { enum: ['null', 'pi'] },
+    piBin: 'string',
+    sessionsDir: 'string',
+    // `prepare` coerces as a `'list'` (comma form
+    // `DORFL_PREPARE=pnpm install,git submodule update --init`), exactly
+    // like `verify` — the SAME precedence chain, the sibling env-prep step.
+    prepare: 'list',
+    verify: 'list',
+    review: 'boolean',
+    reviewModel: 'string',
+    reviewMaxRounds: 'number',
+    taskerLoop: 'boolean',
+    taskerLoopMax: 'number',
+    taskerLoopModel: 'string',
+    // `freshWorktreeGate` is a BOOLEAN coercion (like `taskerLoop`), so
+    // `DORFL_FRESH_WORKTREE_GATE=true|false` works and a typo FAILS LOUDLY.
+    freshWorktreeGate: 'boolean',
+    // `mergeRetries` (the cross-job merge serialiser's CAS-retry cap — prd
+    // `land-time-reverify-and-parallel-merge-ceiling` Story 5 / Applied Answer q1 (a))
+    // coerces as a NUMBER (like `reviewMaxRounds`), so `DORFL_MERGE_RETRIES=20`
+    // works and a typo FAILS LOUDLY. A wide-matrix CI raises it; the default
+    // (1000 — the C2 large liveness ceiling) stays in place when unset.
+    mergeRetries: 'number',
+    // `strictMergeApproval` (the OPT-IN strictness layered on the OQ6
+    // stale-approval default — prd `land-time-reverify-and-parallel-merge-ceiling`
+    // sidecar OQ6 / task `strict-merge-approval-gate`) coerces as a BOOLEAN
+    // (like `freshWorktreeGate`), so `DORFL_STRICT_MERGE_APPROVAL=true|false`
+    // works and a typo FAILS LOUDLY. Default OFF; ON re-surfaces the
+    // merge-question on a merge-base change instead of auto-landing.
+    strictMergeApproval: 'boolean',
+    // `promptGuidance` is a STRUCTURED (nested) namespace, so it has no scalar env
+    // var of its own — each MEMBER carries its own env var (the nested-key form
+    // `DORFL_PROMPT_GUIDANCE_<MEMBER>`), handled out-of-band in
+    // `envOverrides` below. Listing the namespace here would imply a single scalar
+    // `DORFL_PROMPT_GUIDANCE` env var, which is NOT how the namespace is
+    // shaped (each nudge member is independently resolvable).
+};
+/**
+ * The env vars for the nested members of the `promptGuidance` namespace. The
+ * key is the env var name (`DORFL_PROMPT_GUIDANCE_<MEMBER>`, the nested
+ * naming the prd specifies); the value is the (boolean) coercion. Each member
+ * present in env contributes `{<member>: bool}` into a single
+ * `promptGuidance` partial — mergeConfig replaces the whole namespace per the
+ * layered precedence, which is correct because EVERY member is included (env
+ * supplies a complete inner object whenever ANY member is set).
+ */
+const PROMPT_GUIDANCE_ENV = {
+    [ENV_PREFIX + 'PROMPT_GUIDANCE_TEST_FIRST']: 'boolean',
+};
+/** The `DORFL_*` env var name for a config key (`perRepoMax` →
+ * `DORFL_PER_REPO_MAX`): the brand prefix + the key in `constantCase`. */
+export function envVarName(key) {
+    return ENV_PREFIX + constantCase(key);
+}
+/**
+ * Coerce a raw env string for one key, FAILING LOUDLY (with the offending var
+ * name) on invalid input: booleans accept only `true`/`false`; numbers reject
+ * NaN; enums must be in their union; list keys split on comma; strings verbatim.
+ */
+function coerceValue(varName, raw, coercion) {
+    if (typeof coercion === 'object') {
+        // Enum: validate against the union.
+        if (!coercion.enum.includes(raw)) {
+            throw new Error(`Invalid value for ${varName}: '${raw}'. ` +
+                `Expected one of: ${coercion.enum.join(', ')}.`);
+        }
+        return raw;
+    }
+    switch (coercion) {
+        case 'string':
+            return raw;
+        case 'boolean':
+            if (raw === 'true') {
+                return true;
+            }
+            if (raw === 'false') {
+                return false;
+            }
+            throw new Error(`Invalid boolean for ${varName}: '${raw}'. Expected 'true' or 'false'.`);
+        case 'number': {
+            const n = Number(raw);
+            if (raw.trim() === '' || Number.isNaN(n)) {
+                throw new Error(`Invalid number for ${varName}: '${raw}'. Expected a numeric value.`);
+            }
+            return n;
+        }
+        case 'list':
+            // Split on comma (cross-platform; not `:`), trimming each entry. An empty
+            // string ⇒ an empty list (an explicit "clear" of a list key).
+            return raw
+                .split(',')
+                .map((s) => s.trim())
+                .filter((s) => s !== '');
+    }
+}
+/**
+ * Read the `DORFL_*` env layer into a {@link PartialConfig}. Only vars
+ * actually present (and non-`undefined`) contribute, so absent env ⇒ `{}` and
+ * built-in floors/defaults are untouched. Each present var is coerced per its
+ * key's type; an invalid value throws LOUDLY naming the variable.
+ *
+ * Env may set ANY key — host-only included — because env is a per-machine
+ * source, NOT the committed repo file (see this module's doc + ADR §13).
+ */
+export function envOverrides(env = process.env, warn = (m) => console.error(`>> ${m}`)) {
+    // A stale `DORFL_PROVIDER` (the removed provider OVERRIDE) is IGNORED with
+    // a one-line deprecation warning, never an error — the provider is now purely
+    // arbiter-derived; "suppress the PR" re-homes to `noPR` (`DORFL_NO_PR`).
+    const staleProvider = env[ENV_PREFIX + 'PROVIDER'];
+    if (staleProvider !== undefined) {
+        warn(`Ignoring deprecated env var ${ENV_PREFIX}PROVIDER: the provider is now ` +
+            'purely arbiter-derived (a GitHub remote ⇒ the GitHub provider, else ' +
+            'none). To suppress the PR (the old `none` use), set ' +
+            `${ENV_PREFIX}NO_PR=true (or pass --no-pr).` +
+            (staleProvider === 'none'
+                ? ' (your `none` maps directly to NO_PR=true.)'
+                : ''));
+    }
+    const overrides = {};
+    // Per-member env layer for the `promptGuidance` NUDGE namespace. Each member
+    // is INDEPENDENTLY resolvable (`DORFL_PROMPT_GUIDANCE_<MEMBER>`); a
+    // present env var sets that member in the partial. We merge ALL set members
+    // into a single inner object, then assign once — the outer mergeConfig
+    // REPLACES the namespace per layer, so we send a coherent partial-inner per
+    // env override (a missing member there reads its default from the lower
+    // layer's namespace, which works because env is precisely a per-machine
+    // SETTER, not a gate).
+    const promptGuidancePartial = {};
+    for (const [varName, coercion] of Object.entries(PROMPT_GUIDANCE_ENV)) {
+        const raw = env[varName];
+        if (raw === undefined) {
+            continue;
+        }
+        const value = coerceValue(varName, raw, coercion);
+        if (varName === ENV_PREFIX + 'PROMPT_GUIDANCE_TEST_FIRST') {
+            promptGuidancePartial.testFirst = value;
+        }
+    }
+    if (Object.keys(promptGuidancePartial).length > 0) {
+        overrides.promptGuidance = {
+            testFirst: promptGuidancePartial.testFirst ?? false,
+        };
+    }
+    for (const key of Object.keys(KEY_COERCIONS)) {
+        const coercion = KEY_COERCIONS[key];
+        if (coercion === undefined) {
+            continue;
+        }
+        const varName = envVarName(key);
+        const raw = env[varName];
+        if (raw === undefined) {
+            continue;
+        }
+        const coerced = coerceValue(varName, raw, coercion);
+        // Type matches by construction: each coercion yields the key's value type.
+        overrides[key] = coerced;
+    }
+    return overrides;
+}
+//# sourceMappingURL=env-config.js.map

package/dist/env-config.js.map

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

package/dist/failure-cause.d.ts

@@ -0,0 +1,70 @@
+/**
+ * **The failure-CAUSE classifier** (task `failure-cause-classification-model-vs-
+ * git-vs-agent`).
+ *
+ * When a claimed item routes to `work/needs-attention/`, the runner records WHY.
+ * Historically several DIFFERENT causes collapsed into one undifferentiated label
+ * ("agent failed"), even though the CAUSE drives the RECOVERY:
+ *
+ *   - **transient-infra** → retry the SAME work (the work is fine: a model
+ *     endpoint outage the harness surfaced AFTER its own retries, or a git/
+ *     provider outage).
+ *   - **config-error** → fix the WIRING, not the task (a thrown CORE wiring/
+ *     config error, e.g. `review` on with no `reviewGate` configured).
+ *   - **agent-failed** (the conservative generic) → a human/agent must FIX
+ *     something the agent did (ran but produced bad/empty output), OR the cause is
+ *     simply UNKNOWN — the safe default that never forces a wrong specific label.
+ *
+ * This module classifies ONLY the axis that was previously lumped under
+ * "agent-failed". The OTHER existing terminal causes already have precise names
+ * and are NOT re-classified here — a red acceptance gate stays `gate-failed`, a
+ * rebase abort stays `rebase-conflict`, a deliberate STOP stays `agent-stopped`,
+ * a Gate-2 block stays `review-blocked`. This is the CAUSE axis ON TOP of those
+ * (see CONTEXT.md's *failure cause* glossary entry — the single source of truth).
+ *
+ * The classification is BEST-EFFORT + CONSERVATIVE: an unrecognised cause stays
+ * the generic `agent-failed`. The new precision is ADDED only where the cause is
+ * knowable from the surfaced error/detail; it never forces a wrong label.
+ *
+ * **`do` and `run` classify the SAME error the SAME way** by both routing their
+ * thrown-core-error / failed-agent detail through THIS one function — closing the
+ * cross-path divergence recorded in
+ * `work/notes/observations/run-thrown-core-error-labeled-agent-failed.md` (the SAME
+ * thrown core error used to read as `usage-error` in `do` but `agent-failed` in
+ * `run`).
+ *
+ * SCOPE FENCE: model-endpoint RETRIES are the HARNESS's job (pi retries its own
+ * API ~3–4×). This module does NOT add retries — it only CLASSIFIES what the
+ * harness SURFACES once its retries are exhausted (so a post-retry model outage
+ * reads as `transient-infra`, distinct from the agent producing bad output).
+ */
+/**
+ * The CAUSE of a stuck item, the axis ON TOP of the existing terminal outcomes.
+ * Only the values this module decides between are listed — the genuinely-NEW
+ * `transient-infra` / `config-error` plus the conservative generic `agent-failed`
+ * (the existing name, reused as the safe default). The other terminal causes
+ * (`gate-failed`, `rebase-conflict`, `agent-stopped`, `review-blocked`) are NOT
+ * produced here; they keep their own precise outcome names at their own sites.
+ */
+export type FailureCause = 'transient-infra' | 'config-error' | 'agent-failed';
+/**
+ * Classify a failure CAUSE from the surfaced error/detail text, best-effort +
+ * conservative (an unrecognised cause stays `agent-failed`).
+ *
+ * Order matters: a thrown CORE config/wiring error is checked FIRST (it is the
+ * most specific + the cross-path divergence this task closes), then the
+ * transient-infra signals, else the generic default.
+ *
+ * Used by BOTH `do` and `run` at their failure-routing sites so the SAME error
+ * yields the SAME cause regardless of path.
+ */
+export declare function classifyFailureCause(detail: string | undefined): FailureCause;
+/**
+ * A short, human-readable label for a cause, used to PREFIX the recorded
+ * needs-attention reason so an operator (or an autonomous triage loop) reads the
+ * cause WITHOUT a second naming scheme. The generic `agent-failed` gets the
+ * historical "agent failed:" prefix so existing reason prose / tests are
+ * unchanged; only the NEW causes carry a distinct, legible prefix.
+ */
+export declare function failureCauseLabel(cause: FailureCause): string;
+//# sourceMappingURL=failure-cause.d.ts.map

package/dist/failure-cause.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-cause.d.ts","sourceRoot":"","sources":["../src/failure-cause.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACrB,iBAAiB,GACjB,cAAc,GACd,cAAc,CAAC;AAgDlB;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAY7E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAS7D"}

package/dist/failure-cause.js

@@ -0,0 +1,126 @@
+/**
+ * **The failure-CAUSE classifier** (task `failure-cause-classification-model-vs-
+ * git-vs-agent`).
+ *
+ * When a claimed item routes to `work/needs-attention/`, the runner records WHY.
+ * Historically several DIFFERENT causes collapsed into one undifferentiated label
+ * ("agent failed"), even though the CAUSE drives the RECOVERY:
+ *
+ *   - **transient-infra** → retry the SAME work (the work is fine: a model
+ *     endpoint outage the harness surfaced AFTER its own retries, or a git/
+ *     provider outage).
+ *   - **config-error** → fix the WIRING, not the task (a thrown CORE wiring/
+ *     config error, e.g. `review` on with no `reviewGate` configured).
+ *   - **agent-failed** (the conservative generic) → a human/agent must FIX
+ *     something the agent did (ran but produced bad/empty output), OR the cause is
+ *     simply UNKNOWN — the safe default that never forces a wrong specific label.
+ *
+ * This module classifies ONLY the axis that was previously lumped under
+ * "agent-failed". The OTHER existing terminal causes already have precise names
+ * and are NOT re-classified here — a red acceptance gate stays `gate-failed`, a
+ * rebase abort stays `rebase-conflict`, a deliberate STOP stays `agent-stopped`,
+ * a Gate-2 block stays `review-blocked`. This is the CAUSE axis ON TOP of those
+ * (see CONTEXT.md's *failure cause* glossary entry — the single source of truth).
+ *
+ * The classification is BEST-EFFORT + CONSERVATIVE: an unrecognised cause stays
+ * the generic `agent-failed`. The new precision is ADDED only where the cause is
+ * knowable from the surfaced error/detail; it never forces a wrong label.
+ *
+ * **`do` and `run` classify the SAME error the SAME way** by both routing their
+ * thrown-core-error / failed-agent detail through THIS one function — closing the
+ * cross-path divergence recorded in
+ * `work/notes/observations/run-thrown-core-error-labeled-agent-failed.md` (the SAME
+ * thrown core error used to read as `usage-error` in `do` but `agent-failed` in
+ * `run`).
+ *
+ * SCOPE FENCE: model-endpoint RETRIES are the HARNESS's job (pi retries its own
+ * API ~3–4×). This module does NOT add retries — it only CLASSIFIES what the
+ * harness SURFACES once its retries are exhausted (so a post-retry model outage
+ * reads as `transient-infra`, distinct from the agent producing bad output).
+ */
+/**
+ * The signature of a thrown CORE wiring/config error this module recognises. The
+ * core throws a plain `Error` for `review` on with no `reviewGate` wired (the
+ * canonical config-error; see `integration-core.ts`), whose message contains
+ * "wiring bug". We match on that stable phrase rather than the error CLASS so the
+ * classification survives the message crossing the plain-`Error` boundary the
+ * catch sites hand us (they only have `err.message`).
+ */
+const CONFIG_ERROR_SIGNATURES = [
+    /wiring bug/i,
+    /no review gate is configured/i,
+];
+/**
+ * Substrings that mark a TRANSIENT-INFRA failure: a model endpoint / connection
+ * outage the harness surfaced AFTER exhausting its own retries, or a git/provider
+ * outage. Best-effort lexical signals (the harness/git only hand us a message
+ * string) — deliberately conservative: anything not matched stays `agent-failed`.
+ */
+const TRANSIENT_INFRA_SIGNATURES = [
+    // A Gate-2 review verdict the runner could not PARSE (malformed JSON from the
+    // review agent, common on large diffs + weaker models). This is `transient-infra`,
+    // NOT `agent-failed`/`config-error`: the WORK is fine and the wiring is fine; the
+    // STOCHASTIC gate output misbehaved, so re-running the SAME work is the natural
+    // recovery (and the parser's repair pass + the tightened contract make a re-run far
+    // more likely to parse). Matches both `parseReviewVerdict` throw phrasings ("review
+    // verdict was not valid JSON" and "produced no parseable {verdict, findings}") and
+    // the core's "verdict could not be parsed" wrapper.
+    /review verdict was not valid JSON/i,
+    /verdict could not be parsed/i,
+    /no parseable \{verdict/i,
+    /\bECONN(?:REFUSED|RESET|ABORTED)\b/i,
+    /\bETIMEDOUT\b/i,
+    /\bENOTFOUND\b/i,
+    /\bEAI_AGAIN\b/i,
+    /connection (?:error|refused|reset|timed out|failed)/i,
+    /network (?:error|is unreachable|timeout)/i,
+    /\b(?:could not|unable to) (?:connect|reach)\b/i,
+    /\btimed? ?out\b/i,
+    /\b(?:overloaded|service unavailable|temporarily unavailable)\b/i,
+    /\b(?:429|500|502|503|504)\b/,
+    /model (?:endpoint )?(?:offline|unavailable|overloaded)/i,
+    /(?:after|exhausted) .{0,40}retr(?:y|ies)/i,
+    /rate.?limit/i,
+];
+/**
+ * Classify a failure CAUSE from the surfaced error/detail text, best-effort +
+ * conservative (an unrecognised cause stays `agent-failed`).
+ *
+ * Order matters: a thrown CORE config/wiring error is checked FIRST (it is the
+ * most specific + the cross-path divergence this task closes), then the
+ * transient-infra signals, else the generic default.
+ *
+ * Used by BOTH `do` and `run` at their failure-routing sites so the SAME error
+ * yields the SAME cause regardless of path.
+ */
+export function classifyFailureCause(detail) {
+    const text = (detail ?? '').trim();
+    if (text === '') {
+        return 'agent-failed';
+    }
+    if (CONFIG_ERROR_SIGNATURES.some((re) => re.test(text))) {
+        return 'config-error';
+    }
+    if (TRANSIENT_INFRA_SIGNATURES.some((re) => re.test(text))) {
+        return 'transient-infra';
+    }
+    return 'agent-failed';
+}
+/**
+ * A short, human-readable label for a cause, used to PREFIX the recorded
+ * needs-attention reason so an operator (or an autonomous triage loop) reads the
+ * cause WITHOUT a second naming scheme. The generic `agent-failed` gets the
+ * historical "agent failed:" prefix so existing reason prose / tests are
+ * unchanged; only the NEW causes carry a distinct, legible prefix.
+ */
+export function failureCauseLabel(cause) {
+    switch (cause) {
+        case 'transient-infra':
+            return 'transient infra';
+        case 'config-error':
+            return 'config error';
+        case 'agent-failed':
+            return 'agent failed';
+    }
+}
+//# sourceMappingURL=failure-cause.js.map

package/dist/failure-cause.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-cause.js","sourceRoot":"","sources":["../src/failure-cause.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAeH;;;;;;;GAOG;AACH,MAAM,uBAAuB,GAAG;IAC/B,aAAa;IACb,+BAA+B;CAC/B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,0BAA0B,GAAG;IAClC,8EAA8E;IAC9E,mFAAmF;IACnF,kFAAkF;IAClF,gFAAgF;IAChF,oFAAoF;IACpF,oFAAoF;IACpF,mFAAmF;IACnF,oDAAoD;IACpD,oCAAoC;IACpC,8BAA8B;IAC9B,yBAAyB;IACzB,qCAAqC;IACrC,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,sDAAsD;IACtD,2CAA2C;IAC3C,gDAAgD;IAChD,kBAAkB;IAClB,iEAAiE;IACjE,6BAA6B;IAC7B,yDAAyD;IACzD,2CAA2C;IAC3C,cAAc;CACd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAA0B;IAC9D,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QACjB,OAAO,cAAc,CAAC;IACvB,CAAC;IACD,IAAI,uBAAuB,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QACzD,OAAO,cAAc,CAAC;IACvB,CAAC;IACD,IAAI,0BAA0B,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC5D,OAAO,iBAAiB,CAAC;IAC1B,CAAC;IACD,OAAO,cAAc,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAmB;IACpD,QAAQ,KAAK,EAAE,CAAC;QACf,KAAK,iBAAiB;YACrB,OAAO,iBAAiB,CAAC;QAC1B,KAAK,cAAc;YAClB,OAAO,cAAc,CAAC;QACvB,KAAK,cAAc;YAClB,OAAO,cAAc,CAAC;IACxB,CAAC;AACF,CAAC"}

package/dist/format.d.ts

@@ -0,0 +1,43 @@
+import type { ScanReport } from './scan.js';
+import type { CwdSection } from './cwd-section.js';
+import type { LockEntry } from './item-lock.js';
+/**
+ * Human label for the two autonomy axes. `humanOnly` is reported first when both
+ * are set, so the REASON an agent is gated is always visible and distinct from
+ * `needsAnswers`.
+ */
+export declare function gateLabel(humanOnly: boolean | undefined, needsAnswers?: boolean | undefined): string;
+/**
+ * Render the CWD-LOCAL section of `scan`/`status` (the `scan-status-read-cwd-repo`
+ * task): a DISTINCT, separately-counted block for the CURRENT repo, read from
+ * the LOCAL WORKING TREE (NOT the registry's bare mirror ref). Returns `[]` when
+ * the cwd does NOT participate (no local section). The section LABELS its source
+ * + freshness, shows the divergence-vs-arbiter (`main-divergence-guard` framing),
+ * and — when the cwd participates but is NOT registered — teaches
+ * self-registration instead of the dead-end "No participating repos found".
+ *
+ * The counts here are the cwd's OWN (never merged into the registry total — the
+ * consistency rule): the two reads have different freshness + storage models.
+ */
+/**
+ * Render ONE held per-item lock entry (action × state + reason/questions) as
+ * indented lines, the SHARED renderer for the in-flight lock surface on BOTH the
+ * registry view (`formatStatus`) and the cwd section (`formatCwdSection`), so the
+ * two substrates present a held/stuck item identically (NOT a forked renderer). An
+ * `active` hold reads as `in-progress`; a `stuck` hold as `needs-attention` and
+ * carries its (possibly multi-line) reason + any surfaced questions.
+ */
+export declare function formatLockEntryLines(entry: LockEntry, indent: string): string[];
+export declare function formatCwdSection(section: CwdSection): string[];
+/**
+ * Render the cross-repo queue as a human decision dashboard: under each repo,
+ * every backlog item is grouped by who-can-take-it (Agent-claimable now /
+ * Human-only / Blocked), with empty groups shown as `(none)`. Within a group,
+ * ready (deps-satisfied) items sort above blocked ones.
+ *
+ * The set of groups shown is INDEPENDENT of `autoBuild`; only the eligibility
+ * *verdict* line reflects the policy (`report.totalEligible` counts an
+ * agent-claimable item only when `autoBuild` is on).
+ */
+export declare function formatReport(report: ScanReport, cwd?: CwdSection): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAc,MAAM,WAAW,CAAC;AACvD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAW9C;;;;GAIG;AACH,wBAAgB,SAAS,CACxB,SAAS,EAAE,OAAO,GAAG,SAAS,EAC9B,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,GAChC,MAAM,CAQR;AA6ED;;;;;;;;;;;GAWG;AACH;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CACnC,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,GACZ,MAAM,EAAE,CAwBV;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,EAAE,CAyE9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,UAAU,GAAG,MAAM,CAwEzE"}