dorfl 0.0.0 → 0.1.1

package/dist/pi-harness.js

@@ -0,0 +1,342 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { NullHarness, pidAlive, registerHarness, } from './harness.js';
+import { generateSessionPath } from './session-path.js';
+import { lastAssistantText } from './watch-session.js';
+/**
+ * The **pi** harness adapter (ADR §5) — the first real agent harness
+ * `dorfl` drives. It fulfils the harness seam introduced by
+ * `agent-workspaces` (`./harness.ts`): launch a job's work-agent command in its
+ * worktree, and report liveness from **pi-native signals**.
+ *
+ * Two design commitments from the task + ADR §5, both encoded here:
+ *
+ *  1. **Invocation** is the standard work-agent prompt (the constant wrapper +
+ *     the task's `## Prompt`, assembled by `./prompt.ts`) fed to the pi CLI on
+ *     stdin, running non-interactively (`--print`) inside the job worktree.
+ *  2. **Liveness** is reported from the **PID** (process alive?) PLUS a pointer
+ *     to the pi **session file** (real activity + an audit trail) — explicitly
+ *     **NOT filesystem mtime**: a live agent can think for minutes without
+ *     writing any files, so mtime would mistake a thinking agent for a dead one.
+ *
+ * ## Session location: `--session <full-path>` (task `session-path-pi-default`)
+ *
+ * The adapter passes a **deterministic FULL session-FILE path** as `--session
+ * <path>` (NOT `--session-dir <dir>`). The caller GENERATES that path once
+ * (before launch, so `do --watch` can tail the known path) via {@link
+ * generateSessionPath} and threads it in as `LaunchInput.session`; when omitted,
+ * the adapter generates a default for its own cwd. pi creates+writes the session
+ * at exactly that path (it CREATES a non-existent `--session` file) and
+ * `--session` takes precedence over `--session-dir` (verified vs pinned pi
+ * source). The default lands under pi's per-cwd sessions folder, so the
+ * pi-remote dashboard sees the session and the in-place checkout stays clean.
+ * The arg is ABSOLUTE and ends `.jsonl` — required, else pi treats it as a
+ * session-ID lookup and exits 1 (see {@link generateSessionPath}).
+ *
+ * pi specifics stay BEHIND this adapter; the core (`run`, `status`, `do`) talks
+ * only to the `Harness` interface. Where running real pi in CI is impractical,
+ * the pi CLI is stubbed (see `pi-harness.test.ts`) via the injectable `piBin`.
+ *
+ * ## Seam contract (what an adapter promises the core)
+ *
+ *  - `launch(input)` runs the work-agent command for ONE job in `input.dir`
+ *    (the worktree), feeding `input.prompt` to the agent. It returns
+ *    `{ok, record, detail?}`: `ok` iff the agent completed successfully, and a
+ *    `record` to persist in `.dorfl-job.json` carrying the **liveness
+ *    anchor** (`pid`) plus the pi `session` FILE path. The core treats the call
+ *    as blocking (it runs the test gate immediately after).
+ *  - `isAlive(record)` answers liveness FROM THE RECORD'S ANCHOR (PID/session),
+ *    never mtime, so a separate `status`/`do` process can re-derive liveness
+ *    from a fresh process WITHOUT re-launching the agent.
+ */
+/** The default pi CLI binary name (resolved on `PATH`). */
+export const DEFAULT_PI_BIN = 'pi';
+/**
+ * The pi adapter. Invocation: `pi [--model <model>] --print --session
+ * <full-path>.jsonl [extra]` run in the worktree with the work-agent prompt on
+ * stdin. The model is passed NATIVELY as `--model <model>` when set (ADR §13 —
+ * the routing intent dorfl controls); auth/keys stay pi's job, never
+ * dorfl's. Liveness: the PID is the authoritative "is it running?"
+ * signal; the recorded `session` file is the activity + audit pointer surfaced
+ * alongside it. NEVER mtime (ADR §5).
+ */
+export class PiHarness {
+    adapter = 'pi';
+    piBin;
+    extraArgs;
+    constructor(options = {}) {
+        this.piBin = options.piBin ?? DEFAULT_PI_BIN;
+        this.extraArgs = options.extraArgs ?? [];
+    }
+    /**
+     * Resolve the full session-FILE path for a launch. The CALLER normally
+     * generates this (via {@link generateSessionPath}) and passes it in
+     * `input.session` so the watcher knows it BEFORE launch; when omitted (e.g. a
+     * direct adapter call), generate a default under pi's per-cwd folder from the
+     * launch dir. Either way the result is absolute and ends `.jsonl`.
+     */
+    resolveSessionFile(input) {
+        return (input.session ?? generateSessionPath({ cwd: input.dir, id: input.slug }));
+    }
+    /** Build the pi argv: `[--model m] [extra] --print --session <file>`. */
+    buildArgs(input, sessionFile) {
+        // The model ROUTING intent (ADR §13): when set, pass it NATIVELY as
+        // `--model <model>`. dorfl only chooses the model; pi owns auth/keys.
+        const modelArgs = input.model !== undefined && input.model !== ''
+            ? ['--model', input.model]
+            : [];
+        // Non-interactive (`--print`): pi processes the prompt and exits. We pass
+        // the FULL session FILE path (`--session`, never `--session-dir`): pi
+        // creates+writes it there, it is visible to the dashboard, and nothing
+        // lands in the checkout. The operator's `extraArgs` still layer on.
+        return [
+            ...modelArgs,
+            ...this.extraArgs,
+            '--print',
+            '--session',
+            sessionFile,
+        ];
+    }
+    launch(input) {
+        const sessionFile = this.resolveSessionFile(input);
+        const args = this.buildArgs(input, sessionFile);
+        const result = spawnSync(this.piBin, args, {
+            // Spawn pi with cwd = the repo/worktree dir so the NEW session's header
+            // `cwd` groups it correctly in the dashboard (invariant #3) — the folder
+            // does NOT imply the repo.
+            cwd: input.dir,
+            encoding: 'utf8',
+            input: input.prompt,
+            env: input.env ?? process.env,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        if (result.error) {
+            throw new Error(`failed to spawn pi (${this.piBin}): ${result.error.message}`);
+        }
+        // Record the pi child's PID (the liveness anchor) + the exact session FILE
+        // path pi used (the pi-native activity + audit trail). Liveness later reads
+        // these — NOT a filesystem mtime (ADR §5).
+        const record = {
+            adapter: 'pi',
+            pid: result.pid,
+            command: [this.piBin, ...args].join(' '),
+            session: sessionFile,
+        };
+        const status = result.status ?? -1;
+        return {
+            ok: status === 0,
+            record,
+            detail: status === 0 ? undefined : (result.stderr ?? '').trim(),
+            // The agent's ANSWER (task `harness-agent-output`): the LAST assistant
+            // turn's text read from the session `.jsonl` pi just wrote — NOT piped
+            // stdout (which is drained). Shares `watch-session.ts`'s reader.
+            output: readLastAssistantText(sessionFile),
+        };
+    }
+    /**
+     * The ASYNC twin of {@link launch} — IDENTICAL semantics (same `--print
+     * --session <file>` invocation, same prompt on stdin, output still CAPTURED,
+     * same `LaunchResult` shape: PID anchor + session pointer + ok/detail), but
+     * launched NON-BLOCKING with `spawn` instead of the synchronous `spawnSync`.
+     * This is the one structural carve-out the `do --watch` observer needs (task
+     * `do-watch`): `spawnSync` blocks the event loop until pi exits, so NOTHING
+     * could tail the growing session `.jsonl` concurrently. `launchAsync` runs pi
+     * alongside the tailer; the WHOLE launch delta is `spawnSync` → `spawn`. The
+     * prompt is still fed on stdin and stdout/stderr are still captured; we read
+     * the `.jsonl` LOG, never piped stdout.
+     *
+     * ## Resolve on `exit`, NOT `close` (runner-hang fix)
+     *
+     * The promise resolves on the child's **`exit`** event (pi itself terminated),
+     * NOT `close`. `close` fires only once EVERY stdio pipe of the child is closed
+     * — which includes pipes INHERITED by any grandchild pi spawned (an MCP server,
+     * a model proxy, a subshell). If such a grandchild OUTLIVES pi holding the
+     * inherited stdout/stderr write end, `close` never fires and this promise never
+     * resolves — the `advance --watch` surface/triage/apply leg then finishes its
+     * work but its awaited launch hangs forever, burning a CI runner (and one of the
+     * `max-parallel` slots) until cancelled. `exit` fires the instant pi exits, so
+     * we key completion off pi's OWN death, not its descendants'. We still read the
+     * agent's answer from the `.jsonl` (final once pi exited, independent of
+     * stdout), then DESTROY our end of the stdio pipes so a leaked grandchild's
+     * inherited FDs release what they can. A lingering grandchild may still hold an
+     * OS pipe end open (keeping the event loop non-empty); the CLI verbs that call
+     * this path `process.exit(code)` after the awaited result, which is the
+     * belt-and-suspenders backstop bounding any such residual leak.
+     */
+    launchAsync(input) {
+        const sessionFile = this.resolveSessionFile(input);
+        const args = this.buildArgs(input, sessionFile);
+        const record = {
+            adapter: 'pi',
+            command: [this.piBin, ...args].join(' '),
+            session: sessionFile,
+        };
+        return new Promise((resolve, reject) => {
+            const child = spawn(this.piBin, args, {
+                // Same as `launch`: spawn in the repo/worktree dir so the session
+                // header `cwd` groups the dashboard correctly (invariant #3).
+                cwd: input.dir,
+                env: input.env ?? process.env,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            record.pid = child.pid; // the liveness anchor, recorded like spawnSync.
+            let stderr = '';
+            child.stderr?.on('data', (chunk) => {
+                stderr += chunk.toString('utf8');
+            });
+            // Output is CAPTURED (not piped through) — `--watch` reads the .jsonl log,
+            // not stdout. We drain stdout so the pipe never fills and stalls pi.
+            child.stdout?.on('data', () => { });
+            // Guard so `exit` and a late `error` never double-settle the promise.
+            let settled = false;
+            child.on('error', (err) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                reject(new Error(`failed to spawn pi (${this.piBin}): ${err.message}`));
+            });
+            // Resolve on `exit` (pi itself terminated), NOT `close`: `close` waits for
+            // EVERY child stdio pipe to close, including any INHERITED by a grandchild
+            // pi spawned that outlives it — which would hang this promise forever (see
+            // the doc-comment above). Then destroy our stdio ends to release the pipes.
+            child.on('exit', (code) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                // Release our end of the stdio pipes so a leaked grandchild's inherited
+                // FDs stop keeping our streams referenced; `unref` the child handle too.
+                child.stdout?.destroy();
+                child.stderr?.destroy();
+                child.stdin?.destroy();
+                child.unref?.();
+                const status = code ?? -1;
+                resolve({
+                    ok: status === 0,
+                    record,
+                    detail: status === 0 ? undefined : stderr.trim(),
+                    // Read the agent's ANSWER from the `.jsonl` at `exit` — the same
+                    // last-assistant-text read `launch` does at return (task
+                    // `harness-agent-output`); the process has exited so the log is final.
+                    output: readLastAssistantText(sessionFile),
+                });
+            });
+            // Feed the same prepared prompt on stdin, then close it (pi reads to EOF).
+            if (input.prompt !== undefined) {
+                child.stdin?.write(input.prompt);
+            }
+            child.stdin?.end();
+        });
+    }
+    /**
+     * Launch pi INTERACTIVELY (task `agent-interactive-launch`, decision #2): a
+     * FOREGROUND human session in `input.dir`. The whole delta from {@link launch}
+     * is the stdio contract:
+     *
+     *  - **NO `--print`** — a real interactive session the human types into (the
+     *    autonomous form is `pi --print …`, prompt on stdin, captured).
+     *  - **`stdio: 'inherit'`** — the human's terminal IS pi's terminal (foreground).
+     *  - **NO piped prompt** — the human drives; nothing is fed on stdin.
+     *  - **`--model <model>`** still flows in when set (ADR §13: the resolved
+     *    routing pins the human's starting model; they may switch inside pi).
+     *  - **`--session <path>`** is STILL passed so the human session is recorded /
+     *    dashboard-visible (audit trail), exactly as the autonomous path records it.
+     *
+     * It BLOCKS in the foreground until the human exits (`spawnSync` + inherited
+     * stdio), then returns their exit code. It is NOT a tracked job (decision #3):
+     * no `.dorfl-job.json`, no PID/liveness record, no gate — there is
+     * nothing to capture, so it returns only the exit code.
+     */
+    launchInteractive(input) {
+        const sessionFile = this.resolveSessionFile({
+            dir: input.dir,
+            slug: input.slug,
+            command: '',
+            session: input.session,
+        });
+        // The model ROUTING intent (ADR §13): when set, pass it NATIVELY as
+        // `--model <model>`. dorfl only chooses the model; pi owns auth/keys.
+        const modelArgs = input.model !== undefined && input.model !== ''
+            ? ['--model', input.model]
+            : [];
+        // NO `--print` (a real foreground session), but STILL `--session <path>` so
+        // the human session is recorded + dashboard-visible. The operator's
+        // `extraArgs` still layer on.
+        const args = [...modelArgs, ...this.extraArgs, '--session', sessionFile];
+        const result = spawnSync(this.piBin, args, {
+            // Run in the onboarded working tree so the session header `cwd` groups it
+            // correctly in the dashboard (invariant #3) and the human starts there.
+            cwd: input.dir,
+            // INHERIT the human's stdio: their terminal IS pi's terminal (foreground,
+            // interactive) — the opposite of the captured autonomous launch.
+            stdio: 'inherit',
+            env: input.env ?? process.env,
+        });
+        if (result.error) {
+            throw new Error(`failed to spawn pi (${this.piBin}): ${result.error.message}`);
+        }
+        return { exitCode: result.status ?? -1 };
+    }
+    isAlive(record) {
+        return pidAlive(record.pid);
+    }
+    /**
+     * The recorded pi session-FILE pointer for a job — the pi-native activity +
+     * audit trail surfaced alongside PID liveness. `undefined` when the record has
+     * no session pointer (e.g. a non-pi or legacy record). Existence on disk is
+     * reported separately so callers can distinguish "recorded but gone" from
+     * "never recorded".
+     */
+    sessionPointer(record) {
+        return record.session;
+    }
+}
+/**
+ * Does a job record carry a live pi session file on disk? Combines the recorded
+ * pointer with an `existsSync` check. This is the pi-native "is there an audit
+ * trail to look at?" signal — distinct from PID liveness, and STILL not mtime
+ * (we check existence, never modification time).
+ */
+export function piSessionExists(record) {
+    return record.session !== undefined && existsSync(record.session);
+}
+/**
+ * Read the LAST assistant message's text from the pi session `.jsonl` at
+ * `sessionFile` — the agent's final ANSWER, surfaced as `LaunchResult.output`
+ * (task `harness-agent-output`). Called by BOTH `launch` (at return) and
+ * `launchAsync` (at `close`), AFTER pi has exited so the log is complete.
+ *
+ * It REUSES `watch-session.ts`'s {@link lastAssistantText} (one `.jsonl` parser,
+ * not two). An absent file (pi never wrote it) yields `undefined`, as does a log
+ * with no assistant text — a read error is never thrown back into the launch.
+ */
+function readLastAssistantText(sessionFile) {
+    let jsonl;
+    try {
+        jsonl = readFileSync(sessionFile, 'utf8');
+    }
+    catch {
+        return undefined; // no session log on disk — no answer to surface.
+    }
+    return lastAssistantText(jsonl);
+}
+// Register the pi adapter so `status`/`do`/`gc` resolve liveness for `pi` jobs
+// to THIS adapter (PID + session pointer) rather than the null fallback. A
+// default-configured instance is sufficient for liveness (the binary/extra args
+// only matter for `launch`, which the core does via an explicit instance).
+registerHarness(new PiHarness());
+/**
+ * Build the harness that LAUNCHES jobs for a run, from config (ADR §5): `pi`
+ * ⇒ the pi adapter (invoking `config.piBin`); anything else ⇒ the null adapter
+ * (shelling out to `agentCmd`). This is the single place the core turns the
+ * declared `harness` selector into a concrete adapter, keeping pi specifics
+ * behind the seam.
+ */
+export function createHarness(options) {
+    if (options.harness === 'pi') {
+        return new PiHarness({ piBin: options.piBin });
+    }
+    return new NullHarness();
+}
+//# sourceMappingURL=pi-harness.js.map

package/dist/pi-harness.js.map

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

package/dist/placement.d.ts

@@ -0,0 +1,99 @@
+/**
+ * **The shared STAGING/POOL placement resolver** (prd
+ * `staging-pool-position-gate-and-trust-model`, task
+ * `runner-deterministic-slice-placement-policy-and-precedence`, governing ADR
+ * `placement-is-runner-deterministic-humanonly-is-agent-judgement`).
+ *
+ * Pure function from UNFORGEABLE inputs to a staging-vs-pool destination:
+ *
+ *   explicit operator flag  >  untrusted-origin forces STAGING  >
+ *     configured default  >  built-in
+ *
+ * It is the POSITIONAL twin of the untrusted-origin BUILD-propose rule in
+ * `integration-core.ts` (which decides MODE: `propose` vs `merge`): the same
+ * `originTrust:` stamp + the same "explicit operator override beats the trust
+ * force" shape, reused here to decide POSITION (which folder the runner lands
+ * the emitted ledger files in). The agent cannot influence either — both
+ * resolve runner-side from the stamped frontmatter + the resolved policy + the
+ * operator's explicit flag.
+ *
+ * LIFECYCLE-GENERIC. The folder names + the configured-default value are
+ * PARAMETERS (`slots`, `configuredDefault`), so the same resolver serves the
+ * TASK lifecycle (`tasksLandIn`: `pre-backlog`/`ready` — the POOL value was
+ * renamed `'backlog'` → `'todo'` → `'ready'`, ADR
+ * `rename-task-pool-folder-todo-to-ready`) AND the SPEC-
+ * placement lifecycle (`specsLandIn`: `pre-proposed`/`ready`) without forking. A future
+ * lifecycle (e.g. intake's lone-task) plugs its own `slots` in and reuses the
+ * exact precedence — no second implementation.
+ */
+/**
+ * Which side of the staging/pool split the runner chose. The CALLER maps this
+ * onto the lifecycle's concrete folder name via {@link PlacementSlots}.
+ *
+ * - `'staging'` — land in the staging area (tasks: `pre-backlog/`; prds:
+ *   `prds/proposed/`). Not in the agent pool; a human/runner promotion is needed to make
+ *   the item eligible. Review-without-PR review surface.
+ * - `'pool'` — land directly in the agent-eligible pool (tasks: `tasks/ready/`;
+ *   prds: `prds/ready/`). The trusted-fast-path landing.
+ */
+export type PlacementSide = 'staging' | 'pool';
+/**
+ * The two folder names a lifecycle uses for its staging/pool split. Supplied by
+ * the caller so this resolver stays lifecycle-generic (the TASK caller passes
+ * `{staging: 'pre-backlog', pool: 'tasks/ready'}`; the PRD-placement caller passes
+ * `{staging: 'prds/proposed', pool: 'prds/ready'}`).
+ */
+export interface PlacementSlots {
+    staging: string;
+    pool: string;
+}
+/** Inputs to {@link resolvePlacement}, in the precedence chain's order. */
+export interface ResolvePlacementInput {
+    /**
+     * The operator's EXPLICIT override (the TOP of the chain) — when set, it
+     * wins over the untrusted-origin force AND the configured default. Mirrors
+     * `integration-core.ts`'s `explicitMerge` "operator is present; CLI always
+     * wins, no special force-key" shape (the untrusted-origin trust signal
+     * gates pool entry, not the mode in this case). Unset (`undefined`) ⇒ this
+     * rung is skipped and the next one applies.
+     */
+    explicit?: PlacementSide;
+    /**
+     * The source's stamped `originTrust:` frontmatter (`trusted` | `untrusted` |
+     * absent ⇒ trusted by default). When `untrusted`, the resolver FORCES
+     * `staging` even on a "land in pool" repo — the positional analogue of the
+     * existing `untrusted-origin-forces-build-propose` rule. Unset / `trusted`
+     * ⇒ this rung is skipped (zero behaviour change for the normal path).
+     */
+    originTrust?: 'trusted' | 'untrusted';
+    /**
+     * The repo's resolved configured DEFAULT landing (`tasksLandIn` /
+     * `specsLandIn`). Caller resolves it like the existing `taskingIntegration`
+     * (flag > env > per-repo > global > built-in) and passes the result; this
+     * resolver just consumes it.
+     */
+    configuredDefault?: PlacementSide;
+}
+/** The resolved choice + which precedence rung won (for honest reporting). */
+export interface PlacementResult {
+    choice: PlacementSide;
+    reason: 'explicit' | 'untrusted-origin' | 'configured-default' | 'built-in';
+}
+/**
+ * Resolve the staging-vs-pool placement from unforgeable inputs, via the fixed
+ * precedence chain:
+ *
+ *   explicit  >  untrusted-origin ⇒ staging  >  configured default  >  built-in
+ *
+ * Pure: no I/O, no env reads — the caller resolves config + reads the
+ * frontmatter and passes both in. Reused by every lifecycle (task + prd
+ * placement + future intake variants) so a precedence change touches ONE place.
+ */
+export declare function resolvePlacement(input: ResolvePlacementInput): PlacementResult;
+/**
+ * Map a resolved {@link PlacementSide} onto the lifecycle's concrete folder
+ * name. The caller passes its lifecycle slots; this is sugar so the call site
+ * does not re-`if`-ladder the side ↔ folder mapping.
+ */
+export declare function placementFolder(slots: PlacementSlots, choice: PlacementSide): string;
+//# sourceMappingURL=placement.d.ts.map

package/dist/placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;IACtC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,aAAa,CAAC;CAClC;AAED,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,UAAU,GAAG,kBAAkB,GAAG,oBAAoB,GAAG,UAAU,CAAC;CAC5E;AAWD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,qBAAqB,GAC1B,eAAe,CAWjB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,aAAa,GACnB,MAAM,CAER"}

package/dist/placement.js

@@ -0,0 +1,67 @@
+/**
+ * **The shared STAGING/POOL placement resolver** (prd
+ * `staging-pool-position-gate-and-trust-model`, task
+ * `runner-deterministic-slice-placement-policy-and-precedence`, governing ADR
+ * `placement-is-runner-deterministic-humanonly-is-agent-judgement`).
+ *
+ * Pure function from UNFORGEABLE inputs to a staging-vs-pool destination:
+ *
+ *   explicit operator flag  >  untrusted-origin forces STAGING  >
+ *     configured default  >  built-in
+ *
+ * It is the POSITIONAL twin of the untrusted-origin BUILD-propose rule in
+ * `integration-core.ts` (which decides MODE: `propose` vs `merge`): the same
+ * `originTrust:` stamp + the same "explicit operator override beats the trust
+ * force" shape, reused here to decide POSITION (which folder the runner lands
+ * the emitted ledger files in). The agent cannot influence either — both
+ * resolve runner-side from the stamped frontmatter + the resolved policy + the
+ * operator's explicit flag.
+ *
+ * LIFECYCLE-GENERIC. The folder names + the configured-default value are
+ * PARAMETERS (`slots`, `configuredDefault`), so the same resolver serves the
+ * TASK lifecycle (`tasksLandIn`: `pre-backlog`/`ready` — the POOL value was
+ * renamed `'backlog'` → `'todo'` → `'ready'`, ADR
+ * `rename-task-pool-folder-todo-to-ready`) AND the SPEC-
+ * placement lifecycle (`specsLandIn`: `pre-proposed`/`ready`) without forking. A future
+ * lifecycle (e.g. intake's lone-task) plugs its own `slots` in and reuses the
+ * exact precedence — no second implementation.
+ */
+/**
+ * The BUILT-IN floor (the LOWEST rung): land in STAGING. Conservative — a new
+ * lifecycle that has not configured a landing yet stays gated by a human/runner
+ * promotion, never silently auto-eligible. The tracer task
+ * `pre-backlog-staging-folder-and-promote-step-a` also lands staged, so this
+ * preserves zero behaviour change for repos that do not opt into a default.
+ */
+const BUILT_IN_FLOOR = 'staging';
+/**
+ * Resolve the staging-vs-pool placement from unforgeable inputs, via the fixed
+ * precedence chain:
+ *
+ *   explicit  >  untrusted-origin ⇒ staging  >  configured default  >  built-in
+ *
+ * Pure: no I/O, no env reads — the caller resolves config + reads the
+ * frontmatter and passes both in. Reused by every lifecycle (task + prd
+ * placement + future intake variants) so a precedence change touches ONE place.
+ */
+export function resolvePlacement(input) {
+    if (input.explicit !== undefined) {
+        return { choice: input.explicit, reason: 'explicit' };
+    }
+    if (input.originTrust === 'untrusted') {
+        return { choice: 'staging', reason: 'untrusted-origin' };
+    }
+    if (input.configuredDefault !== undefined) {
+        return { choice: input.configuredDefault, reason: 'configured-default' };
+    }
+    return { choice: BUILT_IN_FLOOR, reason: 'built-in' };
+}
+/**
+ * Map a resolved {@link PlacementSide} onto the lifecycle's concrete folder
+ * name. The caller passes its lifecycle slots; this is sugar so the call site
+ * does not re-`if`-ladder the side ↔ folder mapping.
+ */
+export function placementFolder(slots, choice) {
+    return choice === 'staging' ? slots.staging : slots.pool;
+}
+//# sourceMappingURL=placement.js.map

package/dist/placement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA2DH;;;;;;GAMG;AACH,MAAM,cAAc,GAAkB,SAAS,CAAC;AAEhD;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC/B,KAA4B;IAE5B,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO,EAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAC,CAAC;IACrD,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,KAAK,WAAW,EAAE,CAAC;QACvC,OAAO,EAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAC,CAAC;IACxD,CAAC;IACD,IAAI,KAAK,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAC3C,OAAO,EAAC,MAAM,EAAE,KAAK,CAAC,iBAAiB,EAAE,MAAM,EAAE,oBAAoB,EAAC,CAAC;IACxE,CAAC;IACD,OAAO,EAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU,EAAC,CAAC;AACrD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC9B,KAAqB,EACrB,MAAqB;IAErB,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;AAC1D,CAAC"}