@rasensio/aidlc 1.66.0 → 1.72.0

package/dist/autopilot/driver.js

@@ -15,7 +15,12 @@
  *
  * @module
  */
+import { mapUnits } from '../cost/providers/codex.js';
+import { microToUsd, priceUnits } from '../cost/rates.js';
+import { MODEL_ID_RE } from '../cost/types.js';
+import { REASON_MAX, RESET_WAIT_MAX_MS, codexEnd, emptyCodexProgress, firstLine, readClaudeResult, readCodexEvents, refusalSuffix, resetAt, stoppedBy, summaryLines, } from './result.js';
 import { LEGACY_STOPS, pauseEnv, pendingReview, stopsInForce } from './stops.js';
+import { OUTCOME_SCHEMA, UUID_RE, budgetCents, resumePrompt, typedArgv, typedHarness, withOutcomeContract, } from './typed.js';
 const RATE_LIMIT_RE = /rate limit|\b429\b|secondary rate/i;
 const BACKOFF_FIRST_MS = 5 * 60 * 1000;
 const BACKOFF_MAX_MS = 2 * 60 * 60 * 1000;
@@ -39,16 +44,27 @@ function makeIO(ctx) {
             ctx.say(`[dry-run] ${opts.cwd ? `(in ${opts.cwd}) ` : ''}${[cmd, ...args].join(' ')}`);
             return { status: 0, stdout: '', stderr: '', dry: true };
         }
-        const r = ctx.run(cmd, args, opts);
-        if (RATE_LIMIT_RE.test(`${r.stdout}\n${r.stderr}`)) {
+        const r = ctx.run(cmd, args, opts.cwd === undefined ? {} : { cwd: opts.cwd });
+        if (opts.echoes !== true && RATE_LIMIT_RE.test(`${r.stdout}\n${r.stderr}`)) {
             throw new RateLimited(`${cmd} ${args.slice(0, 2).join(' ')}: ${(r.stderr || r.stdout).trim().split('\n')[0]}`);
         }
         return r;
     };
-    const cli = (args) => call(ctx.cli[0], [...ctx.cli.slice(1), ...args], { cwd: ctx.repo });
+    const cli = (args, opts = {}) => call(ctx.cli[0], [...ctx.cli.slice(1), ...args], { cwd: ctx.repo, ...opts });
     return { call, cli };
 }
 const fail = (r) => (r.stderr || r.stdout || `exit ${r.status}`).trim().split('\n').slice(-1)[0];
+/**
+ * Git's whole message on one line, at most 400 characters. `fail` keeps the last
+ * line, and a refused merge's last line is `Aborting` — the files it would
+ * overwrite are the lines before (autopilot-merge-refusal-is-not-a-conflict/AC-7).
+ */
+const gitMessage = (r) => (r.stderr.trim() ? r.stderr : r.stdout || `exit ${r.status}`)
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .join(' ')
+    .slice(0, 400);
 /**
  * Why `aidlc transition --json` refused: each violation, where `fail` alone would keep
  * the last line — a "next step" naming no cause, which is all a halted queue logged
@@ -158,16 +174,13 @@ const itemPauses = (item) => pauseEnv(itemStops(item), item.approved ?? []);
  * fails later prints a banner first, which names nothing (codex-preset-removed-flag/AC-6, AC-10).
  */
 export const LAUNCH_FAILURE_MS = 30_000;
