@peakflo/agent-harness 0.0.0-stage → 0.2.2-rc.1

package/dist/runtime/session-runner.js

@@ -0,0 +1,2122 @@
+"use strict";
+/**
+ * THE SESSION RUNNER — one leased turn, start to finish.
+ *
+ * This is the loop 20x's `AgentManager` runs, reduced to the part that is
+ * actually about running an agent: prepare a workspace, wire the MCP servers
+ * through the loopback auth proxy, drive a backend adapter, and push every part
+ * it produces into the durable projection and then out to the control plane.
+ *
+ * WHAT IT DELIBERATELY IS NOT. `AgentManager` also owns tasks, worktrees, pull
+ * requests, plugin actions, skills sync, output-field extraction and heartbeat
+ * scheduling. None of that is a property of running an agent; all of it is a
+ * property of 20x's TASK model. Dragging it across would have made this package
+ * "20x without a window" rather than a harness, and would have required the
+ * control plane to grow a task table to match. The seam is cut at the turn.
+ *
+ * THE TURN IS THE UNIT OF WORK, which is what makes the lease design work: one
+ * lease is one turn, a lease that expires is requeued, and a runner that dies
+ * mid-turn loses at most that turn — because the parts it already produced were
+ * ingested as it went, not at the end.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionRunner = void 0;
+exports.qualifiedModelId = qualifiedModelId;
+exports.describeProviderError = describeProviderError;
+exports.modelGatewayRefusal = modelGatewayRefusal;
+exports.permissionFingerprint = permissionFingerprint;
+exports.decodeQuestionAnswers = decodeQuestionAnswers;
+exports.isApprovingOptionId = isApprovingOptionId;
+const node_crypto_1 = require("node:crypto");
+const model_gateway_1 = require("../adapters/model-gateway");
+const contract_1 = require("../contract");
+const attachments_1 = require("./attachments");
+const conversation_1 = require("./conversation");
+const permission_mode_1 = require("./permission-mode");
+const projection_1 = require("./projection");
+/** How often the runner asks the adapter for new output when nothing pushes. */
+const POLL_INTERVAL_MS = 2_000;
+/**
+ * How long an idle status must persist before the turn is considered over.
+ *
+ * A backend reports IDLE between tool calls as well as at the end of a turn, so
+ * ending on the first idle would truncate almost every transcript at the first
+ * tool. Two consecutive quiet polls is the 20x behaviour and the reason its
+ * transcripts are complete.
+ */
+const IDLE_CONFIRMATIONS = 2;
+/**
+ * THE PRIMARY GUARD, per the LONG TURNS fix.
+ *
+ * A wall clock cannot tell a runaway model from a slow-but-healthy one — a
+ * real coding turn routinely runs 30-90 minutes. Progress is the honest
+ * signal: as long as the backend keeps producing a new message part, a tool
+ * call start/end, or streamed text, the turn keeps running no matter how long
+ * it has been open. Only silence this long means the backend is hung.
+ *
+ * 20 MINUTES, NOT 10 — raised on review. `pollMessages` only reports a tool
+ * call's completion (or an incremental streamed chunk), not that one is still
+ * running: a single tool that legitimately takes a long time — a large test
+ * suite, a slow build, a big migration — produces NOTHING for the guard to
+ * see until it finishes. 10 minutes cut that kind of tool call outright; 20
+ * gives real long-running commands room while still catching a backend that
+ * has actually gone silent (crashed, wedged, or lost its connection) well
+ * short of the old fixed 10-minute wall clock this whole fix replaces.
+ *
+ * Used when the lease does not name its own `maxTurnIdleMs`
+ * (`CODING_AGENT_MAX_TURN_IDLE_MINUTES` on the control plane).
+ */
+const DEFAULT_MAX_TURN_IDLE_MS = 20 * 60_000;
+/**
+ * Where the soft warning fires, as a fraction of the hard ceiling.
+ *
+ * Only meaningful when an operator has actually set
+ * `CODING_AGENT_MAX_TURN_MINUTES` — `maxTurnDurationMs: null` (the default)
+ * has no ceiling and therefore no 90% mark either.
+ */
+const HARD_CEILING_WARNING_FRACTION = 0.9;
+/** "1 minute" / "10 minutes" — never "0 minutes", which reads like a bug. */
+function formatMinutes(ms) {
+    const minutes = Math.max(1, Math.round(ms / 60_000));
+    return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+}
+/**
+ * The model id the backend actually understands.
+ *
+ * The lease carries `provider` and `model` as SEPARATE fields, but Pi selects
+ * a provider/model pair from ONE qualified string at the adapter boundary.
+ * Passing `model.model` alone therefore threw the provider away: a lease
+ * saying `{provider:'anthropic', model:'claude-sonnet-4'}` reached the adapter
+ * as `claude-sonnet-4`, which has no `/`, so the adapter sent NO model at all
+ * and the backend silently used its own default. The control plane's choice of
+ * model was being ignored on every turn.
+ *
+ * Splitting on the FIRST slash is why this is a plain join and not a
+ * "does it already contain a slash" test: a real gateway model id is
+ * `peakflo/vertex_ai/gemini-3-flash-preview`, whose modelID legitimately
+ * contains a slash of its own.
+ */
+function qualifiedModelId(model) {
+    const name = (model.model ?? '').trim();
+    if (!name)
+        return undefined;
+    const provider = (model.provider ?? '').trim();
+    return provider ? `${provider}/${name}` : name;
+}
+/**
+ * Refuse to run a turn that would fall back to the host's own credentials.
+ *
+ * THIS IS THE SECURITY POINT OF THE GATEWAY, not a nicety. When the lease
+ * names a gateway but carries no `modelToken`, the adapter builds no `peakflo`
+ * provider, Pi can fall through to whatever is in the host's provider store,
+ * and the turn may run anyway — silently spending
+ * the machine owner's credentials, unmetered, with no per-tenant budget. On a
+ * customer VM, which is outside our security perimeter, that is somebody
+ * else's key being used by our software without anybody noticing.
+ *
+ * A missing token must therefore be LOUD. Returning a reason rather than
+ * throwing keeps the decision testable on its own.
+ */
+/**
+ * Say WHICH model was refused, and by whom.
+ *
+ * The bare provider text is often one word. A turn on
+ * a non-gateway model reported exactly `Forbidden`, which names
+ * neither the model nor the provider that refused it, so it reads as a fault
+ * in this runner. It is not: the provider rejected a model this machine holds
+ * no credential for.
+ *
+ * A model id names its provider (decision recorded in `modelGatewayRefusal`),
+ * and only the gateway provider is credentialed per turn from the lease.
+ * Every other provider needs a credential on the RUNNER, so for those the
+ * refusal is worth naming as a likely missing credential — likely, not
+ * certain, because a quota or a withdrawn model refuses identically and
+ * claiming otherwise would send the reader to the wrong place.
+ */
+function describeProviderError(error, qualifiedModel) {
+    // `qualifiedModelId` returns undefined when the lease named no model at all.
+    const model = (qualifiedModel ?? '').trim();
+    const head = model
+        ? `The model provider refused this turn on ${model}: ${error}`
+        : `The model provider refused this turn: ${error}`;
+    const provider = model.includes('/')
+        ? model.slice(0, model.indexOf('/'))
+        : '';
+    if (!provider || provider === model_gateway_1.ENTERPRISE_AI_GATEWAY_PROVIDER_ID) {
+        return head;
+    }
+    return (`${head}\n\n${provider} is not the Peakflo model gateway, so this runner ` +
+        `must hold its own credential for it. Check that the runner is signed in ` +
+        `to ${provider}, or choose a ${model_gateway_1.ENTERPRISE_AI_GATEWAY_PROVIDER_ID}/ model, ` +
+        `which is credentialed for each turn.`);
+}
+function modelGatewayRefusal(lease) {
+    const gatewayUrl = (lease.session.agent.model.gatewayUrl ?? '').trim();
+    if (!gatewayUrl)
+        return null;
+    const token = (lease.modelToken ?? '').trim();
+    if (!token) {
+        return (`Lease names model gateway ${gatewayUrl} but carries no modelToken. ` +
+            "Refusing the turn: running it would fall back to this host's own " +
+            'provider credentials, which are neither tenant-metered nor ' +
+            'budget-capped.');
+    }
+    /*
+     * THE PROVIDER IS PI'S TO CHOOSE, ON EVERY RUNTIME.
+     *
+     * There used to be a second refusal here: a lease naming `anthropic/...`
+     * built the `peakflo` provider and then never routed to it, because the backend
+     * routes by the provider in the model id — so the turn ran on whatever
+     * credentials the host had. That was treated as credential-borrowing and
+     * refused outside the desktop.
+     *
+     * It is now allowed everywhere, deliberately. A model id names its provider,
+     * and Pi is the thing that knows how to reach it — peakflo, google, a local
+     * model. The gateway is one provider among them and the
+     * default, not the only permitted route. Refusing the rest meant the model
+     * picker offered models that could never run.
+     *
+     * WHAT THIS GIVES UP, RECORDED RATHER THAN GLOSSED: a turn may run outside
+     * the gateway and therefore outside tenant metering and budget caps, on any
+     * runtime including the managed sandbox. On a user's own machine that is
+     * their key and their bill. On the SANDBOX it is our machine — the mitigation
+     * there is that the image ships Pi with no provider credentials
+     * configured, so there is nothing ambient to borrow; a turn that names a
+     * provider the sandbox cannot reach fails at the model call rather than
+     * silently spending. If credentials are ever baked into that image, this
+     * decision needs revisiting.
+     *
+     * The EMPTY-TOKEN refusal above is untouched: a lease that names a gateway
+     * and carries no credential is a broken lease, not a choice of provider.
+     */
+    return null;
+}
+/**
+ * Option ids that mean YES.
+ *
+ * AN ALLOWLIST, NOT "anything that is not deny". The difference matters the
+ * moment a backend adds a fifth option: under a denylist an unrecognised id
+ * would be APPROVED, and the cost of being wrong in that direction is an
+ * unattended agent running a command the user meant to refuse. Under this list
+ * an unrecognised id is refused, and the cost of being wrong is a prompt the
+ * user has to answer twice.
+ *
+ * `once` and `always` are OpenCode's own wire words; `allow`, `allow-always`
+ * and `approved-for-session` are what `getPendingApproval` offers and what 20x
+ * sends. All five are accepted because both vocabularies reach this function.
+ */
+/**
+ * What happened to an `answer` command.
+ *
+ * A DISCRIMINATED RESULT, NOT A BOOLEAN, and the distinction is load-bearing.
+ * `false` used to mean both "there was nothing to answer" and "the backend
+ * refused the answer", and the caller's recovery path — forgetting the
+ * commandId, telling the user — is right for the second and WRONG for the
+ * first. Collapsing them is what made that recovery path unreachable: the
+ * catch below swallowed the delivery failure and returned the same `false` a
+ * stale answer returns, so the harness's `.catch()` never fired and the user's
+ * click vanished with no error anywhere.
+ */
+/**
+ * The permission identity a backend session was created under.
+ *
+ * THE FULL PAIR, NOT JUST `permissionMode`. `default`, `plan` and `acceptEdits`
+ * all map to `'ask'` and differ only in `sandboxMode`, so comparing the
+ * two-valued mode alone would miss a `default` -> `plan` change entirely.
+ * Dormant on OpenCode, where those are indistinguishable anyway — but Codex
+ * reads `sandboxMode` directly, and a guard written generically should not
+ * quietly depend on which backend happens to be wired.
+ *
+ * A LEGACY VALUE ('ask' / 'allow', written before this carried the pair) can
+ * never equal a fingerprint, so it reads as "unrecorded" and forces a rebuild.
+ * That is the intended fail-closed outcome, not an accident of the format.
+ */
+function permissionFingerprint(mode) {
+    const mapped = (0, permission_mode_1.mapPermissionMode)(mode);
+    return `${mapped.permissionMode}:${mapped.sandboxMode}`;
+}
+/**
+ * Decode the wire format produced by the browser's question card.
+ *
+ * This deliberately matches 20x's AgentManager: each line is either
+ * `Header: answer` or an unlabelled single answer. OpenCode needs the headers
+ * to align answers with a multi-question request.
+ */
+function decodeQuestionAnswers(answer) {
+    const answers = {};
+    for (const line of (answer ?? '').split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const colon = trimmed.indexOf(':');
+        if (colon > 0) {
+            answers[trimmed.slice(0, colon).trim()] = trimmed.slice(colon + 1).trim();
+        }
+        else {
+            answers.answer = trimmed;
+        }
+    }
+    return answers;
+}
+const APPROVING_OPTION_IDS = new Set([
+    // OpenCode / the shape `getPendingApproval` offers.
+    'allow',
+    'allow-always',
+    'approved-for-session',
+    'always',
+    'once',
+    'approved',
+    /*
+     * CODEX. ITS "ALLOW" BUTTON IS `accept`, AND OMITTING IT WAS A REAL BUG:
+     * `codex-app-server-adapter.ts:995` offers `{ optionId: 'accept', name:
+     * 'Allow' }` by default. That id passed the "was this option offered" check
+     * and then FAILED this one, so a user clicking Allow on a Codex session had
+     * their approval relayed as `approved: false` and saw "Denied" in the
+     * transcript for something they had explicitly permitted.
+     *
+     * The cause was duplication: Codex has its OWN approving list at
+     * `codex-app-server-adapter.ts:588` which does include these, and this set
+     * was written without consulting it. `approving-option-ids.test.ts` now
+     * derives the expectation from what the adapters actually offer, so a backend
+     * adding a new id cannot silently become a denial again.
+     */
+    'accept',
+    'acceptForSession',
+    'approved_for_session'
+]);
+/**
+ * Is this option id an approval?
+ *
+ * Exported so `approving-option-ids.test.ts` can check it against what the
+ * ADAPTERS actually offer, rather than against a restatement of the same list —
+ * a hardcoded copy in the test would have passed against the bug that made
+ * Codex's "Allow" read as a denial.
+ */
+function isApprovingOptionId(optionId) {
+    return APPROVING_OPTION_IDS.has(optionId);
+}
+/** Free-text answers that mean NO, for the paths that carry no `optionId`. */
+const DENYING_ANSWER_TEXT = /^\s*(no|deny|denied|reject|rejected\b.*|cancel)\s*\.?\s*$/i;
+/**
+ * Decide what a user's answer actually means, and fail closed when it is not
+ * clear.
+ *
+ * THREE PATHS REACH HERE AND THEY DO NOT CARRY THE SAME INFORMATION:
+ *
+ *   1. An option BUTTON in the question card. Sends `optionId`. Unambiguous,
+ *      and this is the ordinary case.
+ *   2. The card's Reject button. Sends no `optionId` and the fixed text
+ *      "Rejected by the user."
+ *   3. The COMPOSER. When a question is open, typing a message posts it as an
+ *      answer instead (composer.tsx:76-106) — with no `optionId` at all.
+ *
+ * So free text has to be interpreted, and the rule is: interpret it only when
+ * it plainly matches something the backend offered. Anything else DENIES, and
+ * says so in the transcript rather than silently doing the safer thing without
+ * telling the user why they are being asked again.
+ */
+function resolveApproval(command, open) {
+    const answer = (command.answer ?? '').trim();
+    // Path 1 — an explicit option id.
+    if (command.optionId) {
+        const approved = isApprovingOptionId(command.optionId);
+        // An id the backend never offered is not trusted even if it LOOKS
+        // approving: it did not come from a button we rendered.
+        const offered = open.knownOptionIds.has(command.optionId);
+        if (!offered) {
+            return {
+                approved: false,
+                transcriptText: `Denied — the answer named an option (${command.optionId}) that was not offered.`
+            };
+        }
+        return {
+            approved,
+            optionId: command.optionId,
+            transcriptText: approved
+                ? `Approved${answer ? `: ${answer}` : ''}`
+                : `Denied${answer ? `: ${answer}` : ''}`
+        };
+    }
+    // Path 2/3 — free text. Match it against the labels the backend offered.
+    const matched = open.optionIdByLabel.get(answer.toLowerCase());
+    if (matched) {
+        const approved = isApprovingOptionId(matched);
+        return {
+            approved,
+            optionId: matched,
+            transcriptText: approved ? `Approved: ${answer}` : `Denied: ${answer}`
+        };
+    }
+    if (DENYING_ANSWER_TEXT.test(answer)) {
+        return { approved: false, transcriptText: `Denied: ${answer}` };
+    }
+    /*
+     * Unrecognised free text. DENY.
+     *
+     * The user typed something into the composer while a permission was open —
+     * very likely a new instruction, not consent. Treating "actually, do it a
+     * different way" as approval for the pending shell command would be the worst
+     * possible reading of it. The turn continues; the agent is told it was
+     * refused and why, and the user's words are carried through so the agent can
+     * act on them.
+     */
+    return {
+        approved: false,
+        transcriptText: answer
+            ? `Denied (no option chosen): ${answer}`
+            : 'Denied (no option chosen).'
+    };
+}
+class SessionRunner {
+    deps;
+    logger;
+    /**
+     * What the running turn needs in order to ANSWER a permission from outside
+     * the turn's own call stack.
+     *
+     * `run()` is a single long await; the answer arrives on a control-plane
+     * command handled by the harness, on a completely different stack. These
+     * three are what `answerPendingApproval` needs and cannot otherwise reach.
+     */
+    turnContext = null;
+    /** The approval currently shown to the user, if any. */
+    openApproval = null;
+    /** The transcript identity of an ordinary agent question, if one is open. */
+    openQuestionPartId = null;
+    /**
+     * Expiry of the model token THIS RUNNING BACKEND is holding, when the
+     * control plane reported one — see `LeaseResponse.modelTokenExpiresAt`.
+     * Updated by `updateModelCredential` on a mid-turn refresh. `null` for a
+     * sandbox turn (its per-SANDBOX key has no per-turn expiry to track).
+     */
+    modelTokenExpiresAt = null;
+    /**
+     * Written once per turn, the first time `modelTokenExpiresAt` is found to
+     * be in the past on a backend that cannot take a live credential update
+     * (`notifyConfigChanged` absent — currently Pi). Without this a self-hosted
+     * or desktop Pi turn that outlives its 1h key fails its NEXT model call
+     * with an ordinary-looking auth error and no indication why, which reads as
+     * a random provider outage rather than the known, disclosed limitation it
+     * is.
+     */
+    modelKeyExpiryNoticeShown = false;
+    /** toolCallIds already turned into a question part, so it is emitted once. */
+    emittedApprovals = new Set();
+    /**
+     * Total wall-clock this turn has spent blocked on a human.
+     *
+     * ADDED BACK ONTO THE TURN DEADLINE. `maxTurnDurationMs` is 600 s and it
+     * exists to stop a runaway MODEL, not to put a stopwatch on the user: a
+     * person who takes eleven minutes to decide whether to allow a shell command
+     * is behaving normally, and killing their turn for it would make the approval
+     * feature useless for exactly the cautious user it is built for.
+     */
+    approvalWaitMs = 0;
+    approvalWaitStartedAt = null;
+    constructor(deps) {
+        this.deps = deps;
+        this.logger = deps.logger ?? console;
+    }
+    /**
+     * True while a permission prompt is outstanding. Read by the harness to
+     * decide how hard to poll the control plane for the answer.
+     */
+    isAwaitingApproval() {
+        return this.openApproval !== null || this.openQuestionPartId !== null;
+    }
+    /**
+     * Run the leased turn to completion, or until `signal` aborts it.
+     *
+     * NEVER THROWS FOR AN AGENT-SIDE FAILURE. A backend that crashes, a model that
+     * errors, a tool that hangs — all of those are OUTCOMES of a turn and are
+     * reported in `TurnMetadata.stopReason`, because the control plane needs to
+     * record them and the user needs to see them. Only a failure to talk to the
+     * control plane at all propagates, since that is the one thing the runner
+     * cannot report through the control plane.
+     */
+    async run(lease, signal) {
+        const { session } = lease;
+        const startedAt = new Date().toISOString();
+        const release = this.deps.notifier.keepAwake();
+        let workspaceDir = null;
+        let adapter = null;
+        let backendSessionId = null;
+        let secretToken = null;
+        let partsProduced = 0;
+        let stopReason = 'completed';
+        let error;
+        let repositoryStatuses = [];
+        /** True when the backend session was resumed rather than created. */
+        let resumed = false;
+        /** Part ids already ingested before this turn. See `drain` and the log. */
+        let priorPartIdsForLog = new Set();
+        /** True when history had to be replayed into a fresh backend session. */
+        let replayed = false;
+        /** This runner's own backend instance id — see `loadMemory`. */
+        let ownBackendInstanceId = null;
+        /**
+         * The user's message as the MODEL receives it: `input.content` plus, when
+         * the turn carries attachments, the note saying where they were written.
+         * Also what the conversation log records, so a later turn still knows the
+         * files exist.
+         */
+        let turnContent = session.input.content;
+        this.turnParts = [];
+        this.modelTokenExpiresAt = lease.modelTokenExpiresAt ?? null;
+        this.modelKeyExpiryNoticeShown = false;
+        try {
+            const refusal = modelGatewayRefusal(lease);
+            if (refusal)
+                throw new Error(refusal);
+            try {
+                workspaceDir = await this.deps.workspace.prepare({
+                    sessionId: session.sessionId,
+                    mode: session.workspace.mode,
+                    repositoryUrl: session.workspace.repositoryUrl,
+                    ref: session.workspace.ref,
+                    repositories: session.workspace.repositories,
+                    requestedRepositories: session.workspace.requestedRepositories,
+                    onRepositoryStatus: (status) => {
+                        repositoryStatuses = [
+                            ...repositoryStatuses.filter((current) => current.fullName !== status.fullName),
+                            status
+                        ];
+                    },
+                    refusalReason: session.workspace.refusalReason
+                });
+                const repositoryNames = session.workspace.requestedRepositories ??
+                    (session.workspace.repositories ?? []).map(({ fullName }) => fullName);
+                for (const fullName of repositoryNames) {
+                    if (!repositoryStatuses.some((current) => current.fullName === fullName)) {
+                        repositoryStatuses.push({ fullName, status: 'checkedOut' });
+                    }
+                }
+            }
+            catch (caught) {
+                const reason = caught instanceof Error ? caught.message : String(caught);
+                const status = session.workspace.refusalReason ? 'refused' : 'failed';
+                const names = session.workspace.requestedRepositories ??
+                    (session.workspace.repositories ?? []).map(({ fullName }) => fullName);
+                for (const fullName of names) {
+                    if (!repositoryStatuses.some((current) => current.fullName === fullName)) {
+                        repositoryStatuses.push({ fullName, status, reason });
+                    }
+                }
+                const failures = repositoryStatuses.filter((repository) => repository.status !== 'checkedOut');
+                throw new Error(failures.length > 0
+                    ? failures
+                        .map((repository) => `Repository ${repository.fullName} was not checked out: ${repository.reason ?? reason}`)
+                        .join('\n')
+                    : `Repository workspace was not prepared: ${reason}`);
+            }
+            /*
+             * THE USER'S ATTACHMENTS, INTO THIS TURN'S WORKSPACE — every turn, since
+             * each lease carries its own turn's files and the session may have moved
+             * runner since the last one. Never fatal: a file that cannot be fetched
+             * is named in the note and the turn runs without it.
+             */
+            const hasLeasedAttachments = (session.input.attachments?.length ?? 0) > 0;
+            /*
+             * ATTACHMENTS THE CONTROL PLANE ITSELF COULD NOT PREPARE — a
+             * `local://` URL it cannot fetch (local dev storage), or a signing
+             * failure. These never appear in `session.input.attachments` at all,
+             * so without this the block below would not even RUN when every
+             * attachment fell into this bucket: the turn would proceed as if
+             * nothing had ever been attached, silently, for both the model and
+             * (via the transcript note) the user. See `LeasedTurnInput
+             * .droppedAttachments`'s doc comment.
+             */
+            const hasDroppedAttachments = (session.input.droppedAttachments?.length ?? 0) > 0;
+            if (workspaceDir && (hasLeasedAttachments || hasDroppedAttachments)) {
+                const sync = await (0, attachments_1.syncAttachmentsToWorkspace)(session.input.attachments, workspaceDir, {
+                    fetchImpl: this.deps.fetchAttachment,
+                    logger: this.logger,
+                    // Namespaces this turn's filenames from every other turn's, so a
+                    // later turn's same-named attachment cannot silently overwrite
+                    // an earlier turn's file that an earlier point in the
+                    // conversation log still refers to. See `syncAttachmentsToWorkspace`'s
+                    // `turnId` doc comment for why re-leasing THIS turn stays idempotent.
+                    turnId: session.turnId
+                });
+                /*
+                 * MERGED INTO THE SAME `failed` LIST `syncAttachmentsToWorkspace`'s
+                 * OWN download failures land in, so `attachmentPromptNote` reports
+                 * both kinds identically — the model and the user should not have
+                 * to care WHERE in the pipeline a file was lost. The name is
+                 * sanitised again here: this list crossed the wire in the lease,
+                 * same as `session.input.attachments` does, and is exactly as
+                 * untrusted (see the module's own doc comment).
+                 */
+                if (session.input.droppedAttachments?.length) {
+                    for (const dropped of session.input.droppedAttachments) {
+                        sync.failed.push({
+                            name: (0, attachments_1.sanitizeAttachmentName)(dropped?.name),
+                            reason: String(dropped?.reason ?? 'could not be prepared')
+                        });
+                    }
+                }
+                const note = (0, attachments_1.attachmentPromptNote)(sync);
+                if (note)
+                    turnContent = `${session.input.content}\n\n${note}`;
+                this.deps.telemetry.record('provider.turn.attachments', {
+                    synced: sync.synced.length,
+                    failed: sync.failed.length
+                });
+            }
+            // Point the shared holder at THIS turn's credential before the adapter
+            // builds its provider config. Revoked in `finally`, so the credential
+            // never outlives the turn it was minted for.
+            if (session.agent.model.gatewayUrl) {
+                /*
+                 * REGISTER THE GATEWAY'S WHOLE CATALOGUE, as 20x does — not just the
+                 * one model this turn happens to use.
+                 *
+                 * This used to build a provider containing a single model. The turn ran
+                 * either way, but the backend's own provider list was then a lie:
+                 * `config.providers()` is what an agent form reads to offer a choice,
+                 * so a one-entry provider can never report what is actually reachable.
+                 *
+                 * The fetch is best-effort. A gateway that will not answer must not
+                 * stop a turn whose model is already known, so we fall back to exactly
+                 * the previous behaviour.
+                 */
+                const fetched = await (0, model_gateway_1.fetchGatewayModels)({
+                    baseUrl: session.agent.model.gatewayUrl,
+                    apiKey: lease.modelToken
+                });
+                const named = session.agent.model.model
+                    ? [
+                        {
+                            id: session.agent.model.model,
+                            name: session.agent.model.model
+                        }
+                    ]
+                    : [];
+                /*
+                 * The lease's model is ALWAYS included, even when the gateway does not
+                 * advertise it. Measured on this deployment: the model that works
+                 * (`vertex_ai/gemini-3-flash-preview`) is absent from `/models`, while
+                 * one that is listed (`gpt-4.1`) is refused at call time. Trusting the
+                 * catalogue to be complete would drop the working model out of the
+                 * provider and break the turn.
+                 */
+                const merged = [...fetched];
+                for (const model of named) {
+                    if (!merged.some((m) => m.id === model.id))
+                        merged.push(model);
+                }
+                this.deps.modelGateway?.set({
+                    apiKey: lease.modelToken,
+                    baseUrl: session.agent.model.gatewayUrl,
+                    models: merged
+                });
+            }
+            else {
+                // Null means "no gateway provider" — never "use whatever credentials
+                // are on this machine".
+                this.deps.modelGateway?.set(null);
+            }
+            adapter = this.deps.getAdapter(session.agent.backend);
+            await adapter.initialize();
+            secretToken = this.setUpSecrets(session);
+            const config = this.buildSessionConfig(session, workspaceDir, secretToken, signal);
+            /*
+             * REMEMBER THE CONVERSATION. This block is the fix for the defect that
+             * made this a chat product that could not hold a conversation: the
+             * previous code went straight to `createSession` here, every turn, and
+             * sent only `session.input.content` — so the model met the user for the
+             * first time on every message while the UI transcript looked complete.
+             */
+            /*
+             * WHICH BACKEND INSTANCE THIS RUNNER IS. Optional-chained through a cast
+             * because it is a backend-specific affordance, not part of
+             * `CodingAgentAdapter`, and a backend
+             * that cannot answer keeps the previous behaviour.
+             */
+            ownBackendInstanceId =
+                adapter.backendInstanceId?.() ?? null;
+            const memory = await this.loadMemory(session, ownBackendInstanceId);
+            /*
+             * What this runner has ALREADY ingested for this session.
+             *
+             * Read before the turn starts, from the durable projection rather than
+             * from anything held in memory, so it is correct after a restart too.
+             */
+            const priorPartIds = new Set(this.deps.store.getParts(session.sessionId).map((part) => part.partId));
+            // PREFERRED: keep talking to the backend session that already holds the
+            // context. Nothing is reconstructed and no tokens are re-sent.
+            if (memory.backendSessionId) {
+                try {
+                    /*
+                     * `resumeSession` RETURNS THE SESSION'S HISTORY, and that return
+                     * value is load-bearing rather than incidental.
+                     *
+                     * `pollMessages` is asked for "everything not in these sets". On a
+                     * resumed session that is every message the conversation has ever
+                     * had, so the parts already in the backend must be marked seen or the
+                     * turn re-emits the whole conversation. Seeding from OUR OWN STORE is
+                     * not enough: a cold runner resuming a still-live backend session has
+                     * an empty store and a full backend, which is exactly the
+                     * harness-restart case. The backend's own answer is the only source
+                     * that is right in both.
+                     */
+                    /*
+                     * REFUSE TO RESUME WHEN THE PERMISSION MODE HAS CHANGED — this is
+                     * what makes exit test 4 ("change the mode; the NEXT turn honours it
+                     * with no session restart") actually true.
+                     *
+                     * PI BINDS THE PERMISSION EXTENSION TO THE PROCESS AT CREATION. A
+                     * resumed native session must therefore be started with the current
+                     * decision; a checkpoint made under a different decision is rebuilt
+                     * from the runtime-neutral conversation log.
+                     *
+                     * THE CHECK LIVES HERE, NOT IN THE ADAPTER, because the runner is the
+                     * only place that both owns the resume decision and can see a durable
+                     * record. Two earlier attempts inside the adapter could never fire:
+                     * the workspace is deleted and rebuilt every turn, and `getAdapter`
+                     * constructs a fresh adapter per turn, so neither the config file nor
+                     * the adapter's own map survives to be compared against.
+                     *
+                     * AN UNKNOWN PREVIOUS DECISION NOW FORCES A REBUILD, and an earlier
+                     * version of this guard did the opposite. That was wrong, and review
+                     * caught it: the decision is read from the LOCAL conversation store,
+                     * so it is absent on a checkpoint written before this existed AND on
+                     * ANY OTHER RUNNER — and a lease changing hands is described
+                     * elsewhere in this file as an ordinary event, not an edge case. So
+                     * "unknown skips the check" meant the guard was routinely bypassed
+                     * exactly when a session had travelled, while the UI now presents the
+                     * mode as enforced.
+                     *
+                     * It is also the wrong DIRECTION for this change. Everything else
+                     * here fails closed — an unknown mode maps to `ask`, an unoffered
+                     * option denies. Unknown must therefore mean "rebuild", not "trust
+                     * the old session".
+                     *
+                     * THE COST, STATED: one rebuild and one replay on the first turn
+                     * after an upgrade, and on the first turn after a lease moves to a
+                     * different runner. Bounded, one-off per runner per session, and paid
+                     * in the direction of enforcing the policy the user chose. The
+                     * conversation is preserved either way — the fallback replays it.
+                     */
+                    const wantedDecision = permissionFingerprint(session.agent.permissionMode);
+                    if (memory.permissionDecision !== wantedDecision) {
+                        throw new Error('permission mode changed or unrecorded ' +
+                            `(${memory.permissionDecision ?? 'unrecorded'} -> ${wantedDecision}); ` +
+                            'the backend session must be rebuilt so the new policy takes effect');
+                    }
+                    const history = await adapter.resumeSession(memory.backendSessionId, config);
+                    for (const message of history ?? []) {
+                        for (const part of message.parts ?? []) {
+                            if (part?.id)
+                                priorPartIds.add(part.id);
+                        }
+                    }
+                    backendSessionId = memory.backendSessionId;
+                    resumed = true;
+                    this.deps.telemetry.record('provider.session.resumed', {
+                        backend: session.agent.backend,
+                        runtime: session.runtime
+                    });
+                }
+                catch (caught) {
+                    // AN ORDINARY OUTCOME, NOT AN ERROR. A swept sandbox, a redeployed
+                    // runner or a restarted OpenCode all land here. Falling through to a
+                    // fresh session with the log replayed is the whole point of keeping
+                    // the log, so this is logged at warn and the turn continues.
+                    this.logger.warn(`[SessionRunner] could not resume backend session ` +
+                        `${memory.backendSessionId} for ${session.sessionId}: ` +
+                        `${caught instanceof Error ? caught.message : String(caught)}. ` +
+                        'Falling back to replay.');
+                    this.deps.conversation?.setCheckpoint(session.sessionId, null, session.agent.backend, { backendOwnerId: ownBackendInstanceId });
+                }
+            }
+            if (!backendSessionId) {
+                backendSessionId = await adapter.createSession(config);
+                this.deps.telemetry.record('provider.session.started', {
+                    backend: session.agent.backend,
+                    runtime: session.runtime
+                });
+            }
+            // Record the checkpoint BEFORE the prompt runs. A turn that crashes
+            // half-way still leaves a resumable session behind, and the alternative
+            // — recording it only on success — loses the context in exactly the case
+            // where the user most wants it back.
+            this.deps.conversation?.setCheckpoint(session.sessionId, backendSessionId, session.agent.backend, {
+                // WHICH INSTANCE minted it, so only this runner resumes it (#1591).
+                backendOwnerId: ownBackendInstanceId,
+                // The decision this backend session was CREATED under. The next turn
+                // compares against it to decide whether the session can be reused
+                // (#1602). Independent of the owner; both are recorded.
+                permissionDecision: permissionFingerprint(session.agent.permissionMode)
+            });
+            /*
+             * FALLBACK: a fresh backend session knows nothing, so it has to be told.
+             * When the session was RESUMED this is skipped entirely and the prompt is
+             * byte-for-byte what it always was — a resumed backend already holds the
+             * history, and replaying it as well would both duplicate it and pay for
+             * it twice.
+             */
+            const promptText = resumed
+                ? turnContent
+                : (0, conversation_1.buildReplayPrompt)(memory.messages.map((message) => ({
+                    role: message.role,
+                    content: message.content
+                })), turnContent);
+            // There was no per-turn host-note mechanism in the harness. Keep the
+            // addition small: a workspace may supply one note, which is sent to the
+            // model but is not written into the durable user conversation.
+            const turnNote = this.deps.workspace.takeTurnNote?.(session.sessionId);
+            const promptWithHostNote = turnNote
+                ? `${turnNote}\n\n${promptText}`
+                : promptText;
+            replayed = !resumed && memory.messages.length > 0;
+            priorPartIdsForLog = priorPartIds;
+            await adapter.sendPrompt(backendSessionId, [{ type: 'text', text: promptWithHostNote, role: 'user' }], config);
+            this.deps.telemetry.record('provider.turn.sent', {
+                backend: session.agent.backend
+            });
+            /*
+             * WIRE 3 NEEDS A WAY IN. `run` is one long await, and the user's answer
+             * arrives on a control-plane command that the harness handles on a
+             * completely different stack. This is what `answerPendingApproval`
+             * reaches through. Cleared in the `finally` below, so an answer can never
+             * be applied to a turn that has already ended.
+             */
+            this.turnContext = {
+                sessionId: session.sessionId,
+                backendSessionId,
+                adapter,
+                config
+            };
+            const drained = await this.drain(adapter, backendSessionId, config, session, signal, 
+            // RESUMING REPLAYS THE WHOLE BACKEND SESSION. `pollMessages` is asked
+            // for "everything not in these sets", and on a resumed session that is
+            // every message the conversation has ever had — so without seeding, a
+            // second turn re-emits turn one. The transcript upsert is idempotent so
+            // the UI survives it, but the MODEL LOG would not: each turn would
+            // absorb every previous turn's text and the stored conversation would
+            // grow quadratically until it filled the context window.
+            resumed ? priorPartIds : new Set(), 
+            // THE PROMPT THIS RUNNER JUST SENT. Drain uses it to recognise the
+            // backend's own echo of it — see `drain`.
+            promptWithHostNote);
+            partsProduced = drained.parts;
+            if (signal.aborted) {
+                stopReason = 'aborted';
+            }
+            else if (drained.idleTimedOut) {
+                // THE PRIMARY GUARD. No progress at all for `maxTurnIdleMs` — the
+                // backend is hung, not merely slow. A healthy turn that keeps
+                // producing parts never reaches this no matter how long it runs.
+                stopReason = 'no_progress';
+                error = drained.idleTimedOutMessage ?? 'Turn stopped: no progress';
+                partsProduced += this.record(session.sessionId, [
+                    {
+                        id: `turn-idle-${(0, node_crypto_1.randomUUID)()}`,
+                        role: 'system',
+                        partType: 'error',
+                        content: error
+                    }
+                ]);
+            }
+            else if (drained.timedOut) {
+                // THE LAST-LINE CEILING, and only reached when an operator has
+                // actually configured `CODING_AGENT_MAX_TURN_MINUTES` — the default
+                // is no ceiling at all, enforced by the idle guard above instead.
+                stopReason = 'turn_time_limit';
+                error = 'Turn stopped: turn_time_limit';
+                this.logger.warn(`[SessionRunner] turn-hard-ceiling session=${session.sessionId} ` +
+                    `maxTurnDurationMs=${session.limits.maxTurnDurationMs}`);
+                partsProduced += this.record(session.sessionId, [
+                    {
+                        id: `turn-limit-${(0, node_crypto_1.randomUUID)()}`,
+                        role: 'system',
+                        partType: 'error',
+                        content: error
+                    }
+                ]);
+            }
+            else if (drained.providerError) {
+                // A provider failure is a FAILED turn, never a completed one. Recorded
+                // on the turn so the control plane and the UI can both see it, and
+                // written into the transcript so the user is told rather than left
+                // looking at a conversation that silently stopped answering.
+                stopReason = 'error';
+                error = drained.providerError;
+                this.logger.error(`[SessionRunner] session ${session.sessionId} provider error: ${error}`);
+                partsProduced += this.record(session.sessionId, [
+                    {
+                        id: `error-${(0, node_crypto_1.randomUUID)()}`,
+                        role: 'system',
+                        content: describeProviderError(error ?? String(drained.providerError), qualifiedModelId(session.agent.model)),
+                        partType: 'error'
+                    }
+                ]);
+            }
+        }
+        catch (caught) {
+            stopReason = signal.aborted ? 'aborted' : 'error';
+            error = caught instanceof Error ? caught.message : String(caught);
+            this.logger.error(`[SessionRunner] session ${session.sessionId} failed: ${error}`);
+            // The failure IS the transcript's last word. Recording it as a part is
+            // what makes an error visible to the user instead of a session that
+            // simply stops producing output and never says why.
+            partsProduced += this.record(session.sessionId, [
+                {
+                    id: `error-${(0, node_crypto_1.randomUUID)()}`,
+                    role: 'system',
+                    partType: 'error',
+                    content: error
+                }
+            ]);
+        }
+        finally {
+            release();
+            this.deps.modelGateway?.revoke();
+            /*
+             * THE TURN CAN NO LONGER TAKE AN ANSWER.
+             *
+             * Cleared before anything else in teardown. `answerPendingApproval`
+             * checks `turnContext` first, so once this is null a late answer — one
+             * that raced the turn ending, or that arrived after an abort — is
+             * refused instead of being handed to an adapter whose backend session is
+             * on its way out. `closeApproval` also releases the harness from its
+             * tightened polling, which would otherwise keep running until the next
+             * turn happened to reset it.
+             */
+            this.turnContext = null;
+            this.closeApproval(session.sessionId);
+            this.closeQuestion(session.sessionId);
+            this.emittedApprovals.clear();
+            /*
+             * STOP THE PER-TURN PI PROCESS BEFORE THE NEXT LEASE CAN START.
+             *
+             * Pi receives the virtual gateway key and MCP proxy URLs in its child
+             * environment. The adapter therefore owns one process per turn: no
+             * server-wide config push exists, and a later turn cannot inherit an old
+             * key or old MCP token from a warm process.
+             *
+             * THE CONVERSATION SURVIVES. Pi persists the native session file under
+             * its durable agent directory. The next turn starts a fresh process with
+             * the new credentials and resumes that file only when backend-owner and
+             * permission-decision checks match; otherwise it replays the neutral log.
+             */
+            try {
+                await adapter?.stopServer?.();
+            }
+            catch {
+                // Never let teardown mask the turn's real outcome.
+            }
+            // Teardown is best-effort and ORDERED: revoke the secret grant first, so
+            // a backend that is slow to die cannot use it during the wait.
+            if (secretToken) {
+                try {
+                    this.deps.secrets.unregisterSession(secretToken);
+                }
+                catch {
+                    // Never let teardown mask the turn's real outcome.
+                }
+            }
+            /*
+             * THE BACKEND SESSION IS DELIBERATELY *NOT* DESTROYED HERE.
+             *
+             * It used to be, on every turn, and that single call was the defect: the
+             * session holds the conversation's context, so tearing it down at the end
+             * of each turn is what made the model start blank on the next one. It is
+             * kept alive as the resume checkpoint instead.
+             *
+             * WHAT THIS COSTS, SAID PLAINLY. The backend accumulates one live session
+             * per conversation for the life of the process, along with the adapter's
+             * per-session client maps. That is bounded by concurrent conversations
+             * rather than by turns, and it is how 20x has always behaved. On the
+             * sandbox runtime the sweep destroys the whole machine when the session
+             * ends, so nothing outlives it. Reclaiming a backend session on an
+             * explicit session-end signal is a real follow-up and is recorded as one;
+             * a leak measured in conversations is a far smaller problem than an agent
+             * that cannot remember the previous sentence.
+             */
+        }
+        const turn = {
+            turnId: session.turnId,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            model: session.agent.model.model,
+            stopReason,
+            error,
+            repositories: repositoryStatuses.length > 0 ? repositoryStatuses : undefined,
+            // The checkpoint travels on the final ingest because the final ingest is
+            // the ONE message guaranteed to be sent — it is what releases the lease,
+            // and it is sent even when the turn failed.
+            backendSessionId,
+            backendName: backendSessionId ? session.agent.backend : undefined,
+            /*
+             * Reported with the handle, never separately. A handle whose owner is
+             * unknown is exactly the handle that caused this defect, so the control
+             * plane must never be able to hold one without the other.
+             */
+            backendOwnerId: backendSessionId && ownBackendInstanceId
+                ? ownBackendInstanceId
+                : undefined
+        };
+        /*
+         * WHAT THE MODEL WAS TOLD, AND WHAT IT SAID — recorded for the next turn.
+         *
+         * `session.input.content` and NOT the replayed prompt: the log is the
+         * conversation, and the replay preamble is scaffolding built FROM the log.
+         * Writing the preamble back in would nest the conversation inside itself,
+         * and it would do so once per turn, so the prompt would grow
+         * quadratically until the context window ended the session.
+         */
+        /*
+         * ONLY WHAT THIS TURN SAID.
+         *
+         * Belt and braces behind the `seenPartIds` seeding above. Both guard the
+         * same failure — a resumed session re-emitting its whole history into the
+         * model log — and they fail independently: the seeding depends on the
+         * adapter honouring `seenPartIds`, this depends only on what is already in
+         * our own store. The consequence of getting it wrong is not a wrong answer
+         * but a conversation that silently doubles in size every turn, which is the
+         * kind of defect that looks fine for a week.
+         */
+        const spoken = (0, conversation_1.assistantTextFrom)(this.turnParts.filter((part) => !priorPartIdsForLog.has(part.partId)));
+        const modelMessages = [
+            { role: 'user', content: turnContent },
+            ...(spoken ? [{ role: 'assistant', content: spoken }] : [])
+        ];
+        // Store locally FIRST, for the same reason parts are: the local copy is
+        // what lets this runner answer the next turn without a network call, and a
+        // send that happens first would be lost on a crash between the two.
+        try {
+            this.deps.conversation?.appendModelMessages(session.sessionId, modelMessages);
+        }
+        catch (caught) {
+            // A cache that cannot be written is a slow next turn, not a failed one.
+            this.logger.warn(`[SessionRunner] could not cache model messages for ` +
+                `${session.sessionId}: ` +
+                `${caught instanceof Error ? caught.message : String(caught)}`);
+        }
+        // The FINAL ingest carries the turn metadata and releases the lease. It is
+        // sent even when the turn failed: a lease that is never released is a
+        // session that hangs until the watchdog reaps it, and the user waits.
+        /*
+         * THE FINAL FLUSH MUST CARRY ANY PARTS STILL PENDING, not an empty array.
+         *
+         * `this.pending` is otherwise drained only INSIDE `drain()`, so anything
+         * recorded after it returns never reached the control plane. That silently
+         * broke the error path: the catch block below records the failure as a
+         * transcript part and its comment calls that "the transcript's last word",
+         * but the part went into the local store and no further — the user was left
+         * with a conversation that stopped answering and never said why.
+         *
+         * Sending `[]` here was safe only for as long as nothing was recorded after
+         * the drain. That has not been true since the error path was added.
+         */
+        await this.flush(session.sessionId, this.pending.splice(0), turn, true, modelMessages);
+        this.deps.telemetry.record('provider.turn.memory', {
+            resumed,
+            replayed,
+            priorMessages: this.priorMessageCount
+        });
+        this.deps.telemetry.record('provider.session.stopped', {
+            backend: session.agent.backend,
+            stopReason
+        });
+        return {
+            turn,
+            maxRev: this.deps.store.getMaxRev(session.sessionId),
+            partsProduced
+        };
+    }
+    /* ---------------------------------------------------------------- */
+    /* The poll loop                                                     */
+    /* ---------------------------------------------------------------- */
+    /**
+     * Does this polled part merely mirror the prompt the runner itself sent?
+     *
+     * Matched on TEXT, not on id, because the echo's id belongs to the backend
+     * (`user-message-3`, `user-173…`, `<uuid>-text`) and no runner can predict
+     * it. Matched as a PREFIX of the sent prompt, not equality, because ACP
+     * agents deliver the echo as `user_message_chunk` updates whose accumulated
+     * text grows to the full prompt over several polls — dropping only the final
+     * equal one would strand the intermediate versions in the store.
+     *
+     * Both sides are trimmed first: a backend that strips a trailing newline
+     * from the echoed text must not slip past the prefix check on that alone.
+     */
+    isEchoOfTurnPrompt(part, sentPromptText) {
+        if (typeof part.role !== 'string' || part.role.toLowerCase() !== 'user') {
+            return false;
+        }
+        const text = part.content ?? part.text;
+        if (typeof text !== 'string')
+            return false;
+        const echoed = text.trim();
+        if (echoed.length === 0)
+            return false;
+        return sentPromptText.trim().startsWith(echoed);
+    }
+    /**
+     * Poll the adapter until the turn goes quiet or the signal aborts.
+     *
+     * The adapter's `onDataAvailable` callback wakes this immediately when the
+     * backend has buffered output, so the 2s interval is a FLOOR for liveness
+     * rather than the streaming latency. Without it every token would arrive up
+     * to two seconds late and the UI would look broken.
+     */
+    /**
+     * Pump the backend until it goes quiet, returning what was produced AND any
+     * provider error the backend reported.
+     *
+     * THE ERROR HALF OF THE RETURN IS THE POINT. `getStatus` reports a provider
+     * failure as `type: 'error'` with a message, and this loop used to fold that
+     * into `quiet` alongside `idle` — it stopped draining, which is correct, and
+     * then threw the message away, which is not. The turn went on to be recorded
+     * as `stopReason: 'completed'` with `error: null`.
+     *
+     * That is not theoretical. On 2026-08-22 a gateway stopped serving the
+     * configured model; five consecutive turns logged
+     * `Provider error … Invalid model name passed in model=gpt-4.1`, produced no
+     * assistant output at all, and were all stored as SUCCESSFUL turns. The UI
+     * faithfully showed five user messages and no replies, the runner showed
+     * `ready`, and nothing anywhere said the model call had failed.
+     */
+    async drain(adapter, backendSessionId, config, session, signal, alreadySeenPartIds = new Set(), 
+    /** The exact text `sendPrompt` was given this turn, for echo filtering. */
+    sentPromptText = null) {
+        let providerError;
+        let timedOut = false;
+        let idleTimedOut = false;
+        let idleTimedOutMessage;
+        const seenMessageIds = new Set();
+        const seenPartIds = new Set(alreadySeenPartIds);
+        const partContentLengths = new Map();
+        let produced = 0;
+        let idleSeen = 0;
+        let wake = null;
+        adapter.onDataAvailable = () => {
+            wake?.();
+        };
+        /*
+         * THE LAST-LINE CEILING. `null` means no operator-configured ceiling — see
+         * `LeasedLimits.maxTurnDurationMs`. `<= 0` is treated THE SAME WAY, not as
+         * "expire immediately": the control plane already normalises an explicit
+         * `0` env value to `null` before it ever reaches the wire (config.ts
+         * `maxTurnDurationMsFromEnv`), so a real lease never carries a zero or
+         * negative number on purpose. Treating one as "no ceiling" here — rather
+         * than as an instantly-past deadline — is what keeps this side of the
+         * wire consistent with that normalisation, and is also just the safer
+         * reading of a value nothing should ever legitimately send.
+         */
+        const hardCeilingMs = session.limits.maxTurnDurationMs;
+        const hardDeadline = hardCeilingMs === null ||
+            hardCeilingMs === undefined ||
+            hardCeilingMs <= 0
+            ? null
+            : Date.now() + hardCeilingMs;
+        const softWarningAt = hardDeadline === null
+            ? null
+            : Date.now() + hardCeilingMs * HARD_CEILING_WARNING_FRACTION;
+        let softWarningSent = false;
+        /*
+         * THE PRIMARY GUARD. Reset on every part, tool-call start/end or streamed
+         * text — anything `pollMessages` returns as a new part. `lastProgressAt`
+         * plus the approval total captured AT that moment is enough to compute,
+         * later, exactly how much of the time since then was genuine silence
+         * versus a human being waited on — see the idle check below.
+         */
+        const idleLimitMs = session.limits.maxTurnIdleMs ?? DEFAULT_MAX_TURN_IDLE_MS;
+        let lastProgressAt = Date.now();
+        let approvalWaitAtLastProgress = this.approvalWaitMs;
+        try {
+            while (!signal.aborted) {
+                const now = Date.now();
+                // Historical approval wait PLUS whatever approval is open right now.
+                // Added to both the hard deadline and, below, the idle window — a
+                // turn stopped to ask a person something is blocked on them, not
+                // running away, and ten minutes is an entirely ordinary time for a
+                // person to be away from their desk.
+                const pausedMs = this.approvalWaitMs + this.liveApprovalWaitMs();
+                if (hardDeadline !== null && now > hardDeadline + pausedMs) {
+                    timedOut = true;
+                    break;
+                }
+                /*
+                 * THE SOFT WARNING, once, at 90% of a CONFIGURED ceiling. Written to
+                 * the transcript unconditionally; also offered to the backend as a
+                 * mid-turn nudge when the adapter can take one (`steerTurn`) — so the
+                 * turn has a chance to end with a summary instead of a cut.
+                 */
+                if (softWarningAt !== null &&
+                    !softWarningSent &&
+                    now > softWarningAt + pausedMs) {
+                    softWarningSent = true;
+                    const remainingMs = Math.max(0, hardDeadline + pausedMs - now);
+                    produced += await this.warnOfHardCeiling(adapter, backendSessionId, config, session, remainingMs);
+                }
+                /*
+                 * THE PI MODEL-KEY EXPIRY NOTICE — a disclosed gap, not a silent
+                 * failure. `updateModelCredential` can push a refreshed token into a
+                 * backend that implements `notifyConfigChanged` (OpenCode); one that
+                 * does not (currently Pi, whose credential is fixed in its child
+                 * process's environment at spawn) keeps running on whatever key it
+                 * started with even after the control plane has moved on. Once that
+                 * key's known expiry passes, this backend's NEXT model call is about
+                 * to fail with an ordinary-looking auth error that reads as a random
+                 * provider outage. Surfaced here instead, once, with the real reason.
+                 * Never fires for a sandbox turn: its per-SANDBOX key carries no
+                 * `modelTokenExpiresAt` to begin with (see `buildLeaseBody`).
+                 */
+                if (!this.modelKeyExpiryNoticeShown &&
+                    this.modelTokenExpiresAt &&
+                    typeof adapter.notifyConfigChanged !== 'function' &&
+                    now > Date.parse(this.modelTokenExpiresAt)) {
+                    this.modelKeyExpiryNoticeShown = true;
+                    this.logger.warn(`[SessionRunner] model-key-expired-mid-turn session=${session.sessionId} ` +
+                        `backend=${session.agent.backend} expiredAt=${this.modelTokenExpiresAt}`);
+                    produced += this.record(session.sessionId, [
+                        {
+                            id: `model-key-expired-${(0, node_crypto_1.randomUUID)()}`,
+                            role: 'system',
+                            partType: 'error',
+                            content: 'Model credential expired after 1 hour on this runner; send a new message to continue.'
+                        }
+                    ]);
+                    await this.flush(session.sessionId, this.pending.splice(0), undefined, false);
+                }
+                const parts = (await adapter.pollMessages(backendSessionId, seenMessageIds, seenPartIds, partContentLengths, config));
+                /*
+                 * THE PROMPT'S OWN ECHO IS NOT CONVERSATION.
+                 *
+                 * The user's message is written into the transcript by the control
+                 * plane when the turn is enqueued (`enqueueTurn` →
+                 * `recordUserTurnPart`), so it is durable before this runner is even
+                 * aware of the turn. Several backends ALSO echo the prompt back
+                 * through `pollMessages` — Codex pushes a synthetic user message into
+                 * its buffer, ACP agents stream `user_message` chunks, the Claude Code
+                 * SDK re-emits streamed input — and recording that echo would put the
+                 * same words in the transcript TWICE under two part ids, which no
+                 * idempotency key can merge.
+                 *
+                 * So anything a backend emits as a user part whose text is the prompt
+                 * this runner just handed it — or a streaming prefix of it — is
+                 * dropped. This is safe because every user word reaches the backend
+                 * through `sendPrompt`: mid-turn there is no OTHER user text it could
+                 * be. Answers to questions travel a different wire (`respondTo*`) and
+                 * are recorded by the answer path itself, with the `answer-…` part id.
+                 */
+                const freshParts = sentPromptText && sentPromptText.length > 0
+                    ? parts.filter((part) => !this.isEchoOfTurnPrompt(part, sentPromptText))
+                    : parts;
+                /*
+                 * WIRE 2: A PENDING PERMISSION BECOMES A TRANSCRIPT PART.
+                 *
+                 * Checked BEFORE the produced-parts branch `continue`s, or an approval
+                 * raised in the same pass as some output would not be seen until the
+                 * backend next went quiet — which, while it waits for the very approval
+                 * we failed to show, is never.
+                 */
+                produced += await this.emitPendingApproval(adapter, backendSessionId, session);
+                if (freshParts.length > 0) {
+                    produced += this.record(session.sessionId, freshParts);
+                    await this.flush(session.sessionId, this.pending.splice(0), undefined, false);
+                    // Real output resets the quiet counter. A backend is idle BETWEEN
+                    // tool calls as well as at the end of a turn, so ending on the first
+                    // idle would truncate almost every transcript at the first tool.
+                    idleSeen = 0;
+                    // ...and resets the PRIMARY guard's clock, snapshotting the
+                    // approval total so a later stretch of silence is measured from
+                    // here, not double-counting wait time already excluded once.
+                    lastProgressAt = Date.now();
+                    approvalWaitAtLastProgress = this.approvalWaitMs;
+                    continue;
+                }
+                const status = await adapter.getStatus(backendSessionId, config);
+                if (status.type === 'error' && status.message) {
+                    // Last one wins: a retry that also fails should report its own reason.
+                    providerError = status.message;
+                }
+                const quiet = status.type === 'idle' || status.type === 'error';
+                idleSeen = quiet ? idleSeen + 1 : 0;
+                if (idleSeen >= IDLE_CONFIRMATIONS) {
+                    break;
+                }
+                /*
+                 * THE IDLE CHECK ITSELF. Wall-clock time since the last real progress,
+                 * minus whatever of that stretch was spent waiting on a human — the
+                 * approval accrued SINCE `lastProgressAt`, not the turn's whole
+                 * history, or a long-closed approval from earlier in the turn would be
+                 * subtracted a second time and silence that started long after it
+                 * closed would be under-counted.
+                 *
+                 * SKIPPED OUTRIGHT WHILE AN APPROVAL IS OPEN RIGHT NOW, rather than
+                 * trusted to the arithmetic above — the race that arithmetic cannot
+                 * close on its own: `emitPendingApproval` can OPEN a brand-new
+                 * approval in THIS SAME ITERATION, moments before this check runs,
+                 * so `liveApprovalWaitMs()` is still ~0 and barely dents an
+                 * `idleElapsed` that had already been accumulating stale silence for
+                 * up to `idleLimitMs`. Without this guard a question could be posted
+                 * and the turn cut as `no_progress` in the same tick, before the
+                 * person it was raised for ever sees it.
+                 *
+                 * TODO(approval TTL): an approval left open suppresses BOTH this
+                 * guard and the hard ceiling for as long as it stays open — by
+                 * design, since a slow human must never read as a hung backend, but
+                 * that means an approval nobody ever answers can hold a turn open
+                 * indefinitely today. Pre-existing behaviour (unrelated to the LONG
+                 * TURNS fix), not changed here; a bounded approval wait — after
+                 * which the turn ends on its own rather than waiting forever — is a
+                 * real follow-up, not implemented in this PR.
+                 */
+                const approvalWaitSinceProgress = this.approvalWaitMs -
+                    approvalWaitAtLastProgress +
+                    this.liveApprovalWaitMs();
+                const idleElapsed = Date.now() - lastProgressAt - approvalWaitSinceProgress;
+                if (this.approvalWaitStartedAt === null && idleElapsed > idleLimitMs) {
+                    this.logger.warn(`[SessionRunner] session ${session.sessionId} had no progress for ` +
+                        `${Math.round(idleElapsed / 1000)}s (limit ${Math.round(idleLimitMs / 1000)}s)`);
+                    idleTimedOut = true;
+                    idleTimedOutMessage = `Turn stopped: no progress for ${formatMinutes(idleLimitMs)}`;
+                    break;
+                }
+                // Wait for whichever comes first: the poll interval, the backend
+                // pushing (`wake`), or an abort. `finish` is idempotent because all
+                // three can fire, and a second `resolveWait` on a settled promise
+                // would otherwise leak the timer and the abort listener for the rest
+                // of the turn.
+                await new Promise((resolveWait) => {
+                    let settled = false;
+                    const timer = { handle: null };
+                    const finish = () => {
+                        if (settled) {
+                            return;
+                        }
+                        settled = true;
+                        if (timer.handle)
+                            clearTimeout(timer.handle);
+                        signal.removeEventListener('abort', finish);
+                        wake = null;
+                        resolveWait();
+                    };
+                    timer.handle = setTimeout(finish, POLL_INTERVAL_MS);
+                    wake = finish;
+                    signal.addEventListener('abort', finish, { once: true });
+                });
+            }
+        }
+        finally {
+            adapter.onDataAvailable = undefined;
+            // A part produced between the last flush and the loop ending must not be
+            // lost; the final ingest below only carries turn metadata.
+            if (this.pending.length > 0) {
+                await this.flush(session.sessionId, this.pending.splice(0), undefined, false);
+            }
+        }
+        if (signal.aborted || timedOut || idleTimedOut) {
+            try {
+                await adapter.abortPrompt(backendSessionId, config);
+            }
+            catch {
+                // An abort that cannot be delivered still ends the turn here.
+            }
+        }
+        return {
+            parts: produced,
+            providerError,
+            timedOut,
+            idleTimedOut,
+            idleTimedOutMessage
+        };
+    }
+    /**
+     * THE SOFT WARNING, fired once at 90% of a CONFIGURED hard ceiling.
+     *
+     * Always written into the transcript so the user sees the countdown even
+     * when the backend cannot take a mid-turn nudge. `steerTurn` is optional on
+     * `CodingAgentAdapter` for exactly that reason: Pi can deliver a message to
+     * a running turn (`streamingBehavior: 'steer'`); OpenCode's `sendPrompt` is
+     * a single long-lived HTTP call per session and calling it again while one
+     * is already in flight is not safe, so it does not implement this and the
+     * warning stays transcript-only there.
+     */
+    async warnOfHardCeiling(adapter, backendSessionId, config, session, remainingMs) {
+        const message = `You have ${formatMinutes(remainingMs)} left in this turn. ` +
+            'Commit your work, write a short status, and stop.';
+        // THE RETURN VALUE MATTERS. This part must count toward `produced` in
+        // `drain()`'s caller, the same as every other part recorded there —
+        // otherwise the turn's reported `partsProduced` silently undercounts by
+        // one on every turn a configured ceiling's 90% mark actually fires.
+        const produced = this.record(session.sessionId, [
+            {
+                id: `turn-warning-${(0, node_crypto_1.randomUUID)()}`,
+                role: 'system',
+                partType: 'text',
+                content: message
+            }
+        ]);
+        await this.flush(session.sessionId, this.pending.splice(0), undefined, false);
+        const steerTurn = adapter.steerTurn;
+        if (!steerTurn) {
+            this.logger.warn(`[SessionRunner] session ${session.sessionId}: backend '${session.agent.backend}' ` +
+                'cannot take a mid-turn message; the ceiling warning is transcript-only.');
+            return produced;
+        }
+        try {
+            await steerTurn.call(adapter, backendSessionId, message, config);
+        }
+        catch (caught) {
+            this.logger.warn(`[SessionRunner] session ${session.sessionId}: could not deliver the ` +
+                `ceiling warning to the backend: ${caught instanceof Error ? caught.message : String(caught)}`);
+        }
+        return produced;
+    }
+    /* ---------------------------------------------------------------- */
+    /* PERMISSION APPROVALS — wires 2 and 3 of defect G1                 */
+    /* ---------------------------------------------------------------- */
+    /** Wall-clock spent in the approval we are in RIGHT NOW, if any. */
+    liveApprovalWaitMs() {
+        return this.approvalWaitStartedAt === null
+            ? 0
+            : Date.now() - this.approvalWaitStartedAt;
+    }
+    /**
+     * WIRE 2. Turn a pending backend permission into a `question` transcript part.
+     *
+     * The whole channel below this already existed and was simply never joined
+     * up. The OpenCode adapter queues `permission.asked` events, reports
+     * `WAITING_APPROVAL` from `getStatus` while any are outstanding, and exposes
+     * `getPendingApproval`. The control plane already accepts an answer and
+     * queues it as a session command. The UI already renders a `question` part,
+     * already shows its options as buttons, and already posts `optionId` back.
+     * The only thing missing was somebody asking the adapter.
+     *
+     * THIS IS DELIBERATELY THE SAME SHAPE 20x EMITS (agent-manager.ts:2342-2367),
+     * because the two products render the same transcript and a second shape
+     * would mean a second renderer. ONE DIFFERENCE, ON PURPOSE: 20x builds its
+     * options as `{ label }` and throws `optionId` away, which forces its IPC
+     * layer to recover the choice by matching a display label against a hardcoded
+     * map of English strings (agent-manager.ts:4510-4516). We keep the id. Labels
+     * are ambiguous, repeatable between questions and translatable; ids are none
+     * of those things.
+     *
+     * `getPendingApproval` is DUCK-TYPED rather than declared on
+     * `CodingAgentAdapter` — again matching 20x — so a backend with no permission
+     * concept needs no stub and is simply never asked.
+     */
+    async emitPendingApproval(adapter, backendSessionId, session) {
+        const capable = adapter;
+        if (typeof capable.getPendingApproval !== 'function') {
+            return 0;
+        }
+        let approval;
+        try {
+            approval = capable.getPendingApproval(backendSessionId);
+        }
+        catch (error) {
+            // An adapter that throws here must not take the turn down with it: the
+            // turn is still running and its output is still worth collecting.
+            this.logger.warn(`[SessionRunner] getPendingApproval threw for session ${session.sessionId}: ${error instanceof Error ? error.message : String(error)}`);
+            return 0;
+        }
+        if (!approval) {
+            // The backend has stopped waiting. That happens on our own answer, and
+            // ALSO when the backend resolves the permission itself — a timeout, an
+            // abort, an auto-approve. Either way the turn is no longer blocked on a
+            // human, so the clock starts again and the harness may relax its polling.
+            this.closeApproval(session.sessionId);
+            return 0;
+        }
+        // Already shown. Do not re-emit: an upsert on the same partId is harmless
+        // to the transcript but would bump `rev` on every 2s pass, and the UI polls
+        // on the cursor — the conversation would flicker for as long as the user
+        // took to decide.
+        if (this.emittedApprovals.has(approval.toolCallId)) {
+            return 0;
+        }
+        this.emittedApprovals.add(approval.toolCallId);
+        const partId = `question-${approval.toolCallId}`;
+        const optionIdByLabel = new Map();
+        const knownOptionIds = new Set();
+        for (const option of approval.options) {
+            optionIdByLabel.set(option.name.trim().toLowerCase(), option.optionId);
+            knownOptionIds.add(option.optionId);
+        }
+        this.openApproval = {
+            partId,
+            toolCallId: approval.toolCallId,
+            optionIdByLabel,
+            knownOptionIds
+        };
+        if (this.approvalWaitStartedAt === null) {
+            this.approvalWaitStartedAt = Date.now();
+        }
+        this.deps.onApprovalStateChange?.(session.sessionId, true);
+        this.logger.log(`[SessionRunner] session ${session.sessionId} is waiting for approval: ${approval.question}`);
+        const produced = this.record(session.sessionId, [
+            {
+                id: partId,
+                role: 'assistant',
+                partType: 'question',
+                content: approval.question,
+                tool: {
+                    name: 'permission',
+                    status: 'running',
+                    title: approval.question
+                },
+                questions: [
+                    {
+                        header: 'Permission Required',
+                        question: approval.question,
+                        options: approval.options.map((option) => ({
+                            id: option.optionId,
+                            label: option.name
+                        }))
+                    }
+                ]
+            }
+        ]);
+        /*
+         * FLUSHED HERE, NOT LEFT FOR THE NEXT PASS.
+         *
+         * Every other part in this loop is flushed by the `parts.length > 0`
+         * branch. A question raised on a pass that produced no other output would
+         * otherwise sit in `this.pending` until the NEXT flush — and the next flush
+         * comes when the backend produces something, which it cannot do, because it
+         * is blocked on the question we did not send. The turn would hang with an
+         * empty transcript and no prompt: the exact "silently hangs" failure the
+         * ordering warning in this work's brief is about.
+         */
+        await this.flush(session.sessionId, this.pending.splice(0), undefined, false);
+        return produced;
+    }
+    /**
+     * Tell the USER that their answer could not be delivered.
+     *
+     * Without this, a failed delivery is a server-side log line and nothing else:
+     * the question card stays open, the turn keeps waiting (approval time is
+     * deliberately excluded from the turn deadline), and the person who clicked
+     * Allow has no way to tell their click from a slow backend. An error part is
+     * the only channel that reaches them.
+     *
+     * The approval is deliberately left OPEN — the backend never heard the
+     * answer, so the prompt is still genuinely outstanding and answering again is
+     * the right thing to do.
+     */
+    async reportApprovalFailure(sessionId, reason) {
+        if (!this.turnContext || this.turnContext.sessionId !== sessionId) {
+            return;
+        }
+        this.record(sessionId, [
+            {
+                id: `approval-error-${(0, node_crypto_1.randomUUID)()}`,
+                role: 'system',
+                partType: 'error',
+                content: 'Your answer could not be delivered to the agent, so the request is ' +
+                    `still waiting. Please answer it again. (${reason})`
+            }
+        ]);
+        await this.flush(sessionId, this.pending.splice(0), undefined, false);
+    }
+    /**
+     * MID-TURN MODEL-CREDENTIAL REFRESH — the LONG TURNS audit's answer to a
+     * fixed per-turn LiteLLM key TTL. Called from the harness's lease-renewal
+     * callback when the control plane re-mints the token near its old expiry.
+     *
+     * Updates the shared gateway holder unconditionally (so the NEXT model call
+     * on this turn already uses it), then asks the adapter to push it to a
+     * running backend that can take a live config update. `notifyConfigChanged`
+     * is optional on `CodingAgentAdapter` for exactly this reason: OpenCode
+     * implements it (a shared server, config pushed over HTTP); Pi does not —
+     * its credential is fixed in the child process's environment at spawn, so a
+     * refresh here updates the holder for the SAME session's next turn (a fresh
+     * Pi process) but not the one currently running. That is a real, disclosed
+     * gap, not a silent one: Pi turns still rely on the 1h key outlasting the
+     * turn, same as before this method existed — `expiresAt` is recorded
+     * regardless, so `drain()`'s expiry notice still fires on the correct
+     * (refreshed) deadline rather than the original, already-superseded one.
+     */
+    updateModelCredential(sessionId, apiKey, expiresAt) {
+        if (!this.turnContext || this.turnContext.sessionId !== sessionId) {
+            return;
+        }
+        if (expiresAt) {
+            this.modelTokenExpiresAt = expiresAt;
+            this.modelKeyExpiryNoticeShown = false;
+        }
+        this.deps.modelGateway?.updateApiKey(apiKey);
+        try {
+            void this.turnContext.adapter.notifyConfigChanged?.();
+        }
+        catch {
+            // A backend that cannot take the push keeps running on its old
+            // credential until it, too, expires — not ideal, but no worse than
+            // before this method existed, and never worth ending the turn over.
+        }
+    }
+    /** Stop the approval clock and tell the harness it may relax. */
+    closeApproval(sessionId) {
+        if (this.approvalWaitStartedAt !== null) {
+            this.approvalWaitMs += Date.now() - this.approvalWaitStartedAt;
+            this.approvalWaitStartedAt = null;
+        }
+        if (this.openApproval) {
+            this.openApproval = null;
+            this.deps.onApprovalStateChange?.(sessionId, false);
+        }
+    }
+    closeQuestion(sessionId) {
+        if (this.openQuestionPartId) {
+            this.openQuestionPartId = null;
+            this.deps.onApprovalStateChange?.(sessionId, false);
+        }
+    }
+    /**
+     * WIRE 3. Apply an `answer` session command to the running turn.
+     *
+     * Before this existed, `harness.applyCommand` marked an `answer` as applied
+     * and DROPPED IT. That is what made the permission mode unshippable rather
+     * than merely unenforced: turning the mode on without this would have turned
+     * "silently unrestricted" into "silently hangs on every turn", and because
+     * the default agent stores `permissionMode: 'default'`, it would have hit
+     * every session at once.
+     *
+     * Returns true when the answer reached the backend.
+     */
+    async answerPendingApproval(command) {
+        const context = this.turnContext;
+        if (!context || context.sessionId !== command.sessionId) {
+            return 'ignored';
+        }
+        const open = this.openApproval;
+        if (!open) {
+            /*
+             * A NORMAL AGENT QUESTION, NOT A PERMISSION PROMPT.
+             *
+             * Both kinds are rendered as `partType: question` and travel back over
+             * the same `answer` command, but only permission prompts populate
+             * `openApproval`. The old code returned `ignored` here, even though every
+             * extracted adapter already exposes `respondToQuestion`. Consequently a
+             * click on an ordinary question reached the runner and vanished.
+             */
+            const capable = context.adapter;
+            if (!this.openQuestionPartId) {
+                this.logger.warn(`[SessionRunner] answer for session ${command.sessionId} arrived with no open question; ignoring`);
+                return 'ignored';
+            }
+            if (command.partId && command.partId !== this.openQuestionPartId) {
+                this.logger.warn(`[SessionRunner] answer for session ${command.sessionId} names part ${command.partId}, but ${this.openQuestionPartId} is open; ignoring`);
+                return 'ignored';
+            }
+            if (typeof capable.respondToQuestion !== 'function') {
+                this.logger.warn(`[SessionRunner] answer for session ${command.sessionId} arrived with no open approval and this backend cannot answer ordinary questions; ignoring`);
+                return 'ignored';
+            }
+            const answers = decodeQuestionAnswers(command.answer);
+            if (Object.keys(answers).length === 0) {
+                this.logger.warn(`[SessionRunner] empty answer for ordinary question on session ${command.sessionId}; ignoring`);
+                return 'ignored';
+            }
+            try {
+                const delivered = await capable.respondToQuestion(context.backendSessionId, answers, context.config, command.partId ?? this.openQuestionPartId);
+                if (delivered === false ||
+                    (typeof delivered === 'object' && delivered.handled === false)) {
+                    this.logger.error(`[SessionRunner] backend reported it did not accept the question answer for session ${command.sessionId}`);
+                    return 'failed';
+                }
+            }
+            catch (error) {
+                this.logger.error(`[SessionRunner] failed to deliver question answer for session ${command.sessionId}: ${error instanceof Error ? error.message : String(error)}`);
+                return 'failed';
+            }
+            // This user part closes the question card and restores the ordinary
+            // composer. Without it every later message is posted as another answer.
+            this.record(context.sessionId, [
+                {
+                    id: `answer-${command.partId ?? (0, node_crypto_1.randomUUID)()}`,
+                    role: 'user',
+                    partType: 'text',
+                    content: command.answer ?? Object.values(answers).join('\n')
+                }
+            ]);
+            await this.flush(context.sessionId, this.pending.splice(0), undefined, false);
+            this.closeQuestion(context.sessionId);
+            return 'delivered';
+        }
+        /*
+         * THE ANSWER MUST NAME THE QUESTION IT IS ANSWERING.
+         *
+         * The UI posts back the `partId` of the card the user clicked. If that is
+         * not the prompt currently outstanding, the user answered a DIFFERENT
+         * question — a stale tab, a double click, a card still on screen after the
+         * backend moved on. Applying it would attach a human's "yes" to a tool call
+         * they never read. `partId` is optional in the contract, so an answer
+         * without one is accepted; an answer with the WRONG one never is.
+         */
+        if (command.partId && command.partId !== open.partId) {
+            this.logger.warn(`[SessionRunner] answer for session ${command.sessionId} names part ${command.partId}, but ${open.partId} is open; ignoring`);
+            return 'ignored';
+        }
+        const decision = resolveApproval(command, open);
+        const capable = context.adapter;
+        if (typeof capable.respondToApproval !== 'function') {
+            this.logger.warn(`[SessionRunner] backend for session ${command.sessionId} cannot take an approval response`);
+            return 'ignored';
+        }
+        this.logger.log(`[SessionRunner] answering approval on session ${command.sessionId}: approved=${decision.approved} optionId=${decision.optionId ?? '(none)'}`);
+        try {
+            /*
+             * THE RETURN VALUE IS LOAD-BEARING. An adapter reports a failed delivery
+             * by RESOLVING FALSE as well as by throwing — OpenCode's HTTP relay does
+             * exactly that on a non-OK status. Ignoring it meant a failed delivery was
+             * recorded as 'delivered': the card closed, the transcript said
+             * "Approved", and the backend had never heard the answer.
+             */
+            const delivered = await capable.respondToApproval(context.backendSessionId, decision.approved, decision.optionId);
+            if (delivered === false) {
+                this.logger.error(`[SessionRunner] backend reported it did not accept the approval for session ${command.sessionId}`);
+                return 'failed';
+            }
+        }
+        catch (error) {
+            /*
+             * 'failed', NOT 'ignored'. THIS RETURN IS THE WHOLE POINT OF THE TYPE.
+             *
+             * It used to return `false`, the same value a stale or duplicate answer
+             * returns — so the harness could not tell a lost approval from a no-op,
+             * and its recovery path (forget the commandId, tell the user) was
+             * UNREACHABLE CODE. The comment there described a failure mode the code
+             * could not actually handle.
+             *
+             * The approval is deliberately left OPEN: the backend never heard the
+             * answer, so the prompt is genuinely still outstanding.
+             */
+            this.logger.error(`[SessionRunner] failed to deliver approval for session ${command.sessionId}: ${error instanceof Error ? error.message : String(error)}`);
+            return 'failed';
+        }
+        /*
+         * THE ANSWER GOES INTO THE TRANSCRIPT, AS A USER PART.
+         *
+         * Two reasons, and the second is not cosmetic.
+         *
+         * 1. The exit test asks for "the request, the answer and the result". This
+         *    is the answer.
+         * 2. `selectOpenQuestion` in the UI decides a question is still open by
+         *    looking for ANY user part after it (projection.ts:605-608). Without a
+         *    user part here the card would stay open and interactive for ever, and
+         *    the composer would keep posting answers instead of messages — so the
+         *    user could never send another message in that session again.
+         */
+        this.record(context.sessionId, [
+            {
+                id: `answer-${open.toolCallId}`,
+                role: 'user',
+                partType: 'text',
+                content: decision.transcriptText
+            }
+        ]);
+        await this.flush(context.sessionId, this.pending.splice(0), undefined, false);
+        this.closeApproval(context.sessionId);
+        return 'delivered';
+    }
+    /* ---------------------------------------------------------------- */
+    /* Store, then send                                                  */
+    /* ---------------------------------------------------------------- */
+    pending = [];
+    /**
+     * Everything this turn projected, in order.
+     *
+     * Reset at the start of every `run`. Used only to derive the assistant half
+     * of the model-facing log; the transcript itself is already stored by then.
+     */
+    turnParts = [];
+    /**
+     * STORE FIRST, SEND SECOND, and never the other way round.
+     *
+     * The local store is what lets a harness survive its own crash; if a part
+     * were sent before it was stored, a crash between the two would leave the
+     * control plane holding a part the runner does not know it produced, and a
+     * resumed turn would produce it again with a NEW id — a visible duplicate in
+     * the user's transcript. Storing first makes the send idempotent, because the
+     * upsert is keyed on (sessionId, partId).
+     */
+    record(sessionId, raw) {
+        for (const part of raw) {
+            const partType = part?.partType ?? part?.type;
+            if (part?.id &&
+                partType === 'question' &&
+                part.id !== this.openApproval?.partId &&
+                this.openQuestionPartId !== part.id) {
+                this.openQuestionPartId = part.id;
+                this.deps.onApprovalStateChange?.(sessionId, true);
+            }
+        }
+        const projected = (0, projection_1.projectParts)(raw);
+        if (projected.length === 0) {
+            return 0;
+        }
+        const { maxRev } = this.deps.store.upsertParts(sessionId, projected);
+        this.deps.events.transcriptChanged(sessionId, maxRev);
+        // Kept so the turn can build its MODEL-facing log from what was actually
+        // produced. `this.turnParts` is reset per turn by `run`.
+        for (const part of projected) {
+            this.turnParts.push({
+                partId: part.partId,
+                role: part.role,
+                partType: part.partType,
+                content: part.content
+            });
+        }
+        for (const part of projected) {
+            this.pending.push((0, projection_1.toIngestPart)(part));
+        }
+        return projected.length;
+    }
+    /**
+     * Push a batch to the control plane, chunked to the contract's ceiling.
+     *
+     * The ceiling is enforced HERE rather than discovered as an opaque rejection
+     * mid-turn. `MAX_INGEST_PARTS` is shared with the control plane precisely so
+     * both sides agree on it; a limit only one side knows is not a limit.
+     */
+    async flush(sessionId, parts, turn, final, modelMessages) {
+        if (parts.length === 0 && !final && turn === undefined) {
+            return;
+        }
+        // Oversized parts are dropped with a note rather than sent to be refused.
+        // A single enormous tool result must not take the rest of the batch down.
+        const sendable = parts.filter((part) => {
+            const size = (0, contract_1.ingestPartByteLength)(part);
+            if (size <= 1_000_000) {
+                return true;
+            }
+            this.logger.warn(`[SessionRunner] dropping oversized part ${part.partId} (${size} bytes)`);
+            return false;
+        });
+        const chunks = [];
+        for (let i = 0; i < sendable.length; i += contract_1.MAX_INGEST_PARTS) {
+            chunks.push(sendable.slice(i, i + contract_1.MAX_INGEST_PARTS));
+        }
+        if (chunks.length === 0) {
+            chunks.push([]);
+        }
+        for (let i = 0; i < chunks.length; i += 1) {
+            const isLast = i === chunks.length - 1;
+            await this.deps.ingest(sessionId, chunks[i], isLast ? turn : undefined, isLast ? final : false, isLast ? modelMessages : undefined);
+        }
+    }
+    /* ---------------------------------------------------------------- */
+    /* Wiring                                                            */
+    /* ---------------------------------------------------------------- */
+    /**
+     * WHERE `resumeFromRev` FINALLY DOES SOMETHING.
+     *
+     * The field was specified in the frozen contract, declared in `types.ts`,
+     * documented in the README and named in three test files. The control plane
+     * computed it and put it on every lease. Nothing in the runtime had ever read
+     * it. This is the read.
+     *
+     * ITS MEANING, taken from the contract's own comment: "the harness already
+     * holds transcript up to this rev and need not replay it. Null means start
+     * cold." So it is a statement about what the SERVER has, which the runner
+     * compares against what IT has:
+     *
+     *   null                    -> a brand-new conversation. Nothing to load.
+     *   local maxRev >= it      -> this runner ran the earlier turns and its
+     *                              cache is current. No network call.
+     *   local maxRev  < it      -> this runner is behind, or has never seen this
+     *                              session at all. The control plane is the only
+     *                              place the conversation still exists; fetch it.
+     *
+     * That third case is the one that matters, and it is not an edge case: it is
+     * every cold sandbox, every redeployed runner, and every turn that happens to
+     * be leased to a different machine than the one before it.
+     *
+     * NEVER THROWS. A conversation that cannot be loaded is a turn that starts
+     * cold — degraded, and worth a warning — whereas a throw here would refuse a
+     * turn the user is waiting on. The warning is loud because a fleet silently
+     * forgetting everything is precisely the failure this whole change exists to
+     * end.
+     */
+    priorMessageCount = 0;
+    async loadMemory(session, ownBackendInstanceId) {
+        this.priorMessageCount = 0;
+        const store = this.deps.conversation;
+        const local = store?.getModelMessages(session.sessionId) ?? [];
+        const localCheckpoint = store?.getCheckpoint(session.sessionId) ?? null;
+        /*
+         * Only meaningful when the checkpoint we are about to RESUME is the local
+         * one. If the lease hands us a different backend session, the local record
+         * describes a session we are not reusing, and comparing against it would
+         * rebuild for no reason.
+         */
+        const permissionDecision = localCheckpoint?.backendSessionId &&
+            (session.backendSessionId ?? localCheckpoint.backendSessionId) ===
+                localCheckpoint.backendSessionId
+            ? localCheckpoint.permissionDecision
+            : undefined;
+        /*
+         * A CHECKPOINT MINTED BY A DIFFERENT BACKEND *INSTANCE* IS NOT A CHECKPOINT
+         * EITHER — and this, not the backend-kind check below, is what had never
+         * once worked.
+         *
+         * A Pi session file is a key into ONE Pi agent directory. The control plane
+         * stores whatever the last runner reported and hands it to whoever takes
+         * the next turn, so the moment a conversation is leased to a SECOND runner
+         * the handle stops meaning anything: the second runner's Pi store has never
+         * heard of it, answers "Session not found", and the whole history is
+         * replayed and re-billed. Measured on the owner's machine, one conversation
+         * bounced between a laptop runner and a cloud-sandbox runner reached over
+         * ngrok and did exactly this on every turn after the second runner joined.
+         *
+         * Turns 2 to 7 of that same conversation DID resume — across three
+         * successive runner restarts — because all three processes used one durable
+         * Pi agent directory. That is the whole rule, and
+         * it is why the identity is the state directory rather than the process.
+         *
+         * FAIL-SAFE DIRECTION. Unknown ownership is read as "not mine": replaying
+         * once is recoverable, resuming somebody else's handle is not. A backend
+         * that cannot report an instance id keeps the previous behaviour rather
+         * than being refused outright.
+         */
+        const mine = (checkpoint) => {
+            if (!checkpoint)
+                return false;
+            if (!ownBackendInstanceId)
+                return true; // backend cannot say; unchanged.
+            return checkpoint.backendOwnerId === ownBackendInstanceId;
+        };
+        const leaseCheckpoint = session.backendSessionId
+            ? {
+                backendSessionId: session.backendSessionId,
+                backend: session.backendName ?? null,
+                backendOwnerId: session.backendOwnerId ?? null
+            }
+            : null;
+        /*
+         * The lease is still PREFERRED — the control plane saw the last turn
+         * wherever it ran, and this runner may only have seen an older one — but
+         * only among checkpoints this runner can actually honour.
+         */
+        const usable = [leaseCheckpoint, localCheckpoint].find((candidate) => mine(candidate ?? null));
+        if (!usable && (leaseCheckpoint || localCheckpoint)) {
+            /*
+             * LOG, NOT WARN, AND NOT "could not resume".
+             *
+             * Nothing failed. The conversation is simply being continued somewhere it
+             * has never run, which is an ordinary consequence of a session that can
+             * be leased to any runner. Logging it as a failure is what made a
+             * fallback that ran on every single turn look like a rare edge case.
+             */
+            this.logger.log(`[SessionRunner] session ${session.sessionId} has a checkpoint from ` +
+                `another backend instance (${leaseCheckpoint?.backendOwnerId ??
+                    localCheckpoint?.backendOwnerId ??
+                    'unknown'}); this runner is ${ownBackendInstanceId ?? 'unidentified'}. ` +
+                'Replaying history once into a session of its own.');
+        }
+        let backendSessionId = usable?.backendSessionId ?? null;
+        /*
+         * A CHECKPOINT MINTED BY A DIFFERENT BACKEND IS NOT A CHECKPOINT.
+         *
+         * An OpenCode session id handed to Claude Code is not a session, it is a
+         * string; resuming it fails confusingly, while ignoring it replays cleanly.
+         * This arises for an ordinary reason — an administrator changes the agent's
+         * backend part-way through a conversation.
+         *
+         * The lease's `backendName` is consulted FIRST and the local checkpoint
+         * second. An earlier version checked only the local record, which meant the
+         * guard could not fire on a cold runner — precisely the runner most likely
+         * to be handed a checkpoint it cannot use.
+         */
+        const checkpointBackend = usable?.backend ?? null;
+        if (backendSessionId &&
+            checkpointBackend &&
+            checkpointBackend !== session.agent.backend) {
+            this.logger.warn(`[SessionRunner] session ${session.sessionId} carries a checkpoint from ` +
+                `backend "${checkpointBackend}" but this turn runs on ` +
+                `"${session.agent.backend}". Replaying history into a fresh session.`);
+            backendSessionId = null;
+        }
+        const serverRev = session.resumeFromRev;
+        if (serverRev === null || serverRev === undefined) {
+            // A brand-new conversation. `local` is normally empty here; if it is not,
+            // it is stale state for a reused session id and must not be replayed.
+            this.priorMessageCount = 0;
+            return { backendSessionId, messages: [], permissionDecision };
+        }
+        const localRev = this.deps.store.getMaxRev(session.sessionId);
+        if (local.length > 0 && localRev >= serverRev) {
+            this.priorMessageCount = local.length;
+            return { backendSessionId, messages: local, permissionDecision };
+        }
+        if (!this.deps.fetchHistory) {
+            this.logger.warn(`[SessionRunner] session ${session.sessionId} has server history ` +
+                `(resumeFromRev=${serverRev}) that this runner does not hold, and no ` +
+                'history read path is wired. The turn will start without it.');
+            this.priorMessageCount = local.length;
+            return { backendSessionId, messages: local, permissionDecision };
+        }
+        try {
+            const remote = await this.deps.fetchHistory(session.sessionId);
+            // Cache it, so a second turn on this runner costs no network call.
+            try {
+                store?.replaceModelMessages(session.sessionId, remote.messages);
+            }
+            catch {
+                /* a cache that will not write is a slow turn, not a failed one */
+            }
+            this.priorMessageCount = remote.messages.length;
+            /*
+             * THE SAME OWNERSHIP TEST, ON THE PATH THAT NEEDED IT MOST.
+             *
+             * `remote` carries the checkpoint from the SAME control-plane row the
+             * guard above already refused, so taking it here would quietly undo that
+             * refusal — and it would do so on a COLD runner, which the comment above
+             * calls "precisely the runner most likely to be handed a checkpoint it
+             * cannot use". That is not an edge case: an empty local store plus a
+             * server-side history is the definition of a session that has just moved
+             * between machines, which is the whole defect this change exists to fix.
+             *
+             * `mine()` rather than a second inline comparison, so the two paths
+             * cannot drift.
+             */
+            const remoteCheckpoint = remote.backendSessionId
+                ? {
+                    backendSessionId: remote.backendSessionId,
+                    backendOwnerId: remote.backendOwnerId ?? null
+                }
+                : null;
+            if (remoteCheckpoint && !mine(remoteCheckpoint)) {
+                this.logger.log(`[SessionRunner] session ${session.sessionId}: the history read ` +
+                    `carries a checkpoint from another backend instance ` +
+                    `(${remoteCheckpoint.backendOwnerId ?? 'unknown'}); this runner is ` +
+                    `${ownBackendInstanceId ?? 'unidentified'}. Replaying instead.`);
+            }
+            /*
+             * MERGE NOTE (#1591 × #1602). Both changes rewrote this return.
+             *
+             * #1591 gates the remote handle behind `mine()` — a checkpoint minted by
+             * another backend instance is not a checkpoint here, and this cold path
+             * is exactly where that happens.
+             *
+             * #1602 reports the permission decision, which the control plane does not
+             * carry, so it is only known when the session we end up on is the one we
+             * already hold locally.
+             *
+             * The two compose once the gate runs FIRST: resolve the id, then ask
+             * whether that resolved id is the local one. Computing the decision from
+             * `remote.backendSessionId` — as #1602 did — would answer for a handle the
+             * gate has just refused.
+             */
+            const resolvedBackendSessionId = (remoteCheckpoint && mine(remoteCheckpoint)
+                ? remoteCheckpoint.backendSessionId
+                : null) ?? backendSessionId;
+            return {
+                backendSessionId: resolvedBackendSessionId,
+                messages: remote.messages,
+                permissionDecision: resolvedBackendSessionId === backendSessionId
+                    ? permissionDecision
+                    : undefined
+            };
+        }
+        catch (caught) {
+            this.logger.warn(`[SessionRunner] could not load history for ${session.sessionId}: ` +
+                `${caught instanceof Error ? caught.message : String(caught)}. ` +
+                'The turn will start with whatever this runner holds locally.');
+            this.priorMessageCount = local.length;
+            return { backendSessionId, messages: local, permissionDecision };
+        }
+    }
+    /**
+     * Authorise this session for exactly the secrets it was granted.
+     *
+     * Returns null when the host has no secret broker, which is the ordinary case
+     * on a runner — see `NoSecretProvider`, where holding no vendor credential is
+     * a security position rather than a gap.
+     */
+    setUpSecrets(session) {
+        if (this.deps.secrets.getBrokerPort() === null) {
+            return null;
+        }
+        const token = (0, node_crypto_1.randomUUID)();
+        this.deps.secrets.registerSession(token, session.agent.agentId, []);
+        return token;
+    }
+    /**
+     * Build the backend's session config.
+     *
+     * EVERY MCP SERVER GOES THROUGH THE LOOPBACK PROXY. The real gateway URL and
+     * the session token never reach the backend, never land in an MCP config file
+     * on disk, and never appear in the backend's own session state — so a leaked
+     * workspace does not leak the tenant's tool access. This is also what makes
+     * the token refreshable mid-session, which is the defect the proxy was
+     * originally written for.
+     *
+     * `allowedTools` from the lease is NOT enforced here, and that is deliberate.
+     * It is advisory — for generating AGENTS.md and for what the UI shows. THE
+     * GATEWAY IS AUTHORITATIVE, because a harness on a customer VM is outside our
+     * security perimeter and trusting it to filter its own tools is exactly
+     * defect G2.
+     */
+    buildSessionConfig(session, workspaceDir, secretToken, signal) {
+        const mcpServers = {};
+        for (const server of session.agent.mcpServers) {
+            const proxied = this.deps.proxy.registerTarget(server.url, server.name);
+            mcpServers[server.name] = {
+                name: server.name,
+                type: 'http',
+                // A null proxy URL means the proxy is not running. Falling back to the
+                // direct URL would put the session token in the backend's config, so
+                // the server is simply omitted instead — fewer tools is recoverable,
+                // a leaked token is not.
+                url: proxied
+            };
+            if (!proxied) {
+                delete mcpServers[server.name];
+                this.logger.warn(`[SessionRunner] MCP server "${server.name}" omitted: proxy not running`);
+            }
+        }
+        const abort = new AbortController();
+        signal.addEventListener('abort', () => abort.abort(), { once: true });
+        const brokerPort = this.deps.secrets.getBrokerPort();
+        return {
+            agentId: session.agent.agentId,
+            // The adapters were written against 20x's task model and call this
+            // `taskId`. It is the SESSION id here. Renaming the field in the adapters
+            // would have made them no longer "extracted unchanged", which is worth
+            // more than the tidier name.
+            taskId: session.sessionId,
+            workspaceDir,
+            model: qualifiedModelId(session.agent.model),
+            systemPrompt: session.agent.systemPrompt ?? undefined,
+            skills: session.agent.skills.map((skill) => ({
+                name: skill.name,
+                content: skill.content
+            })),
+            promptAbort: abort,
+            mcpServers: mcpServers,
+            secretBrokerPort: brokerPort ?? undefined,
+            secretSessionToken: secretToken ?? undefined,
+            secretShellPath: this.deps.secrets.writeShellWrapper() ?? undefined,
+            environment: this.deps.workspace.getEnvironment?.(session.sessionId, [
+                session.agent.model.gatewayUrl ?? '',
+                ...session.agent.mcpServers.map((server) => server.url)
+            ]),
+            /*
+             * DEFECT G1, THE OTHER HALF.
+             *
+             * `session.agent.permissionMode` has been on the lease since the contract
+             * was frozen, and until now it DIED HERE: this object was built without
+             * the field, so every session fell to the adapter default no matter what
+             * the user had chosen. The picker in the agent editor was decorative, and
+             * the UI said so in a caveat.
+             *
+             * The lease's vocabulary is four-valued and the adapter's is two-valued,
+             * so the translation is deliberate rather than incidental — the whole
+             * table, and what it costs on each backend, is written down in
+             * ./permission-mode.ts. `sandboxMode` is set from the same call because
+             * it is what carries the part of the intent 'ask' | 'allow' cannot.
+             */
+            ...(0, permission_mode_1.mapPermissionMode)(session.agent.permissionMode)
+        };
+    }
+}
+exports.SessionRunner = SessionRunner;