@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/dist/src/botworker.js

@@ -0,0 +1,805 @@
+// The bot's per-round worker: one Node process that serves ONE round
+// of one PR and exits.
+//
+//     node dist/src/botworker.js --command <id> --mode round|answer
+//
+// `--mode answer` (rule 9's second exception) serves an operator's message
+// to an idle PR instead of a round: the same handshake, login and resume under the
+// same session id, then ONE user turn marked with operator provenance, and the
+// reply goes back in the `done` event. Its tools are the read-only repo tools and
+// the memory lookups (src/engine/botsdk.ts `answer`), no lens tool, no verdict,
+// and no wave, wake or permit: the daemon's own wakes stay held for the round.
+// Only a message the operator marked may-post also gets bash, for the post
+// scripts, and the capability they read; the daemon refuses any other post in any
+// case. It compacts before it exits like a round, and the daemon bounds it by
+// `[daemon] answer_timeout_s` and `answer_cap_usd`. The numbered round below is the
+// round mode's; an answer runs 1 to 3, the one turn, then 6 and 7.
+//
+// The daemon starts it with the command's capability on an inherited fd
+// (QCR_IPC_CAP_FD, src/ipc/capability.ts), the socket path, the command id and
+// the generation in env (QCR_IPC_*), and a small allowlisted env of its own. It
+// holds no GitHub credential (rule 3: the bot mints per command, and every post
+// goes to the daemon's one gate over the socket) and it never opens state.db:
+// what it needs to know arrives through `worker.spec`, what it records goes
+// back as events, and the held wakes come through `wakes.take`
+// (src/ipc/workerspec.ts). tests/botworker-fence.test.ts holds the last claim
+// by walking the import closure.
+//
+// A round, in order:
+//   1. connect, ask for the spec, and verify the payload against the sha256 the
+//      daemon recorded at dispatch;
+//   2. borrow the login: a refresh-blanked copy read once from the agent dir the
+//      login refresher owns, refused when the token would expire inside
+//      this worker's wall-clock cap. The worker never refreshes it;
+//   3. open the PR's session: resume the newest JSONL under its session dir
+//      under the SAME id (the provider's cache key), or start one at birth;
+//   4. start the planned discovery wave (the engine, rule 9), then send the
+//      round order. A JSONL that already holds this command's marker means an
+//      earlier worker took the order: this worker continues instead of sending
+//      it again (marker idempotency, as the inject bridge's receipt works);
+//   5. deliver the wakes held while the round ran, in arrival order;
+//   6. compact (ledger-pin pins the review ledger through pi's own compact());
+//   7. report usage and done, and exit.
+//
+// Throughout, the daemon may push the operator's controls (src/botcontrol.ts):
+// a steer lands in the turn in flight, a follow-up behind the run, an abort stops the
+// session and the passes it started and ends the round with the aborted exit code.
+// Each is acked once over `control.ack`. The turns a control starts are waited for
+// before the wakes and again before the compaction.
+//
+// Exit codes: 0 the round was served (a verdict may or may not have been
+// written: `done` says), 1 a turn failed (timeout, cap, stream, refused
+// login), 2 bad usage, 3 the handshake or the
+// payload could not be trusted, 4 the login was refused up front, 5 the session
+// could not be opened, 6 the operator aborted the round, 75 the daemon went away, 76 the daemon fenced this
+// worker (a stale generation or an inactive command), 143 terminated.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { EventCostMeter } from "./bench/cost.js";
+import { CONTEXT_PACK_FILE } from "@quickchatai/pi-quickreview/src/contextpack.js";
+import { AuthError, classifyAuthFailure, engineCredentials, } from "@quickchatai/pi-quickreview/src/engine/auth.js";
+import { agentDirSettings } from "@quickchatai/pi-quickreview/src/engine/agentdir.js";
+import { COMMIT_VERDICT_RE } from "./engine/answerguard.js";
+import { NO_LENS, botSdkRuntime } from "./engine/botsdk.js";
+import { engineLensTools, } from "@quickchatai/pi-quickreview/src/engine/lens/engine-tools.js";
+import { planLaunch, } from "@quickchatai/pi-quickreview/src/engine/lens/launch-plan.js";
+import { engineLensSection } from "@quickchatai/pi-quickreview/src/engine/lens/section.js";
+import { LensWave, launchWave, } from "@quickchatai/pi-quickreview/src/engine/lens/wave.js";
+import { stopLiveSessions } from "@quickchatai/pi-quickreview/src/engine/livesessions.js";
+import { LENS_LEDGER_FILE, LENS_SESSIONS_DIR, } from "@quickchatai/pi-quickreview/src/engine/openable.js";
+import { PiHost, headerId, } from "@quickchatai/pi-quickreview/src/engine/pisdk.js";
+import { engineLensConfig } from "@quickchatai/pi-quickreview/src/engine/reviewsdk.js";
+import { credentialPaths, loginSourceDirs, } from "@quickchatai/pi-quickreview/src/engine/toolfence.js";
+import { TOOL_UMASK, checkToolUid, toolIdsOf, } from "@quickchatai/pi-quickreview/src/engine/tooluid.js";
+import { connectFromEnv } from "./ipc/client.js";
+import { brokerPermits } from "./ipc/permits.js";
+import { IpcError } from "./ipc/protocol.js";
+import { WAKES_ACK_OP, WAKES_TAKE_OP, WORKER_MODES, WORKER_SPEC_OP, parseWakesTaken, parseWorkerSpec, lensDirOf, roundPassesDir, } from "./ipc/workerspec.js";
+import { WorkerControls, ackSender } from "./botcontrol.js";
+import { MAX_REPLY_CHARS, operatorMayPost } from "./operatormessage.js";
+import { sessionCommandMarker } from "@quickchatai/pi-quickreview/src/session-command.js";
+import { verifiedPayload } from "./session-command-payload.js";
+import { newestSessionFile } from "./sessionjsonl.js";
+export const EXIT = {
+    ok: 0,
+    failed: 1,
+    usage: 2,
+    handshake: 3,
+    auth: 4,
+    session: 5,
+    aborted: 6,
+    lost: 75,
+    fenced: 76,
+    terminated: 143,
+};
+/** The most rounds of `wakes.take` one worker serves: wakes that arrive while it
+ * delivers are served too, but a flood cannot keep a round open for ever. */
+const MAX_WAKE_PASSES = 20;
+/** How long the round waits for the wave's rows to settle once it has ended
+ * them (each ends its session and writes its ledger line). */
+const WAVE_SETTLE_MS = 15_000;
+const DEFAULT_HEARTBEAT_MS = 15_000;
+/** A turn is never given less than this, so a nearly spent cap still runs it. */
+const MIN_TURN_MS = 1_000;
+/** The names of the worker's own env the main session's bash needs for the post
+ * shims (src/ipc/postshim.ts). Never given to a lens pass. */
+const IPC_ENV = [
+    "QCR_IPC_SOCKET",
+    "QCR_IPC_CAP_FD",
+    "QCR_IPC_COMMAND_ID",
+    "QCR_IPC_GENERATION",
+];
+/** The names of a round's identity in the session env. An answer has no round, so
+ * the model's bash (and the post scripts it may run) carries none of them: a post
+ * would claim a round and the daemon would refuse it. */
+const ROUND_ONLY_ENV = ["QCR_ROUND_NO", "QCR_EXPECTED_HEAD", "QCR_POSTING_KEY"];
+export function parseWorkerArgs(argv) {
+    let command;
+    let mode;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--command")
+            command = argv[++i];
+        else if (a === "--mode")
+            mode = argv[++i];
+        else
+            return { error: `unknown argument ${JSON.stringify(a)}` };
+    }
+    if (!command)
+        return { error: "--command <id> is required" };
+    if (!mode || !WORKER_MODES.includes(mode))
+        return { error: "--mode must be round or answer" };
+    return { command, mode: mode };
+}
+/** A user turn's closing marker, in the inject bridge's own spelling. */
+function withMarker(text, marker) {
+    return `${text}${text.endsWith("\n") ? "\n" : "\n\n"}${marker}`;
+}
+export const wakeMarker = (batchId) => `<!-- qcr-wake:${batchId} -->`;
+/** What a continuing worker tells the session. */
+export function continuationText(marker) {
+    return [
+        "The worker that was running this round stopped before the round finished; this conversation is intact. Carry on from where it stopped.",
+        "",
+        "Before you repeat a step, check what the round already produced: files you wrote, lens results you read, a review that was posted. Never post the same review twice (the post scripts tell you when it is already posted). A planned lens whose result you did not read ran in the worker that is gone: run `lens_wave` over the round's task directory again for it.",
+        "",
+        `The round order is the message above that carries ${marker}.`,
+    ].join("\n");
+}
+/** What a continuing answer worker tells the session. */
+export function answerContinuationText(marker) {
+    return [
+        "The worker that was answering the operator's message stopped before it finished; this conversation is intact. Finish the answer.",
+        "",
+        "Before you repeat a step, check what is already done: a review or reply you posted stays posted (the post scripts tell you when it is). Never post the same thing twice.",
+        "",
+        `The operator's message is the one above that carries ${marker}.`,
+    ].join("\n");
+}
+/** Does the session JSONL already hold `marker`? An unreadable file holds none. */
+export function jsonlHasMarker(file, marker) {
+    try {
+        return readFileSync(file, "utf8").includes(marker);
+    }
+    catch {
+        return false;
+    }
+}
+const POST_RE = /(?:^|[\s/;&|(])(post-review|approve-pr|reply-thread)\.sh(?:\s|$)/;
+/** What the daemon wants to know of the session's work: a verdict committed, a
+ * post made, and whether the model's last answer was the provider's failure.
+ * Observed off the session's events, the way the supervisor reads a round's
+ * progress, never off files. */
+class RoundWatch {
+    report;
+    verdictWritten = false;
+    posted = 0;
+    /** The provider's error on the newest assistant message, if that is how it ended. */
+    lastError;
+    /** The text of the newest assistant message that did not end in a tool call:
+     * what the model said last, which is an answer's reply. */
+    replyText;
+    commands = new Map();
+    constructor(report) {
+        this.report = report;
+    }
+    hear(event) {
+        if (event["type"] === "message_end") {
+            const message = event["message"];
+            if (message?.role === "assistant") {
+                const full = event["message"];
+                if (full.stopReason !== "toolUse" && full.stopReason !== "error")
+                    this.replyText = textOf(full.content);
+            }
+            if (message?.role === "assistant")
+                this.lastError =
+                    message.stopReason === "error"
+                        ? (typeof message.errorMessage === "string"
+                            ? message.errorMessage
+                            : "the provider returned an error").slice(0, 300)
+                        : undefined;
+            return;
+        }
+        const id = event["toolCallId"];
+        if (typeof id !== "string")
+            return;
+        if (event["type"] === "tool_execution_start" && event["toolName"] === "bash") {
+            const command = event["args"]?.command;
+            if (typeof command === "string")
+                this.commands.set(id, command);
+            return;
+        }
+        if (event["type"] !== "tool_execution_end")
+            return;
+        const command = this.commands.get(id);
+        this.commands.delete(id);
+        if (command === undefined || event["isError"] !== false)
+            return;
+        if (COMMIT_VERDICT_RE.test(command)) {
+            this.verdictWritten = true;
+            this.report("verdict_written", {});
+        }
+        const post = POST_RE.exec(command);
+        if (post) {
+            this.posted++;
+            this.report("posted", { script: `${post[1]}.sh` });
+        }
+    }
+}
+/** The text blocks of an assistant message's content, joined. */
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .flatMap((b) => typeof b === "object" &&
+        b !== null &&
+        b.type === "text" &&
+        typeof b.text === "string"
+        ? [b.text]
+        : [])
+        .join("\n")
+        .trim();
+}
+/** `: <the file's last line>` for a failure's reason, or nothing. */
+function lastLineOf(file) {
+    try {
+        const line = readFileSync(file, "utf8").trimEnd().split("\n").at(-1)?.trim();
+        return line ? `: ${line.slice(0, 300)}` : "";
+    }
+    catch {
+        return "";
+    }
+}
+class Stop extends Error {
+    exit;
+    reason;
+    constructor(exit, reason) {
+        super(reason);
+        this.exit = exit;
+        this.reason = reason;
+    }
+}
+/** Serve one round. Resolves to the exit code; a failed round is a returned
+ * code and a `failed` event, never a throw. */
+export async function runBotWorker(args, deps) {
+    const log = deps.log ?? (() => { });
+    const now = deps.now ?? Date.now;
+    const env = deps.env;
+    const answering = args.mode === "answer";
+    if (env["QCR_IPC_COMMAND_ID"] !== args.command) {
+        log("botworker: --command is not the command id the daemon put in env");
+        return EXIT.usage;
+    }
+    let client;
+    try {
+        client = await (deps.connect ?? (() => connectFromEnv("worker", env)))();
+    }
+    catch (e) {
+        log(`botworker: could not reach the daemon: ${errText(e)}`);
+        return EXIT.lost;
+    }
+    let broken = false;
+    const report = (kind, body) => {
+        if (broken)
+            return;
+        try {
+            client.event(kind, body);
+        }
+        catch {
+            broken = true;
+        }
+    };
+    // A daemon that restarts takes the socket with it: there is nobody left
+    // to post for this worker, so it stops spending. The same for a daemon that
+    // fences it (a newer generation, a command that is no longer active).
+    let stopCode;
+    let stopReason = "stopped";
+    let stopped = Promise.resolve();
+    let session;
+    const stopNow = (code, why) => {
+        if (stopCode !== undefined)
+            return stopped;
+        stopCode = code;
+        stopReason = why;
+        log(`botworker: stopping (${why})`);
+        stopped = (session?.abort() ?? Promise.resolve())
+            .catch(() => { })
+            .then(() => stopLiveSessions(5_000))
+            .catch(() => { });
+        return stopped;
+    };
+    const checkpoint = () => {
+        if (stopCode !== undefined)
+            throw new Stop(stopCode, stopReason);
+    };
+    client.onClose((e) => void stopNow(EXIT.lost, `the daemon connection ended: ${e.message}`));
+    client.onError((e) => {
+        if (e.code === "stale_generation" || e.code === "command_inactive" || e.code === "unauthorized")
+            void stopNow(EXIT.fenced, `the daemon fenced this worker: ${e.code}`);
+    });
+    // The operator's controls. They are taken from the moment the daemon
+    // connects: one that arrives before the session is open is refused, not lost.
+    let turnLimits = () => ({});
+    const controls = new WorkerControls({
+        session: () => session,
+        limits: () => turnLimits(),
+        abort: () => stopNow(EXIT.aborted, "the round was aborted by the operator"),
+        ack: ackSender((op, body) => client.request(op, body)),
+        log,
+    });
+    client.onControl((kind, body) => controls.receive(kind, body));
+    let host;
+    let beat;
+    let endWave = async () => { };
+    const started = now();
+    try {
+        const spec = await handshake(client, args);
+        const deadline = started + spec.wall_clock_ms;
+        const remaining = () => Math.max(MIN_TURN_MS, deadline - now());
+        // The payload is what the daemon dispatched, byte for byte, or nothing runs.
+        const verified = verifiedPayload({ payload_path: spec.payload_path, payload_sha256: spec.payload_sha256 }, "the command's payload");
+        if (!verified.ok)
+            throw new Stop(EXIT.handshake, verified.why);
+        // An answer posts only when the operator marked the message: the daemon's word
+        // (the spec) and the sealed payload both have to say so.
+        const mayPost = answering && spec.may_post === true && operatorMayPost(verified.payload.toString("utf8"));
+        // The login: borrowed, blanked, and checked against this worker's own cap.
+        let auth;
+        try {
+            auth = engineCredentials({ srcDir: spec.agent_dir, needMs: spec.wall_clock_ms, now });
+        }
+        catch (e) {
+            if (e instanceof AuthError)
+                throw new Stop(EXIT.auth, e.message);
+            throw e;
+        }
+        checkpoint();
+        // The host, the lens tools and the session. The model's tools run as the
+        // tool uid wherever the image asks for it.
+        const wave = new LensWave();
+        let lensUsd = 0;
+        let lensRuns = 0;
+        const marker = sessionCommandMarker(spec.command_id, spec.payload_sha256);
+        let opened;
+        try {
+            checkToolUid(env, { what: "the bot worker", instead: "", isolated: true });
+            const ids = toolIdsOf(env);
+            host = await (deps.makeHost ?? PiHost.create)({
+                agentDir: spec.agent_dir,
+                ownsProcess: true,
+                homeDir: homedir(),
+                ...(ids !== null && !("refused" in ids) ? { toolUid: ids } : {}),
+                fenceDirs: [...loginSourceDirs(env), ...credentialPaths(env, spec.env)],
+                credentials: auth.credentials,
+                settings: agentDirSettings(spec.agent_dir),
+            });
+            // The lens cap is the daemon's, over every worker: a pass asks the broker.
+            const permits = brokerPermits(client, (m) => log(`botworker: ${m}`));
+            opened = await openSession(host, spec, env, wave, marker, deps, log, permits, (run) => {
+                lensUsd += run.result.usage.cost;
+                lensRuns++;
+            }, answering ? { mayPost } : undefined);
+        }
+        catch (e) {
+            throw new Stop(EXIT.session, `could not open the session: ${errText(e)}`);
+        }
+        const { tools, resumed, continuing } = opened;
+        const live = opened.session;
+        session = live;
+        checkpoint();
+        const watch = new RoundWatch(report);
+        let accepted = false;
+        live.subscribe((event) => {
+            if (!accepted && event["type"] === "agent_start") {
+                accepted = true;
+                report("accepted", { command_id: spec.command_id, continued: continuing });
+            }
+            watch.hear(event);
+        });
+        report("ready", {
+            session_id: live.id,
+            session_file: opened.file ?? null,
+            resumed,
+            continued: continuing,
+        });
+        beat = setInterval(() => report("progress", {
+            stage: "heartbeat",
+            turns: live.stats().turns,
+            busy: live.stats().busy,
+        }), spec.heartbeat_ms ?? DEFAULT_HEARTBEAT_MS);
+        beat.unref();
+        turnLimits = () => ({
+            timeoutMs: remaining(),
+            ...(spec.cap_usd !== undefined
+                ? { capUsd: Math.max(0, spec.cap_usd - live.stats().spentUsd) }
+                : {}),
+        });
+        // What the round has cost, priced the way the transcript is (src/bench/cost.ts):
+        // the session's assistant messages and the passes its lens tools reported, each
+        // run once, and, at the end, the lens ledger's warm-ups. The daemon's est_usd
+        // takes it in place of measuring the transcript.
+        const meter = new EventCostMeter();
+        live.subscribe((event) => {
+            const type = event["type"];
+            if (type === "message_end" ||
+                type === "tool_execution_update" ||
+                type === "tool_execution_end")
+                meter.add(JSON.stringify(event));
+        }, { updates: true });
+        const usage = () => report("usage", {
+            total_usd: meter.totalUsd,
+            lens_usd: lensUsd,
+            lens_runs: lensRuns,
+            turns: live.stats().turns,
+        });
+        const settle = (r, what) => {
+            usage();
+            checkpoint();
+            if (r.timedOut)
+                throw new Stop(EXIT.failed, `${what}: the wall-clock cap ran out`);
+            if (r.capped)
+                throw new Stop(EXIT.failed, `${what}: the dollar cap was reached`);
+            if (r.streamError)
+                throw new Stop(EXIT.failed, `${what}: output stream failed: ${r.streamError.slice(0, 300)}`);
+            // A provider failure ends the turn as an assistant message, not as a throw.
+            if (watch.lastError !== undefined) {
+                const refused = classifyAuthFailure(watch.lastError);
+                throw new Stop(EXIT.failed, refused
+                    ? `${what}: the provider refused the login: ${refused.message}`
+                    : `${what}: the provider failed the turn: ${watch.lastError}`);
+            }
+            if (r.code !== 0)
+                throw new Stop(EXIT.failed, `${what}: the turn failed${lastLineOf(spec.stderr_file)}`);
+        };
+        const deliver = async (text, what) => {
+            const d = await live.followUp(text, turnLimits());
+            if (d.status === "queued") {
+                // An operator's turn is in flight, and this message runs behind it: its
+                // result is the session's last once nothing is queued.
+                await controls.drain();
+                const last = live.stats().last;
+                if (last === null)
+                    throw new Stop(EXIT.failed, `${what}: the message was not run (queued)`);
+                settle(last, what);
+                return;
+            }
+            if (d.status !== "handled")
+                throw new Stop(EXIT.failed, `${what}: the message was not run (${d.status})`);
+            settle(d.result, what);
+        };
+        // The turns an operator's control started: settled before the round goes on.
+        let controlsChecked = 0;
+        const settleControls = async (close) => {
+            await (close ? controls.drainAndClose() : controls.drain());
+            checkpoint();
+            const taken = controls.counts.steer + controls.counts.follow_up;
+            const last = live.stats().last;
+            if (last !== null && taken > controlsChecked)
+                settle(last, "the operator's message");
+            controlsChecked = taken;
+        };
+        // The round's turn. The engine starts the planned wave first, so the lenses
+        // are in flight while the session reads. A continuation does not: the rows ran
+        // in the worker that is gone, and the session is told so. An answer is one
+        // turn: the operator's message, no wave and no wakes (the daemon's own wakes
+        // stay held for the round).
+        let wakesDelivered = 0;
+        if (answering) {
+            const message = verified.payload.toString("utf8");
+            if (continuing) {
+                report("progress", { stage: "continuing" });
+                await deliver(answerContinuationText(marker), "the continuation");
+            }
+            else {
+                report("progress", { stage: "message_sent" });
+                settle(await live.prompt(withMarker(message, marker), turnLimits()), "the answer");
+            }
+        }
+        else {
+            if (continuing) {
+                report("progress", { stage: "continuing" });
+                await deliver(continuationText(marker), "the continuation");
+            }
+            else {
+                const planned = plannedWave(spec, env);
+                if (planned.note)
+                    log(`botworker: ${planned.note}`);
+                const section = engineLensSection(planned.dir, spec.planned_wave && planned.units.length
+                    ? { dir: planned.dir, agents: planned.units.map((u) => u.agent) }
+                    : null);
+                if (spec.planned_wave && planned.units.length) {
+                    const stop = new AbortController();
+                    if (tools === undefined)
+                        throw new Stop(EXIT.session, "a round opens with its lens tools");
+                    const rows = launchWave(wave, tools.runner, planned.units, stop.signal);
+                    report("progress", { stage: "wave_started", rows: rows.length });
+                    endWave = async () => {
+                        stop.abort();
+                        let timer;
+                        await Promise.race([
+                            Promise.allSettled(rows.map((row) => row.done)),
+                            new Promise((resolve) => (timer = setTimeout(resolve, WAVE_SETTLE_MS))),
+                        ]);
+                        clearTimeout(timer);
+                        endWave = async () => { };
+                    };
+                }
+                const order = verified.payload.toString("utf8");
+                report("progress", { stage: "round_order_sent" });
+                settle(await live.prompt(withMarker(`${order.trimEnd()}\n\n${section}`, marker), turnLimits()), "the round");
+            }
+            // Whatever the operator steered or followed up with runs to its end first.
+            await settleControls(false);
+            // The turns are over: a wave row nobody joined is not wanted any more.
+            await endWave();
+            // The wakes held while the round ran, in arrival order.
+            for (let pass = 0; pass < MAX_WAKE_PASSES; pass++) {
+                let batches;
+                try {
+                    batches = parseWakesTaken(await client.request(WAKES_TAKE_OP, {})).batches;
+                }
+                catch (e) {
+                    if (e instanceof IpcError && e.code === "unknown_op")
+                        break;
+                    throw e;
+                }
+                if (batches.length === 0)
+                    break;
+                for (const batch of batches) {
+                    const mark = wakeMarker(batch.id);
+                    const file = live.sessionFile;
+                    // A batch an earlier worker delivered and died before acking is acked, not sent again.
+                    if (!(file !== null && jsonlHasMarker(file, mark)))
+                        await deliver(withMarker(batch.message, mark), `wake ${batch.id}`);
+                    await client.request(WAKES_ACK_OP, { id: batch.id });
+                    wakesDelivered++;
+                }
+                report("progress", { stage: "wakes_delivered", delivered: wakesDelivered });
+            }
+        }
+        // Nothing is steered into a round that is closing; an abort still is.
+        await settleControls(true);
+        // Compaction through ledger-pin: pi's own compact() fires the session's
+        // session_before_compact. An optimisation, so a failure is reported and not fatal.
+        let compacted = "skipped";
+        if (spec.compact !== false && live.compact) {
+            report("progress", { stage: "compacting" });
+            const outcome = await live.compact();
+            compacted = outcome.status;
+            report("compacted", outcome);
+        }
+        checkpoint();
+        if (!answering)
+            foldLensLedger(meter, lensLedgerOf(spec));
+        usage();
+        report("done", {
+            mode: args.mode,
+            ...(answering
+                ? {
+                    // What the model said last, for the operator: the daemon writes it to the
+                    // command's result file.
+                    reply: (watch.replyText ?? "").slice(0, MAX_REPLY_CHARS),
+                    may_post: mayPost,
+                }
+                : {}),
+            session_id: live.id,
+            resumed,
+            continued: continuing,
+            verdict_written: watch.verdictWritten,
+            posted: watch.posted,
+            wakes_delivered: wakesDelivered,
+            controls: { ...controls.counts },
+            compacted,
+            turns: live.stats().turns,
+            total_usd: meter.totalUsd,
+            lens_usd: lensUsd,
+            elapsed_ms: now() - started,
+        });
+        return EXIT.ok;
+    }
+    catch (e) {
+        // A dropped connection fails whatever request was in flight; the cause is the
+        // stop code, not the request's error (the supervisor reads lost/fenced from it).
+        const stop = e instanceof Stop
+            ? e
+            : stopCode !== undefined
+                ? new Stop(stopCode, stopReason)
+                : new Stop(EXIT.failed, errText(e));
+        log(`botworker: ${stop.reason}`);
+        report("failed", { code: stop.exit, reason: stop.reason });
+        return stop.exit;
+    }
+    finally {
+        if (beat !== undefined)
+            clearInterval(beat);
+        await endWave().catch(() => { });
+        await session?.dispose().catch(() => { });
+        host?.dispose();
+        await controls.flush().catch(() => { });
+        await client.drain().catch(() => { });
+        client.close();
+    }
+}
+const errText = (e) => (e instanceof Error ? e.message : String(e)).slice(0, 500);
+/** The hello is the daemon's; the spec is its answer to who this command is. */
+async function handshake(client, args) {
+    let spec;
+    try {
+        spec = parseWorkerSpec(await client.request(WORKER_SPEC_OP, {}));
+    }
+    catch (e) {
+        throw new Stop(EXIT.handshake, `no usable spec from the daemon: ${errText(e)}`);
+    }
+    if (spec.command_id !== args.command || spec.mode !== args.mode)
+        throw new Stop(EXIT.handshake, "the spec is for another command or mode");
+    if (spec.pr !== client.pr)
+        throw new Stop(EXIT.handshake, "the spec is for another PR");
+    if (Object.keys(spec.env).some((k) => k.startsWith("QCR_IPC_")))
+        throw new Stop(EXIT.handshake, "the spec's env names the IPC variables, which are the worker's");
+    return spec;
+}
+/** The planned discovery wave's task files: the round's own pass dir. */
+function plannedWave(spec, env) {
+    const passes = roundPassesDir(spec, spec.round_no ?? 0);
+    const dir = join(passes, "tasks");
+    if (!existsSync(dir))
+        return { dir, units: [] };
+    const plan = planLaunch({ dirs: [passes] }, { QCR_SANDBOX_ROOT: spec.root, QCR_PR: String(spec.pr), PATH: env["PATH"] });
+    return plan.ok
+        ? { dir, units: plan.units }
+        : { dir, units: [], note: `engine wave not planned: ${plan.error}`.slice(0, 300) };
+}
+/** The main session's spec: the daemon's env, plus the IPC names the post shims
+ * read from the model's bash. A lens pass never gets those. */
+function sessionSpecOf(spec, env, answer) {
+    const ipc = {};
+    // An answer that may not post is given no way to reach the daemon at all.
+    if (!answer || answer.mayPost)
+        for (const name of IPC_ENV) {
+            const value = env[name];
+            if (value !== undefined)
+                ipc[name] = value;
+        }
+    const own = { ...spec.env };
+    if (answer)
+        for (const name of ROUND_ONLY_ENV)
+            delete own[name];
+    return {
+        cwd: spec.cwd,
+        env: { ...own, ...ipc },
+        model: spec.model,
+        systemPromptFile: spec.system_prompt_file,
+        name: spec.session,
+        eventsFile: spec.events_file,
+        stderrFile: spec.stderr_file,
+        limits: {
+            timeoutMs: spec.wall_clock_ms,
+            ...(spec.cap_usd !== undefined ? { capUsd: spec.cap_usd } : {}),
+        },
+    };
+}
+const lensLedgerOf = (spec) => join(lensDirOf(spec), LENS_LEDGER_FILE);
+/** The ledger's lines priced into `meter`: a run a tool result already reported
+ * adds nothing, a cache warm-up (which only the ledger records) is added. */
+function foldLensLedger(meter, file) {
+    try {
+        for (const line of readFileSync(file, "utf8").split("\n"))
+            meter.add(line);
+    }
+    catch {
+        // no ledger: the round ran no pass
+    }
+}
+/** Open the PR's session: the engine's lens tools over this round's own ledger
+ * and JSONLs, the bot runtime over them, and then resume the newest JSONL
+ * under the PR's session dir (same id) or, with none, a session born there. */
+async function openSession(host, spec, env, wave, marker, deps, log, permitPort, tap, answer) {
+    if (answer)
+        return openAnswerSession(host, spec, env, marker, deps, log, answer);
+    const round = spec.round_no ?? 0;
+    const lensDir = lensDirOf(spec);
+    const lensSpec = {
+        ...sessionSpecOf(spec, {}),
+        env: { ...spec.env, PI_CODING_AGENT_DIR: spec.agent_dir },
+    };
+    const base = {
+        ...engineLensConfig(host, lensSpec),
+        warn: (m) => console.error(`[lens] ${m}`),
+    };
+    // The round's context pack sits beside its task files, not beside the ledger.
+    const packFile = join(roundPassesDir(spec, round), CONTEXT_PACK_FILE);
+    const pack = existsSync(packFile) ? readFileSync(packFile, "utf8") : "";
+    const tools = engineLensTools({
+        ...base,
+        permitPort,
+        ledgerPath: lensLedgerOf(spec),
+        sessionsDir: join(lensDir, LENS_SESSIONS_DIR),
+        ...(base.cache && pack ? { cache: { ...base.cache, pack } } : {}),
+    }, wave, tap);
+    const runtime = botSdkRuntime(host, {
+        lens: tools,
+        processEnv: env,
+        ...(spec.round_no !== null
+            ? { live: { root: spec.root, key: spec.session, round: spec.round_no } }
+            : {}),
+        warn: (m) => log(`botworker: ${m}`),
+        ...(deps.openViking ? { openViking: deps.openViking } : {}),
+    });
+    const sessionSpec = sessionSpecOf(spec, env);
+    const file = newestSessionFile(spec.session_dir);
+    if (file === undefined) {
+        const born = await runtime.create({ ...sessionSpec, sessionDir: spec.session_dir });
+        return { session: born, tools, resumed: false, file: undefined, continuing: false };
+    }
+    const id = headerId(file);
+    const resumed = await runtime.resume(file, sessionSpec);
+    if (id !== null && resumed.id !== id) {
+        await resumed.dispose();
+        throw new Error(`the resumed session id ${resumed.id} is not the JSONL's ${id}`);
+    }
+    return { session: resumed, tools, resumed: true, file, continuing: jsonlHasMarker(file, marker) };
+}
+/** An answer worker's session: the PR's newest JSONL resumed under its own id (an
+ * answer never births one), with the read-only tool set and no lens tool. */
+async function openAnswerSession(host, spec, env, marker, deps, log, answer) {
+    const file = newestSessionFile(spec.session_dir);
+    if (file === undefined)
+        throw new Error(`#${spec.pr} has no session to resume: an answer never births one`);
+    const liveRound = spec.round_no ?? spec.live_round;
+    const runtime = botSdkRuntime(host, {
+        lens: NO_LENS,
+        answer,
+        processEnv: env,
+        ...(liveRound !== undefined
+            ? { live: { root: spec.root, key: spec.session, round: liveRound } }
+            : {}),
+        warn: (m) => log(`botworker: ${m}`),
+        ...(deps.openViking ? { openViking: deps.openViking } : {}),
+    });
+    const id = headerId(file);
+    const resumed = await runtime.resume(file, sessionSpecOf(spec, env, answer));
+    if (id !== null && resumed.id !== id) {
+        await resumed.dispose();
+        throw new Error(`the resumed session id ${resumed.id} is not the JSONL's ${id}`);
+    }
+    return {
+        session: resumed,
+        tools: undefined,
+        resumed: true,
+        file,
+        continuing: jsonlHasMarker(file, marker),
+    };
+}
+async function main() {
+    const parsed = parseWorkerArgs(process.argv.slice(2));
+    if ("error" in parsed) {
+        process.stderr.write(`botworker: ${parsed.error}\n`);
+        process.exit(EXIT.usage);
+    }
+    // Under the tool uid the run uid and the tool uid share one
+    // gid: what this worker's file tools write (a verdict staged, a review body)
+    // the model's bash may rewrite (commit-verdict.sh, render-review.sh), and the
+    // reverse, so both write group-writable files. The daemon keeps its own umask:
+    // the files it writes for a session to read (the recall hints) stay its own.
+    const ids = toolIdsOf(process.env);
+    if (ids !== null && !("refused" in ids))
+        process.umask(TOOL_UMASK);
+    // The supervisor's TERM is the hard stop (the process exit); this stops the
+    // sessions first so a turn in flight is aborted and its JSONL closed.
+    for (const sig of ["SIGTERM", "SIGINT"])
+        process.on(sig, () => {
+            void stopLiveSessions(3_000).finally(() => process.exit(EXIT.terminated));
+        });
+    const code = await runBotWorker(parsed, {
+        env: process.env,
+        log: (line) => process.stderr.write(`${line}\n`),
+    });
+    process.exit(code);
+}
+// Run only as the entry point, not when a test imports runBotWorker.
+if (process.argv[1]?.endsWith("botworker.js"))
+    void main();
+//# sourceMappingURL=botworker.js.map