-const REASON_MAX = 200;
 /**
  * The first non-blank line of `text`, terminal escapes and control characters removed,
  * at most 200 characters; null when there is none (codex-preset-removed-flag/AC-12).
  * The first line, not `fail`'s last: for an argument error the last is the usage line.
  */
 export function firstOutputLine(text) {
-    const plain = text.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
-    const line = plain.split('\n').map((l) => l.trim()).find((l) => l !== '');
-    return line === undefined ? null : line.slice(0, REASON_MAX);
+    return firstLine(text, REASON_MAX);
 }
 /**
  * The park reason for an agent that failed to launch, or null when it did not or the
@@ -183,9 +196,92 @@ function launchFailure(ctx, item) {
     const line = firstOutputLine(exit.output);
     return line === null ? `agent failed to launch (${how}) with no output` : `agent failed to launch (${how}): ${line}`;
 }
-function launchAgent(ctx, item, prompt) {
+/**
+ * The reset time of the latest session-limit wait still in force, or null. While there is
+ * one, no agent is launched for any item: the limit is the account's, so every launch
+ * would hit it (autopilot-reads-agent-result/AC-26).
+ */
+export function launchBlocked(state, now) {
+    let latest = null;
+    for (const i of state.items) {
+        const w = i.resume_wait;
+        const until = w?.kind === 'session-limit' ? Date.parse(w.until) : Number.NaN;
+        if (until > now && (latest === null || until > latest))
+            latest = until;
+    }
+    // Re-rendered, not repeated: the stored text came from a file that can be edited.
+    return latest === null ? null : new Date(latest).toISOString();
+}
+/** The park reason when the item's spend has used up its cap (autopilot-reads-agent-result/AC-7, AC-18, AC-20). */
+const capReached = (cap, spentMicro) => `cost cap ${cap} USD reached — spent ${microToUsd(spentMicro)}`;
+const logFile = (ctx, item) => `${ctx.paths.logs}/${item.name}.log`;
+/**
+ * Launch the item's agent. False when nothing was launched: a session-limit wait is in
+ * force — the net under each caller's own check (design D7) — or the item was parked,
+ * for a budget under a cent (autopilot-reads-agent-result/AC-18) or a session id that is
+ * not a UUID (AC-33).
+ *
+ * A preset command is launched typed (AC-1, AC-2): the outcome contract in the prompt
+ * (AC-5), the flags, the budget (AC-17), and the launch recorded on the item with where
+ * its output starts, so a pass in any process reads its result (AC-32). A custom
+ * command is launched exactly as configured, and clears any earlier mark (AC-3, AC-31).
+ *
+ * @param budget - the run's item budget, which a park here must reach.
+ */
+function launchAgent(ctx, io, state, item, prompt, budget, resume) {
+    if (launchBlocked(state, ctx.now()) !== null)
+        return false;
+    const cap = ctx.config?.cost_cap_usd;
+    const spent = item.spent_micro_usd ?? 0;
+    const cents = typeof cap === 'number' ? budgetCents(cap, spent) : null;
+    if (typeof cap === 'number' && (cents ?? 0) < 1) {
+        park(ctx, io, state, item, capReached(cap, spent), budget);
+        return false;
+    }
     const command = ctx.config?.agent_command ?? [];
-    const argv = command.map((a) => (a === '{prompt}' ? prompt : a));
+    const harness = typedHarness(command);
+    const log = logFile(ctx, item);
+    let argv;
+    let launch;
+    if (harness === null) {
+        argv = command.map((a) => (a === '{prompt}' ? prompt : a));
+    }
+    else {
+        const outcomeFile = `${ctx.paths.dir}/outcomes/${item.name}.json`;
+        const schemaFile = `${ctx.paths.dir}/outcome-schema.json`;
+        const typed = typedArgv(command, {
+            harness,
+            prompt: withOutcomeContract(prompt),
+            schemaFile,
+            outcomeFile,
+            maxBudgetCents: harness === 'claude' ? cents : null,
+            resume: resume?.session ?? null,
+        });
+        if (typed === null) {
+            park(ctx, io, state, item, `${resume?.label ?? 'session'} — no usable session id`, budget);
+            return false;
+        }
+        argv = typed;
+        launch = {
+            harness,
+            at: new Date(ctx.now()).toISOString(),
+            ...(typeof cap === 'number' ? { cap_usd: cap } : {}),
+            log_offset: 0,
+            ...(harness === 'codex' ? { outcome_file: outcomeFile, progress: emptyCodexProgress() } : {}),
+            ...(resume === undefined ? {} : { resumes: resume.session }),
+        };
+        // A resume continues the thread's rollout, which sits in its first launch's day
+        // directory, and Codex reports the model there once (design D10).
+        if (resume?.from?.harness === 'codex') {
+            if (resume.from.model !== undefined)
+                launch.model = resume.from.model;
+            launch.rollout_at = resume.from.rollout_at ?? resume.from.at;
+        }
+        if (harness === 'codex' && !ctx.dryRun) {
+            ctx.fs.write(schemaFile, `${JSON.stringify(OUTCOME_SCHEMA, null, 2)}\n`);
+            ctx.fs.write(outcomeFile, '');
+        }
+    }
     const env = {
         AIDLC_UNATTENDED: '1',
         AIDLC_AGENT: ctx.config?.agent_platform ?? 'claude-code',
@@ -193,10 +289,21 @@ function launchAgent(ctx, item, prompt) {
         AIDLC_PAUSE_AFTER: itemPauses(item),
     };
     if (ctx.dryRun) {
-        ctx.say(`[dry-run] (in ${item.worktree}) launch agent: ${argv[0]} … (${argv.length} args)`);
-        return;
+        ctx.say(`[dry-run] (in ${item.worktree}) launch agent: ${argv[0]} … (${argv.length} args${harness === null ? '' : `, typed ${harness}`})`);
+        return true;
+    }
+    if (launch === undefined) {
+        delete item.launch;
     }
-    item.pid = ctx.spawnDetached(argv, { cwd: item.worktree, env, logFile: `${ctx.paths.logs}/${item.name}.log` });
+    else {
+        // Read before the spawn, not after: only this item's agent writes its log, and it is
+        // not running yet, so nothing can write in between.
+        launch.log_offset = ctx.fs.size?.(log) ?? 0;
+        if (launch.harness === 'codex')
+            launch.read_offset = launch.log_offset;
+        item.launch = launch;
+    }
+    item.pid = ctx.spawnDetached(argv, { cwd: item.worktree, env, logFile: log });
     item.pid_started_at = new Date(ctx.now()).toISOString();
     const id = ctx.identify?.(item.pid);
     if (id) {
@@ -205,6 +312,7 @@ function launchAgent(ctx, item, prompt) {
         item.pid_ns = id.ns;
     }
     tell(ctx, item, `agent started (pid ${item.pid})`);
+    return true;
 }
 function drop(state, item, budget) {
     state.items = state.items.filter((i) => i !== item);
@@ -212,7 +320,7 @@ function drop(state, item, budget) {
     budget?.onFinish(item.name);
 }
 function park(ctx, io, state, item, reason, budget) {
-    const r = io.cli(['roadmap', 'park', item.name, '--reason', reason]);
+    const r = io.cli(['roadmap', 'park', item.name, '--reason', reason], { echoes: true });
     if (r.status !== 0) {
         failItem(ctx, state, item, `park failed: ${fail(r)}`);
         tell(ctx, item, `could not park — ${item.error}`);
@@ -223,10 +331,16 @@ function park(ctx, io, state, item, reason, budget) {
     notice(ctx, 'item parked', `${item.name}: ${reason}`);
     drop(state, item, budget);
 }
-/** The instance's `current_phase` in its worktree, or null when unreadable. Shared with the view. */
+/**
+ * The instance's `current_phase` in its worktree, or null when unreadable. Shared with the
+ * view. Only a phase-shaped name: the agent writes this file, and the phase reaches park
+ * reasons committed to the roadmap (autopilot-reads-agent-result/AC-29).
+ */
 export function instancePhase(read, item) {
     const yaml = read(`${item.worktree}/.aidlc/state/${item.name}/instance.yaml`) ?? '';
-    return /^current_phase:\s*(\S+)/m.exec(yaml)?.[1] ?? null;
+    // A name of word characters and hyphens ending at a space or the line's end: what `\S+`
+    // read for every real phase — a trailing comment too — without its escapes.
+    return /^current_phase:[ \t]*([A-Za-z0-9_-]{1,32})(?=\s|$)/m.exec(yaml)?.[1] ?? null;
 }
 function currentPhase(ctx, item) {
     return instancePhase(ctx.fs.read, item);
@@ -252,10 +366,225 @@ function awaitIfPaused(ctx, item) {
     notice(ctx, 'review needed', `${item.name}: paused after ${phase} — aidlc autopilot approve ${item.name}`);
     return true;
 }
+/** How much of a log one read takes, and one pass at most (design, "While the agent runs"). */
+const CHUNK_BYTES = 1024 * 1024;
+const PASS_READ_BYTES = 8 * CHUNK_BYTES;
+/**
+ * Fold what a Codex launch appended to the item's log since the last pass into its
+ * progress, at most 8 MiB a pass (autopilot-reads-agent-result/AC-20). Offsets are bytes,
+ * and a chunk is decoded only up to its last newline byte, so a character split across
+ * two chunks is never miscounted. A line still being written waits for the next pass —
+ * unless `final`, when the agent has exited and the line will never be finished. A line
+ * longer than a chunk is skipped; its tail fails to parse and is counted unreadable.
+ *
+ * @returns whether the whole log has been folded.
+ */
+function followCodex(ctx, item, launch, final) {
+    const readRange = ctx.fs.readRange;
+    if (readRange === undefined)
+        return true;
+    const progress = (launch.progress ??= emptyCodexProgress());
+    const log = logFile(ctx, item);
+    let offset = launch.read_offset ?? launch.log_offset;
+    for (let left = PASS_READ_BYTES; left > 0;) {
+        const want = Math.min(CHUNK_BYTES, left);
+        const chunk = readRange(log, offset, want);
+        if (chunk.length === 0)
+            break;
+        const newline = chunk.lastIndexOf(0x0a);
+        if (newline === -1) {
+            if (chunk.length === CHUNK_BYTES) {
+                offset += chunk.length;
+                left -= chunk.length;
+                continue;
+            }
+            // The end of the log, mid-line: finished only when the agent will write no more.
+            if (final && chunk.length < want) {
+                readCodexEvents(chunk.toString('utf8'), progress);
+                offset += chunk.length;
+            }
+            break;
+        }
+        readCodexEvents(chunk.toString('utf8', 0, newline + 1), progress);
+        offset += newline + 1;
+        left -= newline + 1;
+    }
+    launch.read_offset = offset;
+    return offset >= (ctx.fs.size?.(log) ?? offset);
+}
+/** Rollout lookups for a thread's model before its launch is treated as unpriced (design D10). */
+const MODEL_LOOKUPS = 3;
+/** The model a Codex launch used, looked up at most three times, kept once found. */
+function codexModelOf(ctx, launch) {
+    if (launch.model !== undefined)
+        return launch.model;
+    const thread = launch.progress?.thread_id ?? null;
+    if (thread === null || ctx.codexModel === undefined || (launch.model_lookups ?? 0) >= MODEL_LOOKUPS)
+        return null;
+    launch.model_lookups = (launch.model_lookups ?? 0) + 1;
+    const model = ctx.codexModel(thread, launch.rollout_at ?? launch.at);
+    // The shape the cost ledger accepts, and nothing else reaches state or a message (AC-21).
+    if (model !== null && MODEL_ID_RE.test(model))
+        launch.model = model;
+    return launch.model ?? null;
+}
+/**
+ * Whether the model lookup has given up for good, which is when "cannot be read" is said
+ * (AC-21) — after three tries, or at once when a turn completed with no usable thread id,
+ * since `thread.started` comes first or never.
+ */
+const modelLookupGaveUp = (launch) => launch.model === undefined &&
+    ((launch.model_lookups ?? 0) >= MODEL_LOOKUPS || (launch.progress?.thread_id == null && (launch.progress?.turns ?? 0) > 0));
+/**
+ * What a Codex launch's summed `turn.completed` usage costs, in micro-USD, priced as the
+ * Codex cost provider prices a turn — cached input counted inside input, not on top of
+ * it — at the effective rate for its model; null when it cannot be priced
+ * (autopilot-reads-agent-result/AC-20, AC-21). The one place the reading of Codex's
+ * usage lives: if the release run finds it a running total, this changes and nothing
+ * else does (design, Risk 1).
+ */
+export function launchUsageMicro(ctx, launch) {
+    const usage = launch.progress?.usage;
+    if (usage === undefined)
+        return null;
+    const model = codexModelOf(ctx, launch);
+    const rates = ctx.rates?.();
+    if (model === null || rates === undefined)
+        return null;
+    const units = mapUnits({
+        input_tokens: usage.input,
+        cached_input_tokens: usage.cached,
+        cache_write_input_tokens: 0,
+        output_tokens: usage.output,
+        reasoning_output_tokens: 0,
+        total_tokens: usage.input + usage.output,
+    }, model);
+    const micro = priceUnits(units, rates);
+    // A figure the state file cannot hold is no figure: JSON writes Infinity as null, and the
+    // next load would read the spend as 0.
+    return micro !== null && Number.isSafeInteger(micro) ? micro : null;
+}
+/** What a running launch's session amounts to so far: a Codex launch's folded events; nothing for Claude. */
+function sessionSoFar(launch, costMicro) {
+    return launch.harness === 'codex' && launch.progress !== undefined ? codexEnd(launch.progress, null, costMicro) : null;
+}
+/**
+ * Stop a running Codex launch whose priced usage, on top of the item's recorded spend,
+ * has reached the cap less the 10% margin (autopilot-reads-agent-result/AC-20). Codex has
+ * no budget flag, so this is the cap inside its run. Usage that cannot be priced is said
+ * once and stops nothing (AC-21).
+ *
+ * @returns whether it stopped and parked the item.
+ */
+function stoppedAtCap(ctx, io, state, item, launch, cap, budget) {
+    if ((launch.progress?.turns ?? 0) === 0)
+        return false;
+    const priced = launchUsageMicro(ctx, launch);
+    if (priced === null) {
+        noteUnpriced(ctx, item, launch);
+        return false;
+    }
+    const spent = (item.spent_micro_usd ?? 0) + priced;
+    if (spent < Math.round(cap * 1e6) - Math.round(cap * 1e5))
+        return false;
+    if (!ctx.dryRun && item.pid !== null)
+        ctx.kill(item.pid);
+    appendSummary(ctx, item, summaryLines(sessionSoFar(launch, priced), 'stopped by autopilot at the cost cap'));
+    park(ctx, io, state, item, capReached(cap, spent), budget);
+    return true;
+}
+/**
+ * Say once for the item that its Codex spend cannot be priced, and where a rate goes
+ * (autopilot-reads-agent-result/AC-21). Only once it is known why: the model is read and
+ * the rate table has nothing for it, or the lookup has given up — not while the rollout
+ * may still turn up.
+ */
+function noteUnpriced(ctx, item, launch) {
+    if (item.unpriced_noted === true)
+        return;
+    const why = launch.model !== undefined ? `no rate for ${launch.model}` : modelLookupGaveUp(launch) ? "the session's model cannot be read" : null;
+    if (why === null)
+        return;
+    item.unpriced_noted = true;
+    tell(ctx, item, `Codex spend cannot be priced: ${why}; a rate for its model goes under cost.rates in .aidlc/config.yaml — until then this run is not stopped for cost`);
+}
+/** How much of a Claude launch's segment is read for its result, and of a Codex outcome file. */
+const RESULT_TAIL_BYTES = 1024 * 1024;
+const OUTCOME_FILE_BYTES = 64 * 1024;
+/**
+ * Read how a typed launch's session ended, once: store it on the launch, add its cost to
+ * the item's spend, and append the summary to the item's log. Read from the offset the
+ * launch recorded, so it is this launch's result whichever process saw it exit
+ * (autopilot-reads-agent-result/AC-6, AC-19, AC-28, AC-32).
+ *
+ * @returns false while a Codex launch's log is still being folded: its end is decided
+ *   only once everything it wrote has been read, over several passes if need be.
+ */
+function endSession(ctx, item, launch) {
+    const { readRange, size } = ctx.fs;
+    if (readRange === undefined || size === undefined) {
+        launch.end = null;
+        return true;
+    }
+    const log = logFile(ctx, item);
+    let end;
+    if (launch.harness === 'claude') {
+        const total = size(log);
+        const start = Math.max(launch.log_offset, total - RESULT_TAIL_BYTES);
+        end = readClaudeResult(readRange(log, start, Math.max(0, total - start)).toString('utf8'));
+    }
+    else {
+        if (!followCodex(ctx, item, launch, true))
+            return false;
+        const outcome = launch.outcome_file === undefined ? null : readRange(launch.outcome_file, 0, OUTCOME_FILE_BYTES).toString('utf8');
+        end = codexEnd(launch.progress ?? emptyCodexProgress(), outcome, launchUsageMicro(ctx, launch));
+    }
+    launch.end = end;
+    if (end !== null)
+        recordSpend(item, end);
+    appendSummary(ctx, item, summaryLines(end));
+    return true;
+}
+/**
+ * Add a session's cost to the item's spend (autopilot-reads-agent-result/AC-19). A
+ * session already on record adds only its increase. Claude reports a session's cost;
+ * a resumed Codex launch's usage counts only its own turns, so a Codex session's cost
+ * is what was recorded plus this launch's (design, Risk 1). Unpriced adds nothing.
+ */
+function recordSpend(item, end) {
+    if (end.cost_micro === null)
+        return;
+    const costs = item.session_costs ?? {};
+    const id = end.session_id;
+    const previous = id === null ? 0 : costs[id] ?? 0;
+    const sessionCost = end.harness === 'codex' ? previous + end.cost_micro : end.cost_micro;
+    item.spent_micro_usd = (item.spent_micro_usd ?? 0) + Math.max(0, sessionCost - previous);
+    if (id !== null) {
+        costs[id] = Math.max(previous, sessionCost);
+        item.session_costs = costs;
+    }
+}
+/** Append lines to the item's log, on a line of their own. Nothing in a dry run. */
+function appendSummary(ctx, item, lines) {
+    const { append, readRange, size } = ctx.fs;
+    if (ctx.dryRun || append === undefined)
+        return;
+    const log = logFile(ctx, item);
+    const total = size?.(log) ?? 0;
+    const last = total > 0 ? readRange?.(log, total - 1, 1) : undefined;
+    const lead = last !== undefined && last.length === 1 && last[0] !== 0x0a ? '\n' : '';
+    append(log, `${lead}${lines.join('\n')}\n`);
+}
 function advanceBuilding(ctx, io, state, item, budget) {
     if (item.pid && ctx.isAlive(item.pid)) {
+        const launch = item.launch;
+        if (launch?.harness === 'codex')
+            followCodex(ctx, item, launch, false);
         const cap = ctx.config?.cost_cap_usd;
         if (typeof cap === 'number') {
+            if (launch?.harness === 'codex' && stoppedAtCap(ctx, io, state, item, launch, cap, budget))
+                return;
+            // Every agent, typed or not: the ledger's view of the cap stands (autopilot-reads-agent-result/AC-22).
             const r = io.cli(['cost', item.name, '--json']);
             let micro = 0;
             try {
@@ -267,19 +596,44 @@ function advanceBuilding(ctx, io, state, item, budget) {
             if (micro > cap * 1e6) {
                 if (!ctx.dryRun)
                     ctx.kill(item.pid);
+                if (launch !== undefined) {
+                    const priced = launch.harness === 'codex' ? launchUsageMicro(ctx, launch) : null;
+                    appendSummary(ctx, item, summaryLines(sessionSoFar(launch, priced), 'stopped by autopilot: aidlc cost passed the cap'));
+                }
                 park(ctx, io, state, item, `cost cap ${cap} USD exceeded`, budget);
             }
         }
         return;
     }
+    // First, once per launch: every session that ended gets its summary, one that parked
+    // itself included, and a paused item's spend is on record before an approval works
+    // out the relaunch's budget (autopilot-reads-agent-result/AC-19, AC-28).
+    if (item.launch !== undefined && item.launch.end === undefined && !endSession(ctx, item, item.launch))
+        return;
     if (ctx.fs.exists(`${ctx.repo}/.aidlc/roadmap/hold/${item.file}`)) {
         tell(ctx, item, 'the agent parked it');
         notice(ctx, 'item parked', `${item.name}: parked by its agent — the reason is in the item's history`);
         drop(state, item, budget);
         return;
     }
-    if (awaitIfPaused(ctx, item))
+    // After hold/: a person who parked a waiting item by hand has the last word.
+    if (item.resume_wait !== undefined) {
+        resumeWhenDue(ctx, io, state, item, item.resume_wait, budget);
+        return;
+    }
+    if (awaitIfPaused(ctx, item)) {
+        // The result led to a pause; after the approval it must not decide again (design D8).
+        delete item.launch;
+        return;
+    }
+    // Before the launch-failure check: a typed launch that exited inside 30 seconds but
+    // wrote a result is decided by it (autopilot-reads-agent-result/AC-6, AC-14).
+    const end = item.launch?.end;
+    if (item.launch !== undefined && end !== undefined && end !== null) {
+        decideFromResult(ctx, io, state, item, item.launch, end, budget);
         return;
+    }
+    // Untyped, or no readable result: as before (autopilot-reads-agent-result/AC-15, AC-31).
     // Before the phase: a relaunch that never started would otherwise push and open
     // the pull request as if it had finished (codex-preset-removed-flag/AC-9).
     const launch = launchFailure(ctx, item);
@@ -287,19 +641,197 @@ function advanceBuilding(ctx, io, state, item, budget) {
         park(ctx, io, state, item, launch, budget);
         return;
     }
+    byPhase(ctx, io, state, item, budget);
+}
+const stopLabel = (kind) => kind === 'connection' ? 'connection dropped' : kind === 'ended-early' ? 'ended before the release boundary' : 'session limit';
+const waitingLine = (until, session) => `waiting for the session limit to reset at ${until}, then resuming session ${session}`;
+/**
+ * A session that stopped on a dropped connection or a session limit is resumed once with
+ * its own session id — at the next pass, or once the limit resets — and parked when it
+ * cannot be (autopilot-reads-agent-result/AC-23..AC-27, AC-33). The item stays `building`
+ * with no agent while it waits (AC-26).
+ */
+function decideResume(ctx, io, state, item, launch, end, error, stop, budget) {
+    const label = stopLabel(stop);
+    const line = firstLine(error, REASON_MAX) ?? 'error';
+    // A resume that stops again is AC-27's whether or not it reported its id again: a
+    // resumed Codex thread writes no second `thread.started`.
+    const resumed = launch.resumes !== undefined && UUID_RE.test(launch.resumes) ? launch.resumes : null;
+    const id = end.session_id ?? resumed;
+    if (launch.resumes !== undefined && id !== null) {
+        park(ctx, io, state, item, `${label} — resumed once, stopped again: ${line}; session ${id}`, budget);
+        return;
+    }
+    if (id === null) {
+        park(ctx, io, state, item, `${label} — no usable session id: ${line}`, budget);
+        return;
+    }
+    const now = ctx.now();
+    item.pid = null;
+    if (stop === 'connection') {
+        item.resume_wait = { kind: 'connection', until: new Date(now).toISOString(), session: id };
+        tell(ctx, item, `connection dropped — resuming session ${id} at the next pass`);
+        return;
+    }
+    const until = resetAt(error, now);
+    const at = new Date(until).toISOString();
+    // A weekly limit: hours of a build slot held, and every other launch blocked, for one resume (AC-25).
+    if (until - now > RESET_WAIT_MAX_MS) {
+        park(ctx, io, state, item, `session limit — resets ${at}; session ${id}`, budget);
+        return;
+    }
+    item.resume_wait = { kind: 'session-limit', until: at, session: id };
+    tell(ctx, item, waitingLine(at, id));
+}
+/**
+ * A waiting item, each pass: wait on until its time, then resume its session with the
+ * same preset flags and a budget worked out again (autopilot-reads-agent-result/AC-23,
+ * AC-24, AC-26). The id has been in `state.json` since it was read, so it is checked
+ * again here (AC-33); a resume needs the harness that started the session.
+ */
+function resumeWhenDue(ctx, io, state, item, wait, budget) {
+    const label = stopLabel(wait.kind);
+    // Before the id is printed anywhere: it came back from a file that can be edited.
+    if (!UUID_RE.test(wait.session)) {
+        delete item.resume_wait;
+        park(ctx, io, state, item, `${label} — no usable session id`, budget);
+        return;
+    }
+    const until = Date.parse(wait.until);
+    if (ctx.now() < until) {
+        // The same text keeps the time it was first said, so the view shows how long it has waited.
+        tell(ctx, item, waitingLine(new Date(until).toISOString(), wait.session));
+        return;
+    }
+    const blocked = launchBlocked(state, ctx.now());
+    if (blocked !== null) {
+        tell(ctx, item, `${label} — resuming session ${wait.session} waits for the session limit to reset at ${blocked}`);
+        return;
+    }
+    delete item.resume_wait;
+    const from = item.launch;
+    if (from === undefined || typedHarness(ctx.config?.agent_command ?? []) !== from.harness) {
+        park(ctx, io, state, item, `${label} — the agent command changed since the session stopped; session ${wait.session}`, budget);
+        return;
+    }
+    tell(ctx, item, `${label} — resuming session ${wait.session}`);
+    // The stopped session's claim outlives it by the 60-minute staleness, and a resume may
+    // run under another id, whose `aidlc claim` it would refuse. From the worktree: an
+    // in-flight instance's state is on its branch, and `release` refuses an instance it
+    // cannot find. `echoes`: it prints the instance name (unattended-agent-ends-turn-to-wait/AC-7).
+    const released = io.call(ctx.cli[0], [...ctx.cli.slice(1), 'release', item.name], { cwd: item.worktree, echoes: true });
+    if (released.status !== 0) {
+        const said = `${label} — could not release the claim: ${fail(released)}; resuming anyway`;
+        tell(ctx, item, said);
+        // The item's own log too: it is where the resumed session's summary lands next.
+        appendSummary(ctx, item, [`[autopilot] ${said}`]);
+    }
+    launchAgent(ctx, io, state, item, resumePrompt(item, label), budget, { session: wait.session, label, from });
+}
+/** At deployment, the pull request; short of it, parked. `suffix` follows the park reason. */
+function byPhase(ctx, io, state, item, budget, suffix = '') {
     const phase = currentPhase(ctx, item);
     if (phase !== 'deployment') {
-        park(ctx, io, state, item, `agent exited before the release boundary (phase ${phase ?? 'unknown'})`, budget);
+        park(ctx, io, state, item, `agent exited before the release boundary (phase ${phase ?? 'unknown'})${suffix}`, budget);
         return;
     }
     openPullRequest(ctx, io, state, item);
 }
+/**
+ * What a typed session's own result says happens next — first match wins
+ * (autopilot-reads-agent-result/AC-7..AC-13). Every park decided here ends with the
+ * refused tool calls, after any other suffix (AC-16). Only the pull request keeps the
+ * launch's end: a failed push resumed by `aidlc autopilot run` decides the same way
+ * again; every other row parks the item or waits to resume it (design D8).
+ */
+function decideFromResult(ctx, io, state, item, launch, end, budget) {
+    const refusals = refusalSuffix(end);
+    const parkWith = (reason) => park(ctx, io, state, item, `${reason}${refusals}`, budget);
+    const spent = item.spent_micro_usd ?? 0;
+    if (end.limit === 'budget') {
+        // The cap the budget came from, so a config edited mid-run cannot leave the reason without one.
+        parkWith(launch.cap_usd === undefined ? `budget reached — spent ${microToUsd(spent)}` : capReached(launch.cap_usd, spent));
+        return;
+    }
+    if (end.limit === 'turns') {
+        parkWith(`turn limit reached after ${end.turns ?? 'an unknown number of'} turns`);
+        return;
+    }
+    if (end.error !== null) {
+        const stop = stoppedBy(end.error);
+        if (stop !== null) {
+            decideResume(ctx, io, state, item, launch, end, end.error, stop, budget);
+            return;
+        }
+        parkWith(`agent session failed: ${firstLine(end.error, REASON_MAX) ?? 'error'}`);
+        return;
+    }
+    const early = (reason) => endedEarly(ctx, io, state, item, launch, end, reason, budget);
+    if (end.outcome === null) {
+        // `byPhase`, with the early ending where it would park.
+        const phase = currentPhase(ctx, item);
+        if (phase === 'deployment')
+            openPullRequest(ctx, io, state, item);
+        else
+            early(`agent exited before the release boundary (phase ${phase ?? 'unknown'}) — the agent reported no outcome`);
+        return;
+    }
+    const { outcome, reason } = end.outcome;
+    const phase = currentPhase(ctx, item) ?? 'unknown';
+    if (outcome === 'parked') {
+        parkWith(`agent parked at ${phase}: ${reason}`);
+        return;
+    }
+    if (outcome === 'blocked') {
+        early(`agent blocked at ${phase}: ${reason}`);
+        return;
+    }
+    if (outcome === 'shipped' && phase === 'deployment') {
+        openPullRequest(ctx, io, state, item);
+        return;
+    }
+    // A `paused` that awaits review was handled before this; one that does not is a stop
+    // the phase files do not bear out (AC-11).
+    early(`agent reported ${outcome}, but the instance is at ${phase}`);
+}
+/**
+ * A session that ended before the release boundary with no stop autopilot honours — no
+ * outcome short of deployment, `blocked`, or a `shipped` or `paused` its phase does not
+ * bear out. Most likely it ended its turn to wait for a command, which under `claude -p`
+ * ends the process and the command with it. Resumed once at the next pass, like a dropped
+ * connection; parked with `reason` — today's text — when it cannot be
+ * (unattended-agent-ends-turn-to-wait/AC-3, AC-5, AC-6).
+ */
+function endedEarly(ctx, io, state, item, launch, end, reason, budget) {
+    const refusals = refusalSuffix(end);
+    // A CI-fix or conflict relaunch: its pull request is open, so it is past the release
+    // boundary, and the early-ending prompt would be wrong about it. Parked as before.
+    if (item.pr) {
+        park(ctx, io, state, item, `${reason}${refusals}`, budget);
+        return;
+    }
+    // As `decideResume` reads it: a resumed Codex thread writes no second `thread.started`.
+    const resumed = launch.resumes !== undefined && UUID_RE.test(launch.resumes) ? launch.resumes : null;
+    const id = end.session_id ?? resumed;
+    // A resume of any kind: a session is resumed once (AC-5).
+    if (launch.resumes !== undefined) {
+        park(ctx, io, state, item, `${reason}; resumed once${id === null ? '' : `, session ${id}`}${refusals}`, budget);
+        return;
+    }
+    if (id === null) {
+        park(ctx, io, state, item, `${reason}${refusals}`, budget);
+        return;
+    }
+    item.pid = null;
+    item.resume_wait = { kind: 'ended-early', until: new Date(ctx.now()).toISOString(), session: id };
+    tell(ctx, item, `ended before the release boundary — resuming session ${id} at the next pass`);
+}
 /**
  * The pass after `aidlc autopilot approve`: wait again at the next completed pause,
  * open the pull request when the agent is already at deployment, or relaunch it to
  * carry on (autopilot-stop-controls/AC-18).
  */
-function advanceApproved(ctx, io, state, item) {
+function advanceApproved(ctx, io, state, item, budget) {
     if (awaitIfPaused(ctx, item))
         return;
     if (currentPhase(ctx, item) === 'deployment') {
@@ -311,9 +843,13 @@ function advanceApproved(ctx, io, state, item) {
     // since this pass serves it before `startBuilds` runs.
     if (building(state) >= buildSlots(ctx))
         return;
+    // And for the session limit, still `approved` (autopilot-reads-agent-result/AC-26).
+    if (launchBlocked(state, ctx.now()) !== null)
+        return;
     item.step = 'building';
     tell(ctx, item, 'approved — relaunching the agent to carry on');
-    launchAgent(ctx, item, agentPrompt(item, itemPauses(item)));
+    // The run's budget: a park for the cap here must reach `run.finished`, or `--items n` never ends.
+    launchAgent(ctx, io, state, item, agentPrompt(item, itemPauses(item)), budget);
 }
 function openPullRequest(ctx, io, state, item) {
     const push = io.call('git', ['push', '-u', 'origin', item.branch], { cwd: item.worktree });
@@ -445,11 +981,55 @@ function handleConflict(ctx, io, state, item, budget) {
         park(ctx, io, state, item, `conflicts with main after ${CONFLICT_FIX_LIMIT} fix attempts`, budget);
         return;
     }
+    const blocked = launchBlocked(state, ctx.now());
+    if (blocked !== null) {
+        // No attempt is made, so none is counted; out of the merge queue, so the items
+        // behind it can merge meanwhile (autopilot-reads-agent-result/AC-26, design D7).
+        dequeue(state, item);
+        item.step = 'pr-open';
+        tell(ctx, item, `conflicts with main — the fix waits for the session limit to reset at ${blocked}`);
+        return;
+    }
     item.conflict_fixes = tries + 1;
     dequeue(state, item);
     item.step = 'building';
     tell(ctx, item, `conflicts with main — relaunching the agent to resolve it (attempt ${tries + 1} of ${CONFLICT_FIX_LIMIT})`);
-    launchAgent(ctx, item, conflictPrompt(item));
+    launchAgent(ctx, io, state, item, conflictPrompt(item), budget);
+}
+/**
+ * The two `merge=union` cost ledgers a worktree collects between commits. `name` is
+ * the one `aidlc start` created and the agent claimed, so it holds no glob or
+ * option character (autopilot-merge-refusal-is-not-a-conflict/AC-1).
+ */
+const ledgerPaths = (name) => ['.aidlc/cost/unattributed.ndjson', `.aidlc/state/${name}/costs.ndjson`];
+const LEDGER_COMMIT_MESSAGE = 'chore(aidlc): commit cost ledgers before updating from main (autopilot)';
+/**
+ * Commit the worktree's uncommitted cost ledgers, and nothing else, so git does not
+ * refuse the update from main over a ledger both sides appended to — PR #125 on
+ * 2026-10-06 (autopilot-merge-refusal-is-not-a-conflict/AC-1..AC-4). Null when
+ * nothing needed committing or the commit was made; otherwise git's failure.
+ */
+function commitLedgers(ctx, io, item) {
+    const wt = { cwd: item.worktree };
+    const candidates = ledgerPaths(item.name);
+    const status = io.call('git', ['status', '--porcelain=v1', '--untracked-files=all', '--', ...candidates], wt);
+    if (status.status !== 0)
+        return status;
+    // Exact matches only, so a quoted or renamed path fails safe; a deleted ledger is
+    // never committed as a deletion (AC-2).
+    const lines = status.stdout.split('\n');
+    const dirty = candidates.filter((p) => lines.some((l) => l.slice(3) === p && !l.slice(0, 2).includes('D')));
+    if (dirty.length === 0)
+        return null;
+    const add = io.call('git', ['add', '--', ...dirty], wt);
+    if (add.status !== 0)
+        return add;
+    // By pathspec: another staged change stays staged and outside this commit (AC-2).
+    const commit = io.call('git', ['commit', '-q', '-m', LEDGER_COMMIT_MESSAGE, '--', ...dirty], wt);
+    if (commit.status !== 0)
+        return commit;
+    tell(ctx, item, 'committed its cost ledgers before updating from main');
+    return null;
 }
 /**
  * Bring the item's branch up to date with main in its own worktree, where the
@@ -469,16 +1049,35 @@ function upToDateWithMain(ctx, io, state, item, resume, budget) {
         return false;
     }
     const contains = io.call('git', ['merge-base', '--is-ancestor', 'origin/main', 'HEAD'], wt);
+    // Nothing is committed on this path: the head CI passed on is the head merged (AC-3).
     if (contains.status === 0)
         return true;
     if (contains.status !== 1) {
         failItem(ctx, state, item, `update from main failed: ${fail(contains)}`, resume);
         return false;
     }
+    // Here, not at the end of the build: the cost hook can write after the agent's
+    // last commit, and the head is about to move anyway (design D1).
+    const ledgers = commitLedgers(ctx, io, item);
+    if (ledgers !== null) {
+        failItem(ctx, state, item, `update from main failed: could not commit the cost ledgers: ${gitMessage(ledgers)}`, resume);
+        return false;
+    }
     const merge = io.call('git', ['merge', '--no-edit', 'origin/main'], wt);
     if (merge.status !== 0) {
+        // Read before the abort clears them. A merge git refused — local changes it would
+        // overwrite — leaves none, and an agent relaunched over it found "a clean merge"
+        // seven minutes later (autopilot-merge-refusal-is-not-a-conflict/AC-5, AC-8).
+        const unmerged = io.call('git', ['diff', '--name-only', '--diff-filter=U'], wt);
+        // Fails harmlessly when the merge never started.
         io.call('git', ['merge', '--abort'], wt);
-        handleConflict(ctx, io, state, item, budget);
+        if (unmerged.status === 0 && unmerged.stdout.trim() !== '') {
+            handleConflict(ctx, io, state, item, budget);
+        }
+        else {
+            // A check that cannot answer is no conflict either: an agent cannot mend git (AC-6).
+            failItem(ctx, state, item, `update from main failed: ${gitMessage(merge)}`, resume);
+        }
         return false;
     }
     dequeue(state, item);
@@ -538,14 +1137,23 @@ function advancePr(ctx, io, state, item, budget) {
         return;
     }
     item.ci = 'failed';
-    item.ci_failures = (item.ci_failures ?? 0) + 1;
-    if (item.ci_failures >= CI_FAILURE_LIMIT) {
+    const failures = (item.ci_failures ?? 0) + 1;
+    if (failures >= CI_FAILURE_LIMIT) {
+        item.ci_failures = failures;
         park(ctx, io, state, item, `CI failed twice: ${failing.join(', ')}`, budget);
         return;
     }
+    const blocked = launchBlocked(state, ctx.now());
+    if (blocked !== null) {
+        // Counted when the fix is launched, not before: the next pass reads the checks again
+        // (autopilot-reads-agent-result/AC-26, design D7).
+        tell(ctx, item, `CI failed (${failing.join(', ')}) — the fix waits for the session limit to reset at ${blocked}`);
+        return;
+    }
+    item.ci_failures = failures;
     tell(ctx, item, `CI failed (${failing.join(', ')}), relaunching the agent once`);
     item.step = 'building';
-    launchAgent(ctx, item, fixPrompt(item, failing));
+    launchAgent(ctx, io, state, item, fixPrompt(item, failing), budget);
 }
 /**
  * Mark the deployment artifact complete so `aidlc transition` can close the
@@ -646,7 +1254,8 @@ function serveQueue(ctx, io, state, budget) {
  */
 function parkUnstartable(ctx, io, file, failure) {
     const error = failure.trim();
-    const r = io.cli(['roadmap', 'park', '--item', file, '--reason', `could not start: ${error}`]);
+    // The start failure was read for a rate limit already, when `aidlc start` printed it.
+    const r = io.cli(['roadmap', 'park', '--item', file, '--reason', `could not start: ${error}`], { echoes: true });
     if (r.status !== 0) {
         ctx.say(`could not start ${file}: ${error} — and could not park it: ${fail(r)}`);
         return false;
@@ -661,6 +1270,18 @@ function startBuilds(ctx, io, state, budget) {
         ctx.say('not starting builds: no agent command configured — run `aidlc autopilot setup`');
         return;
     }
+    // Before `aidlc start`, not at launch: a new item has spent nothing, so a cap this small
+    // would start and park every ready item in turn (design-questions.md Q1).
+    const cap = ctx.config?.cost_cap_usd;
+    if (typeof cap === 'number' && budgetCents(cap, 0) < 1) {
+        ctx.say(`not starting builds: cost cap ${cap} USD leaves under a cent after the 10% margin`);
+        return;
+    }
+    const blocked = launchBlocked(state, ctx.now());
+    if (blocked !== null) {
+        ctx.say(`not starting builds: waiting for the session limit to reset at ${blocked}`);
+        return;
+    }
     const max = buildSlots(ctx);
     const template = ctx.config?.template ?? 'quick-feature';
     let busy = building(state);
@@ -714,7 +1335,9 @@ function startBuilds(ctx, io, state, budget) {
             // Held to these until it leaves, whatever later runs say (autopilot-stop-controls/AC-6).
             stops: stopsInForce(ctx.config),
         };
-        launchAgent(ctx, item, agentPrompt(item, itemPauses(item)));
+        // Only the gate can refuse here, and it was checked above; nothing is tracked without an agent.
+        if (!launchAgent(ctx, io, state, item, agentPrompt(item, itemPauses(item)), budget))
+            return;
         if (ctx.dryRun)
             return;
         state.items.push(item);
@@ -797,7 +1420,7 @@ export function tick(ctx, state, budget) {
             if (item.step === 'building')
                 advanceBuilding(ctx, io, state, item, budget);
             else if (item.step === 'approved')
-                advanceApproved(ctx, io, state, item);
+                advanceApproved(ctx, io, state, item, budget);
             else if (item.step === 'pr-open')
                 advancePr(ctx, io, state, item, budget);
             else if (item.step === 'awaiting-merge')