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

package/dist/harness.js

@@ -0,0 +1,1414 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Harness = exports.UpgradeRequestedError = exports.VersionRefusedError = void 0;
+const node_path_1 = require("node:path");
+const model_gateway_1 = require("./adapters/model-gateway");
+const capabilities_1 = require("./capabilities");
+const contract_1 = require("./contract");
+const control_plane_1 = require("./control-plane");
+const credential_store_1 = require("./credential-store");
+const github_command_guards_1 = require("./github-command-guards");
+const github_workspace_1 = require("./github-workspace");
+const health_1 = require("./health");
+const model_probe_1 = require("./model-probe");
+const ports_default_1 = require("./ports-default");
+const lease_renewal_1 = require("./runtime/lease-renewal");
+const mcp_auth_proxy_1 = require("./runtime/mcp-auth-proxy");
+const session_runner_1 = require("./runtime/session-runner");
+const conversation_store_1 = require("./store/conversation-store");
+const sqlite_store_1 = require("./store/sqlite-store");
+const version_1 = require("./version");
+/** Backoff after a lease poll fails, so an unreachable control plane is not hammered. */
+const LEASE_ERROR_BACKOFF_MS = 5_000;
+/**
+ * How often the model catalogue is re-probed once the harness is running.
+ *
+ * A long interval, deliberately: Pi model discovery starts a short-lived RPC
+ * process. Every six hours is a bounded refresh of a slowly changing catalog.
+ */
+const MODEL_PROBE_REFRESH_MS = 6 * 60 * 60 * 1000;
+/**
+ * The control plane refused this harness's PROTOCOL or VERSION. FINAL.
+ *
+ * A distinct class rather than a message match, so a caller cannot break the
+ * gate by rewording an error string. The process must EXIT — not merely throw —
+ * because the health socket keeps the Node event loop alive for ever, and a
+ * harness that only threw would hang while the gate quietly never took effect.
+ * Phase 0 shipped exactly that bug.
+ */
+class VersionRefusedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'VersionRefusedError';
+    }
+}
+exports.VersionRefusedError = VersionRefusedError;
+/** The sandbox supervisor, not the harness, owns package installation. */
+class UpgradeRequestedError extends Error {
+    harnessVersion;
+    constructor(harnessVersion) {
+        super(`Harness upgrade requested: ${harnessVersion}`);
+        this.harnessVersion = harnessVersion;
+        this.name = 'UpgradeRequestedError';
+    }
+}
+exports.UpgradeRequestedError = UpgradeRequestedError;
+function log(message, extra) {
+    process.stdout.write(`${JSON.stringify({
+        ts: new Date().toISOString(),
+        component: 'pf-agent-harness',
+        message,
+        ...extra
+    })}\n`);
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * THE HARNESS.
+ *
+ * ONE PROGRAM, THREE HOSTING MODES. A Daytona sandbox, a customer VM and the
+ * 20x desktop run this identical loop; nothing below asks which it is. Where a
+ * host genuinely differs it supplies a PORT, and the ports are capabilities
+ * ("can you notify a human?"), never identities ("are you the desktop?").
+ *
+ * THE LOOP, and why it has this shape:
+ *
+ *   register  ->  heartbeat (30s, forever)  +  lease (25s poll, forever)
+ *
+ * Both are OUTBOUND. Nothing dials in, there is no listening port reachable
+ * from the network, and that single property is what lets a customer VM behind
+ * NAT work with no tunnel and no firewall change. It is also why an abort or a
+ * user's answer to a question rides back on `sessionCommands` in the HEARTBEAT
+ * response rather than arriving on a socket.
+ *
+ * Long-poll rather than a WebSocket because Cloud Run bills a request slot for
+ * the WHOLE life of a connection and caps it at 3600s. One persistent socket per
+ * runner would be one billed slot per runner, permanently.
+ */
+class Harness {
+    options;
+    deps;
+    client;
+    health;
+    proxy;
+    store;
+    /** The model-facing conversation log. See `ports.ts#ConversationStore`. */
+    conversation;
+    /** False when the log is in memory only, so a restart forgets. Reported. */
+    conversationDurable;
+    storeDurable;
+    storeReason;
+    workspace;
+    secrets;
+    events;
+    telemetry;
+    notifier;
+    artifacts;
+    tokens = new ports_default_1.SessionTokenInjector(null);
+    startedAt = Date.now();
+    status = 'starting';
+    tenantId = null;
+    runnerId = null;
+    capabilities = null;
+    /**
+     * The cached model catalogue, probed at start-up and on a LONG interval.
+     *
+     * Probed ONCE, not per heartbeat: Pi discovery starts a short-lived RPC
+     * process, and doing that every 30 seconds would be a regression. The cache
+     * is the flat `models` + per-backend list
+     * that every capability report after start reuses.
+     */
+    modelCatalog = null;
+    /** Epoch ms of the last successful (or attempted) model probe. */
+    modelProbeAt = 0;
+    /**
+     * Empty gateway for the model probe. The probe builds a FRESH adapter and
+     * must not read a live turn's credential; a null config is "no gateway",
+     * which makes the probe list the host's own local models — and the control
+     * plane separately supplies the gateway list.
+     */
+    modelProbeGateway = new model_gateway_1.SessionModelGateway();
+    heartbeatIntervalMs;
+    leaseWaitSeconds = contract_1.DEFAULT_LEASE_WAIT_SECONDS;
+    heartbeatTimer = null;
+    /** Fires when the runner credential should be rotated. Durable runtimes re-persist the new one. */
+    rotateTimer = null;
+    credentialStore;
+    /** True when this run reused a persisted credential rather than enrolling. */
+    reusedStoredCredential = false;
+    lastHeartbeatAt = null;
+    lastHeartbeatError = null;
+    consecutiveHeartbeatFailures = 0;
+    stopping = false;
+    /** Releases this Harness's reference to the process-wide generic wrappers. */
+    releaseGitHubGuard = null;
+    /** sessionId -> the controller that aborts its turn. */
+    active = new Map();
+    /** Renewal workers that must receive a credential rotation in flight. */
+    activeRenewals = new Set();
+    /** commandIds already applied. `SessionCommand` is idempotent by contract. */
+    appliedCommands = new Set();
+    /** Session-end cleanup waits for an active turn to save its dirty work. */
+    pendingWorkspaceReleases = new Set();
+    /**
+     * sessionId -> the runner executing its turn.
+     *
+     * `active` above holds only an AbortController, which is all an `abort`
+     * command needs. An `answer` needs the RUNNER: the adapter and the backend
+     * session id live inside the turn, and the answer has to reach them from the
+     * command handler's stack. This map is what makes wire 3 possible.
+     */
+    runners = new Map();
+    leaseLoop = null;
+    /** Set when the control plane refuses this build. Ends the process. */
+    fatal = null;
+    /** A changed pin waits here until every live lease has completed. */
+    pendingHarnessVersion = null;
+    /** Same idea, for the INDEPENDENT sandbox-tools pin (gh, node deps, ...). */
+    pendingSandboxToolsVersion = null;
+    constructor(options, deps = {}) {
+        this.options = options;
+        this.deps = deps;
+        this.client =
+            deps.clientFactory?.(options.controlPlaneUrl) ??
+                new control_plane_1.ControlPlaneClient(options.controlPlaneUrl);
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs;
+        this.health = new health_1.HealthServer(options.healthPort, () => this.snapshot());
+        const opened = deps.store !== undefined
+            ? { store: deps.store, durable: true, reason: undefined }
+            : (0, sqlite_store_1.openTranscriptStore)((0, node_path_1.join)(options.workspaceRoot, 'harness.sqlite'));
+        this.store = opened.store;
+        this.storeDurable = opened.durable;
+        this.storeReason = opened.reason;
+        /*
+         * WHERE THE CONVERSATION LIVES BETWEEN TURNS.
+         *
+         * Kept in its OWN sqlite file rather than beside the transcript, because
+         * the two answer to different owners: `harness.sqlite` is a cache of a UI
+         * projection and may be dropped whenever it is convenient, while this is
+         * the model's memory and dropping it is a user-visible regression. A
+         * separate file makes "clear the transcript cache" a safe operation.
+         */
+        const conversation = deps.conversation !== undefined
+            ? { store: deps.conversation, durable: true, reason: undefined }
+            : (0, conversation_store_1.openConversationStore)((0, node_path_1.join)(options.workspaceRoot, 'conversation.sqlite'));
+        this.conversation = conversation.store;
+        this.conversationDurable = conversation.durable;
+        this.workspace =
+            deps.workspace ??
+                new github_workspace_1.GitHubWorkspaceProvider({
+                    root: options.workspaceRoot,
+                    port: options.githubProxyPort,
+                    directUrls: [options.controlPlaneUrl]
+                });
+        this.secrets = deps.secrets ?? new ports_default_1.NoSecretProvider();
+        this.events = deps.events ?? new ports_default_1.NullEventSink();
+        this.telemetry = deps.telemetry ?? new ports_default_1.NoopTelemetry();
+        this.notifier = deps.notifier ?? new ports_default_1.ServerNotifier();
+        this.artifacts = deps.artifacts ?? new ports_default_1.NoArtifactInspector();
+        this.credentialStore =
+            deps.credentialStore ??
+                (0, credential_store_1.createCredentialStore)(options.runtime, options.workspaceRoot);
+        this.proxy = new mcp_auth_proxy_1.McpAuthProxy({
+            tokens: this.tokens,
+            notifier: this.notifier
+        });
+    }
+    /** The actual bound health port. Used by tests to prove the socket closed. */
+    getHealthPort() {
+        return this.health.boundPort;
+    }
+    snapshot() {
+        return {
+            // 'busy' is deliberately NOT reported here. A probe asks "may this host be
+            // used at all", and a host mid-turn is still perfectly healthy.
+            status: this.status === 'busy' ? 'ready' : this.status,
+            harnessVersion: (0, version_1.getHarnessVersion)(),
+            nodeVersion: process.version,
+            piVersion: (0, version_1.getPiVersion)(),
+            registered: this.client.isRegistered(),
+            tenantId: this.tenantId,
+            // Phase 0 called it sandboxId. The canonical name is runnerId; the old
+            // field is still populated so an existing probe does not break on the
+            // upgrade, and it goes when nothing reads it.
+            sandboxId: this.runnerId,
+            runnerId: this.runnerId,
+            protocolVersion: undefined,
+            // A harness that cannot durably hold the conversation is degraded, not
+            // merely slower: on a restart it forgets every session it was mid-way
+            // through, and the user sees an agent that lost the thread. The control
+            // plane still holds the record, so it is recoverable — which is exactly
+            // why it must be VISIBLE rather than silent.
+            degraded: this.options.degraded ||
+                !this.storeDurable ||
+                !this.conversationDurable,
+            degradedReason: this.options.degradedReason ??
+                (this.storeDurable ? undefined : this.storeReason) ??
+                (this.conversationDurable
+                    ? undefined
+                    : 'conversation log is in memory only; a restart will forget history'),
+            uptimeMs: Date.now() - this.startedAt,
+            activeSessions: this.active.size,
+            lastHeartbeatAt: this.lastHeartbeatAt,
+            lastHeartbeatError: this.lastHeartbeatError
+        };
+    }
+    /* ------------------------------------------------------------------ */
+    /* Lifecycle                                                           */
+    /* ------------------------------------------------------------------ */
+    async start() {
+        // The health check comes up FIRST, so a probe sees 'starting' rather than a
+        // connection refused while registration is still retrying.
+        await this.health.start();
+        await this.proxy.start();
+        this.capabilities = await (0, capabilities_1.probeCapabilities)({
+            maxConcurrentSessions: this.options.maxConcurrentSessions,
+            labels: this.options.labels
+        });
+        // Install immediately before model probing can start a backend. The lease
+        // is process-wide and reference-counted, so concurrent Harness instances
+        // share one generic launcher instead of racing to rewrite global PATH.
+        if (this.options.runtime === 'sandbox') {
+            const guard = await (0, github_command_guards_1.acquireGhGuardPath)(this.options.workspaceRoot);
+            this.releaseGitHubGuard = guard.release;
+        }
+        /*
+         * MODELS ARE PROBED ONCE, AT START-UP — not on every heartbeat, because
+         * enumerating providers starts a Pi discovery process. The catalogue is
+         * attached to every capability report after this; a re-probe happens only
+         * on a long interval or when a backend newly appears.
+         */
+        await this.refreshModelCatalog(true);
+        this.applyModelCatalog(this.capabilities);
+        log('Harness starting', {
+            harnessVersion: (0, version_1.getHarnessVersion)(),
+            healthPort: this.options.healthPort,
+            backends: this.capabilities.backends.map((b) => b.name),
+            git: this.capabilities.git,
+            docker: this.capabilities.docker,
+            durableStore: this.storeDurable,
+            durableConversation: this.conversationDurable,
+            degraded: this.options.degraded
+        });
+        if (!this.storeDurable) {
+            // Visible, not silent. A fallback nobody can see is how an outage becomes
+            // a mystery three weeks later.
+            log('Durable store unavailable, running in memory', {
+                reason: this.storeReason
+            });
+        }
+        try {
+            await this.register();
+        }
+        catch (error) {
+            // The health server and the proxy are already listening, and a listening
+            // server keeps the Node event loop alive for ever. Without this the
+            // process would HANG on a refused registration instead of exiting, and
+            // the version gate would never recycle the host.
+            await this.stop();
+            throw error;
+        }
+        this.status = 'ready';
+        log('Harness ready', { tenantId: this.tenantId, runnerId: this.runnerId });
+        this.scheduleHeartbeat();
+        this.leaseLoop = this.runLeaseLoop();
+    }
+    /**
+     * Block until the harness stops for a reason worth reporting.
+     *
+     * Resolves on a clean drain; rejects when the control plane refused this
+     * build, so the CLI can exit non-zero and the host is recycled onto a
+     * supported version.
+     */
+    async wait() {
+        await this.leaseLoop;
+        if (this.fatal) {
+            throw this.fatal;
+        }
+    }
+    async stop(options = {}) {
+        if (this.stopping) {
+            return;
+        }
+        this.stopping = true;
+        this.status = 'draining';
+        if (this.heartbeatTimer) {
+            clearTimeout(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.rotateTimer) {
+            clearTimeout(this.rotateTimer);
+            this.rotateTimer = null;
+        }
+        // Abort in-flight turns BEFORE deregistering, so the control plane's
+        // requeue count is accurate rather than racing the turns it is counting.
+        const hadActive = this.active.size > 0;
+        for (const controller of this.active.values()) {
+            controller.abort();
+        }
+        /*
+         * A DURABLE RUNNER DOES NOT DEREGISTER.
+         *
+         * Deregistration REVOKES the credential server-side (handlers/runners.ts —
+         * it nulls credentialHash). For a sandbox that is correct: it is ephemeral,
+         * its credential is memory-only, and a fresh one always exists. But a
+         * self-hosted or desktop runner PERSISTS its credential precisely so it can
+         * restart on it — and a clean SIGTERM (a systemd restart, a host reboot)
+         * would otherwise revoke the very credential we saved, re-bricking the host
+         * we just un-bricked. Skipping deregister keeps that credential valid; the
+         * in-flight leases are still recovered, by the same heartbeat-liveness path
+         * a crash relies on (three missed beats, then the watchdog requeues).
+         *
+         * `sandbox` still says goodbye, so its leases requeue immediately.
+         */
+        const durable = this.options.runtime !== 'sandbox';
+        if (this.client.isRegistered() &&
+            !durable &&
+            !options.preserveRegistration) {
+            try {
+                await this.client.deregister('shutdown', hadActive);
+            }
+            catch (error) {
+                // A goodbye that cannot be delivered must never block a shutdown.
+                // Liveness is the heartbeat: three missed beats and the watchdog
+                // requeues everything this runner held.
+                log('Deregister failed, continuing shutdown', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+        else if (durable && this.client.isRegistered()) {
+            log('Durable runner: skipping deregister to preserve the credential', {
+                runtime: this.options.runtime,
+                hadActiveSessions: hadActive
+            });
+        }
+        await this.proxy.stop();
+        await this.workspace.stop?.();
+        await this.health.stop();
+        this.releaseGitHubGuard?.();
+        this.releaseGitHubGuard = null;
+        this.tokens.revoke();
+        if (!options.preserveRegistration) {
+            this.client.forgetCredential();
+        }
+        log('Harness stopped');
+    }
+    /* ------------------------------------------------------------------ */
+    /* Registration                                                        */
+    /* ------------------------------------------------------------------ */
+    async register() {
+        const capabilities = this.capabilities ?? (await (0, capabilities_1.probeCapabilities)());
+        // 1. REUSE A PERSISTED CREDENTIAL when there is a valid one.
+        //
+        // This is the whole fix for "a crashed harness can never rejoin": a
+        // self-hosted or desktop runner that was SIGKILLed, OOM-ed or rebooted comes
+        // back on its stored, still-valid credential — no fresh single-use enrolment
+        // token required. `sandbox` uses a no-op store, so it always falls through
+        // to enrolment, where a fresh token always exists.
+        if (await this.tryStoredCredential(capabilities)) {
+            this.reusedStoredCredential = true;
+            return;
+        }
+        // 2. ENROL. The ordinary first-boot path, and the fallback when no usable
+        //    stored credential exists (absent, expired or rejected).
+        if (!this.options.enrolmentToken) {
+            throw new Error('No usable stored runner credential and no enrolment token. Provide ' +
+                '--token / PF_ENROLMENT_TOKEN for the first registration.');
+        }
+        // Back-off and the final-status short-circuit both live in the client, so
+        // every route obeys the same retry rule and no route can drift from it.
+        const response = await this.client.register({
+            enrolmentToken: this.options.enrolmentToken,
+            capabilities,
+            runtime: this.options.runtime,
+            degraded: this.options.degraded,
+            degradedReason: this.options.degradedReason
+        });
+        // FAIL CLOSED. `isRegistered()` is the real invariant, not `accepted`:
+        // a 200 that simply omits the field must not be read as consent.
+        if (response.accepted === false || !this.client.isRegistered()) {
+            // "refused harness version" is asserted verbatim by the sandbox e2e
+            // against the REAL image. Rewording it turns a passing check into one
+            // that can never fail, which is the whole reason the final-status list
+            // is matched on the STATUS and never on a message.
+            throw new VersionRefusedError(`Control plane refused harness version ${(0, version_1.getHarnessVersion)()}: ${response.reason ?? 'no runner credential in the response'}${response.minProtocolVersion
+                ? ` (min protocol ${response.minProtocolVersion})`
+                : ''}`);
+        }
+        this.tenantId = response.tenantId ?? null;
+        this.runnerId = this.client.getRunnerId();
+        if (response.heartbeatIntervalMs) {
+            this.heartbeatIntervalMs = response.heartbeatIntervalMs;
+        }
+        if (response.leaseWaitSeconds) {
+            this.leaseWaitSeconds = response.leaseWaitSeconds;
+        }
+        // PERSIST FOR DURABLE RUNTIMES, so the next boot after a crash reuses this
+        // credential instead of re-enrolling with a token that has already burned.
+        this.persistCredential(response);
+        this.scheduleRotation(response.rotateAfter, response.credentialExpiresAt);
+        // This exact phrase is asserted by the sandbox e2e suite against the REAL
+        // image. Rewording it silently turns a passing check into one that can
+        // never fail, so it is kept verbatim from Phase 0.
+        log('Registered with control plane', {
+            tenantId: this.tenantId,
+            runnerId: this.runnerId,
+            heartbeatIntervalMs: this.heartbeatIntervalMs,
+            leaseWaitSeconds: this.leaseWaitSeconds
+        });
+    }
+    /**
+     * Try to authenticate with a persisted credential. Returns true on success.
+     *
+     * The stored credential is VALIDATED by an actual authenticated call — a
+     * heartbeat, the lightest one — before the harness commits to it. That is what
+     * makes the fallback safe: a stored credential that the control plane has
+     * revoked (a `401`/`403`) is dropped here and enrolment is retried, so a stale
+     * credential cannot wedge the runner. A TRANSIENT failure is NOT treated as a
+     * rejection — re-enrolling on a network blip would burn an already-spent token
+     * — so the harness keeps the credential and lets the normal loop retry.
+     */
+    async tryStoredCredential(capabilities) {
+        const stored = this.credentialStore.load();
+        if (!stored) {
+            return false;
+        }
+        if (stored.credentialExpiresAt &&
+            Date.parse(stored.credentialExpiresAt) <= Date.now()) {
+            log('Stored runner credential has expired; re-enrolling', {
+                runnerId: stored.runnerId,
+                credentialExpiresAt: stored.credentialExpiresAt
+            });
+            this.credentialStore.clear();
+            return false;
+        }
+        this.client.useStoredCredential(stored.runnerId, stored.credential);
+        try {
+            const response = await this.client.heartbeat({
+                status: this.status,
+                uptimeMs: Date.now() - this.startedAt,
+                activeSessions: 0,
+                activeSessionIds: [],
+                degraded: this.options.degraded || !this.storeDurable,
+                capabilities
+            });
+            this.tenantId = stored.tenantId;
+            this.runnerId = stored.runnerId;
+            if (response.heartbeatIntervalMs) {
+                this.heartbeatIntervalMs = response.heartbeatIntervalMs;
+            }
+            this.observeHarnessPin(response.harnessVersion);
+            this.observeSandboxToolsPin(response.sandboxToolsVersion);
+            for (const command of response.sessionCommands ?? []) {
+                this.applyCommand(command);
+            }
+            log('Reused stored runner credential', {
+                runnerId: stored.runnerId,
+                tenantId: stored.tenantId
+            });
+            return true;
+        }
+        catch (error) {
+            const rejected = error instanceof control_plane_1.ControlPlaneError &&
+                (error.status === 401 || error.status === 403);
+            if (rejected) {
+                log('Stored runner credential was rejected; re-enrolling', {
+                    runnerId: stored.runnerId,
+                    status: error.status,
+                    code: error.code
+                });
+                this.credentialStore.clear();
+                this.client.forgetCredential();
+                return false;
+            }
+            // Transient (a network blip, a 5xx, or the 426 running-fleet gate, which
+            // the lease loop turns fatal). Keep the credential and proceed — the
+            // heartbeat and lease loops retry, and re-enrolling here would throw away
+            // a good credential over a momentary outage.
+            this.tenantId = stored.tenantId;
+            this.runnerId = stored.runnerId;
+            log('Could not validate stored credential (transient); proceeding', {
+                runnerId: stored.runnerId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return true;
+        }
+    }
+    /**
+     * Persist the runner credential for durable runtimes.
+     *
+     * A no-op for `sandbox` (its store discards everything) and for a response
+     * that carried no credential. This is what a crash on the NEXT run reuses.
+     */
+    persistCredential(response) {
+        if (!response.runnerCredential || !this.runnerId) {
+            return;
+        }
+        this.credentialStore.save({
+            runnerId: this.runnerId,
+            tenantId: this.tenantId,
+            credential: response.runnerCredential,
+            credentialExpiresAt: response.credentialExpiresAt ?? null,
+            savedAt: new Date().toISOString()
+        });
+    }
+    /* ------------------------------------------------------------------ */
+    /* Credential rotation                                                 */
+    /* ------------------------------------------------------------------ */
+    /**
+     * Schedule a rotation at `rotateAfter`, comfortably before the credential
+     * expires. The control plane owns the cadence; if it names neither a
+     * `rotateAfter` nor an expiry, no rotation is scheduled and the credential
+     * simply lives out its TTL.
+     */
+    scheduleRotation(rotateAfterIso, credentialExpiresAtIso) {
+        if (this.stopping) {
+            return;
+        }
+        const now = Date.now();
+        let delay = null;
+        if (rotateAfterIso) {
+            delay = Math.max(0, Date.parse(rotateAfterIso) - now);
+        }
+        else if (credentialExpiresAtIso) {
+            // Halfway to expiry, so a failed rotation still has a whole grace period
+            // to retry in.
+            delay = Math.max(0, (Date.parse(credentialExpiresAtIso) - now) / 2);
+        }
+        if (delay === null || Number.isNaN(delay)) {
+            return;
+        }
+        if (this.rotateTimer) {
+            clearTimeout(this.rotateTimer);
+        }
+        this.rotateTimer = setTimeout(() => {
+            void this.rotateCredential();
+        }, delay);
+        this.rotateTimer.unref();
+    }
+    /**
+     * Rotate the runner credential and re-persist it.
+     *
+     * A credential cannot authenticate its own replacement once expired, so
+     * rotation is scheduled AHEAD of expiry and never used to climb out of a 401.
+     * A failed rotation keeps the current credential and retries later; a final
+     * status stops trying, because the credential is gone for good and the loop
+     * will surface that.
+     */
+    async rotateCredential() {
+        if (this.stopping) {
+            return;
+        }
+        try {
+            const response = await this.client.rotateCredential((0, version_1.getHarnessVersion)());
+            if (this.runnerId && response.runnerCredential) {
+                this.credentialStore.save({
+                    runnerId: this.runnerId,
+                    tenantId: this.tenantId,
+                    credential: response.runnerCredential,
+                    credentialExpiresAt: response.credentialExpiresAt ?? null,
+                    savedAt: new Date().toISOString()
+                });
+                for (const renewal of this.activeRenewals) {
+                    renewal.setCredential?.(response.runnerCredential);
+                }
+            }
+            log('Rotated runner credential', { rotateAfter: response.rotateAfter });
+            this.scheduleRotation(response.rotateAfter, response.credentialExpiresAt);
+        }
+        catch (error) {
+            log('Credential rotation failed', {
+                error: error instanceof Error ? error.message : String(error)
+            });
+            if (!(error instanceof control_plane_1.ControlPlaneError && error.final) &&
+                !this.stopping) {
+                this.rotateTimer = setTimeout(() => {
+                    void this.rotateCredential();
+                }, 30_000);
+                this.rotateTimer.unref();
+            }
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /* Heartbeat                                                           */
+    /* ------------------------------------------------------------------ */
+    /**
+     * Re-probe the model catalogue.
+     *
+     * Runs ONCE at start-up and on a long interval after that — never per
+     * heartbeat, because the probe starts a Pi discovery process.
+     * `force` re-probes regardless of age (used at start-up). Never rejects.
+     */
+    async refreshModelCatalog(force = false) {
+        const backends = this.capabilities?.backends ?? [];
+        const build = this.deps.getAdapter;
+        if (!build || backends.length === 0) {
+            this.modelCatalog = null;
+            this.modelProbeAt = Date.now();
+            return;
+        }
+        if (!force &&
+            this.modelCatalog &&
+            Date.now() - this.modelProbeAt < MODEL_PROBE_REFRESH_MS) {
+            return;
+        }
+        const factory = (backend) => {
+            try {
+                return build(backend, { modelGateway: this.modelProbeGateway }) ?? null;
+            }
+            catch {
+                // A backend the host cannot wire (nothing installed, adapter throws) is
+                // "no models here", never an error on the probe path.
+                return null;
+            }
+        };
+        this.modelProbeAt = Date.now();
+        try {
+            const catalog = await (0, model_probe_1.probeModelCatalog)(backends, factory);
+            this.modelCatalog = catalog;
+            log('Model catalogue probed', {
+                backends: catalog.attempted,
+                models: catalog.flat.length
+            });
+        }
+        catch {
+            // probeModelCatalog NEVER rejects by construction; this is a belt-and-
+            // braces guard so a regression cannot take down the start-up/register
+            // path. Without a catalog the capabilities simply carry no models.
+            this.modelCatalog = null;
+        }
+    }
+    /**
+     * Attach the cached model catalogue to a capability report.
+     *
+     * Mutates `capabilities` in place: the flat list on `models`, and each
+     * installed backend's own list on `backends[].models`. Absent (rather than
+     * an empty-but-meaningful list) when the catalogue is empty.
+     */
+    applyModelCatalog(capabilities) {
+        const catalog = this.modelCatalog;
+        if (!catalog) {
+            capabilities.models = undefined;
+            for (const backend of capabilities.backends) {
+                delete backend.models;
+            }
+            return;
+        }
+        capabilities.models = catalog.flat.length > 0 ? catalog.flat : undefined;
+        for (const backend of capabilities.backends) {
+            const models = catalog.byBackend[backend.name];
+            if (models && models.length > 0) {
+                backend.models = models;
+            }
+            else {
+                delete backend.models;
+            }
+        }
+    }
+    /**
+     * Whether the model catalogue needs a (rare) re-probe.
+     *
+     * Interval-only, and the interval doubles as a cooldown: `refreshModelCatalog`
+     * stamps `modelProbeAt` even when the probe itself fails, so a host whose
+     * models cannot be enumerated does not keep starting a process on every
+     * heartbeat trying. Start-up force bypasses this.
+     *
+     * NEVER WHILE A TURN IS RUNNING. Pi discovery and a live turn share the Pi
+     * agent directory, including models.json; avoiding concurrent discovery
+     * keeps provider configuration changes out of an active model call.
+     * Deferring costs nothing: the catalogue only
+     * changes when the host's model config does, and the next idle heartbeat
+     * picks it up.
+     */
+    modelsNeedRefresh() {
+        if (this.active.size > 0) {
+            return false;
+        }
+        return Date.now() - this.modelProbeAt >= MODEL_PROBE_REFRESH_MS;
+    }
+    scheduleHeartbeat() {
+        if (this.stopping) {
+            return;
+        }
+        this.heartbeatTimer = setTimeout(() => {
+            void this.sendHeartbeat();
+        }, this.heartbeatIntervalMs);
+        // Never hold the event loop open on the heartbeat alone.
+        this.heartbeatTimer.unref();
+    }
+    async sendHeartbeat() {
+        try {
+            // Capabilities are RE-PROBED, not cached from registration. A host is
+            // upgraded in place: docker can appear and a backend can be installed
+            // without the runner ever restarting, and the control plane routes work
+            // on this answer.
+            const capabilities = await (0, capabilities_1.probeCapabilities)({
+                maxConcurrentSessions: this.options.maxConcurrentSessions,
+                labels: this.options.labels
+            });
+            this.applyModelCatalog(capabilities);
+            this.capabilities = capabilities;
+            /*
+             * THE MODEL CATALOGUE IS NOT RE-PROBED HERE, EVER. Only the CLI probes
+             * run on a heartbeat; Pi discovery starts an RPC process, and doing that
+             * every heartbeat would be a regression. The
+             * cached catalogue (probed at start-up) is attached above; a refresh is
+             * kicked off only when the long interval has elapsed or a backend newly
+             * appeared, and its result lands on a LATER heartbeat.
+             */
+            if (this.modelsNeedRefresh()) {
+                void this.refreshModelCatalog();
+            }
+            const response = await this.client.heartbeat({
+                status: this.status,
+                uptimeMs: Date.now() - this.startedAt,
+                activeSessions: this.active.size,
+                activeSessionIds: Array.from(this.active.keys()),
+                degraded: this.options.degraded || !this.storeDurable,
+                capabilities
+            });
+            this.lastHeartbeatAt = new Date().toISOString();
+            this.lastHeartbeatError = null;
+            this.consecutiveHeartbeatFailures = 0;
+            if (response.heartbeatIntervalMs) {
+                this.heartbeatIntervalMs = response.heartbeatIntervalMs;
+            }
+            this.observeHarnessPin(response.harnessVersion);
+            this.observeSandboxToolsPin(response.sandboxToolsVersion);
+            for (const command of response.sessionCommands ?? []) {
+                this.applyCommand(command);
+            }
+            if (response.action === 'drain') {
+                this.status = 'draining';
+                log('Control plane asked the harness to drain');
+            }
+            else if (response.action === 'restart') {
+                log('Control plane asked the harness to restart');
+                await this.stop();
+                return;
+            }
+        }
+        catch (error) {
+            // A 426 here is the RUNNING-FLEET version gate: the floor was raised
+            // under a runner that had already registered. It is FINAL, and retrying
+            // would hammer a control plane that will never serve this build again.
+            if (error instanceof control_plane_1.ProtocolRefusedError) {
+                this.fatal = new VersionRefusedError(`Control plane raised its protocol floor: ${error.message}`);
+                await this.stop();
+                return;
+            }
+            this.consecutiveHeartbeatFailures += 1;
+            this.lastHeartbeatError =
+                error instanceof Error ? error.message : String(error);
+            log('Heartbeat failed', {
+                error: this.lastHeartbeatError,
+                consecutive: this.consecutiveHeartbeatFailures
+            });
+            // After the control plane has already written this runner off, keep
+            // beating but stop taking work: finishing a turn whose lease was requeued
+            // onto another runner would interleave two writers into one transcript.
+            if (this.consecutiveHeartbeatFailures >= contract_1.MISSED_HEARTBEATS_BEFORE_OFFLINE &&
+                this.status === 'ready') {
+                this.status = 'draining';
+                log('Presumed offline by the control plane, draining');
+            }
+        }
+        this.scheduleHeartbeat();
+    }
+    /**
+     * Apply a command that rode back on a heartbeat.
+     *
+     * Idempotent by `commandId`, because the contract lets the control plane
+     * repeat a command until it observes the effect — it has no other way to
+     * know, since it cannot dial in and ask.
+     */
+    applyCommand(command) {
+        if (this.appliedCommands.has(command.commandId)) {
+            return;
+        }
+        this.appliedCommands.add(command.commandId);
+        if (command.command === 'abort') {
+            const controller = this.active.get(command.sessionId);
+            if (controller) {
+                log('Aborting session by control-plane command', {
+                    sessionId: command.sessionId
+                });
+                controller.abort();
+            }
+            return;
+        }
+        if (command.command === 'release-workspace') {
+            const controller = this.active.get(command.sessionId);
+            if (controller) {
+                this.pendingWorkspaceReleases.add(command.sessionId);
+                controller.abort();
+                log('Workspace release deferred until the active turn ends', {
+                    sessionId: command.sessionId
+                });
+            }
+            else {
+                void this.releaseSessionWorkspace(command.sessionId);
+            }
+            return;
+        }
+        if (command.command === 'answer') {
+            /*
+             * WIRE 3 — THE ACTUAL BLOCKER OF DEFECT G1, NOW JOINED UP.
+             *
+             * This used to be a comment saying the command was "recorded as applied
+             * rather than retried for ever". Everything either side of it worked: the
+             * UI posts an answer, the control plane queues it as a session command,
+             * the heartbeat carries it back, and the adapter has had
+             * `respondToApproval` all along. The command arrived here and was
+             * DROPPED.
+             *
+             * That is why the permission mode could not simply be turned on. With
+             * this line missing, passing the real mode through would have converted
+             * "silently unrestricted" into "silently hangs on every turn" — and since
+             * the default agent stores `permissionMode: 'default'`, it would have
+             * done so to every session at once.
+             *
+             * FIRE AND FORGET, DELIBERATELY. `applyCommand` is called from the
+             * heartbeat and renew paths, and neither may be blocked on a backend HTTP
+             * call: a slow backend would otherwise stall the beat that proves this
+             * runner is alive, and three missed beats is the definition of offline.
+             */
+            const runner = this.runners.get(command.sessionId);
+            if (!runner) {
+                /*
+                 * FORGET IT RATHER THAN MARKING IT APPLIED.
+                 *
+                 * This path is reached when the turn ended between the command being
+                 * queued and it arriving — `runLeasedTurn`'s `finally` has already
+                 * removed the runner. Leaving the commandId in `appliedCommands` would
+                 * mark the user's answer as handled when nothing handled it, which is
+                 * the very "recorded as applied, retried never" defect this work set
+                 * out to fix, surviving on one entry path.
+                 *
+                 * There is no runner to write a transcript part through, so the log is
+                 * all that can be said here; what this buys is that a redelivery would
+                 * be attempted rather than discarded as a duplicate.
+                 */
+                this.appliedCommands.delete(command.commandId);
+                log('Answer arrived for a session this runner is no longer running', {
+                    sessionId: command.sessionId,
+                    commandId: command.commandId
+                });
+                return;
+            }
+            void runner
+                .answerPendingApproval({
+                sessionId: command.sessionId,
+                partId: command.partId,
+                answer: command.answer,
+                optionId: command.optionId
+            })
+                .then((outcome) => {
+                log('Applied answer command', {
+                    sessionId: command.sessionId,
+                    commandId: command.commandId,
+                    outcome
+                });
+                /*
+                 * 'failed' IS THE ONLY OUTCOME THAT NEEDS RECOVERY, AND IT ARRIVES
+                 * HERE RATHER THAN IN `.catch()`.
+                 *
+                 * `answerPendingApproval` RESOLVES with 'failed' when the backend
+                 * could not be told — it does not reject. An earlier version of this
+                 * handler put the recovery in `.catch()` only, and because the runner
+                 * swallowed that error and returned a plain `false`, the recovery was
+                 * UNREACHABLE: the commandId stayed applied, no error part was
+                 * written, and the user's click vanished silently. Exactly the
+                 * failure the comment below describes, in the code meant to prevent
+                 * it.
+                 *
+                 * 'ignored' is NOT a failure — a stale or duplicate answer is an
+                 * ordinary outcome and must not tell the user anything went wrong.
+                 */
+                if (outcome === 'failed') {
+                    this.recoverFailedAnswer(runner, command, 'the backend did not accept the answer');
+                }
+            })
+                .catch((error) => {
+                /*
+                 * A FAILED ANSWER MUST NOT BE SILENTLY FORGOTTEN.
+                 *
+                 * `appliedCommands.add` ran before the delivery, and the control
+                 * plane stamps `delivered_at` at hand-off and never re-sends. So a
+                 * transient failure here — a backend hiccup or slow process — would
+                 * otherwise drop the user's approval PERMANENTLY, leaving the
+                 * question card open with no way to answer it again and the turn
+                 * waiting for ever (the approval wait is deliberately excluded from
+                 * the turn deadline, so nothing else ends it either).
+                 *
+                 * Forgetting the commandId is the cheap half: it costs nothing, and
+                 * if the command is ever delivered again the answer is retried
+                 * instead of being discarded as a duplicate. The control plane does
+                 * not re-send today, so this is a latch for a retry that does not yet
+                 * exist rather than a fix on its own — which is why the failure is
+                 * ALSO pushed into the transcript, where the user can see it.
+                 */
+                log('Answer command threw', {
+                    sessionId: command.sessionId,
+                    commandId: command.commandId,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+                this.recoverFailedAnswer(runner, command, error instanceof Error ? error.message : String(error));
+            });
+        }
+    }
+    async releaseSessionWorkspace(sessionId) {
+        try {
+            const released = await this.workspace.release(sessionId, { force: true });
+            log(released === false
+                ? 'Session workspace release refused; keeping workspace'
+                : 'Session workspace release processed', { sessionId });
+        }
+        catch (error) {
+            log('Session workspace release failed; keeping workspace', {
+                sessionId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    /**
+     * A user's answer did not reach the backend. Do the two things that keep it
+     * from vanishing.
+     *
+     * 1. FORGET THE commandId, so a redelivery is retried rather than discarded
+     *    as a duplicate. On its own this fixes nothing — the control plane stamps
+     *    `delivered_at` at hand-off and does not resend today — so it is a latch
+     *    for a retry that does not yet exist.
+     * 2. TELL THE USER, in the transcript. This is the half that actually
+     *    reaches them: without it the question card stays open, the turn keeps
+     *    waiting (approval time is deliberately outside the turn deadline, so
+     *    nothing else ends it), and a click is indistinguishable from a slow
+     *    backend.
+     */
+    recoverFailedAnswer(runner, command, reason) {
+        this.appliedCommands.delete(command.commandId);
+        void runner.reportApprovalFailure(command.sessionId, reason).catch(() => {
+            // If even that cannot be delivered, the log at the call site is all
+            // there is. Never let reporting a failure become a second failure.
+        });
+    }
+    /* ------------------------------------------------------------------ */
+    /* The lease loop                                                      */
+    /* ------------------------------------------------------------------ */
+    async runLeaseLoop() {
+        while (!this.stopping && !this.fatal) {
+            // Either pin can move independently — a tools-only bump must drain and
+            // re-invoke the supervisor exactly like a harness bump does, because
+            // pf-bootstrap's re-dial of /harness/bootstrap is what actually
+            // resyncs BOTH layers, not just the one that changed.
+            if (this.pendingHarnessVersion || this.pendingSandboxToolsVersion) {
+                if (this.active.size === 0) {
+                    await this.requestUpgrade(this.pendingHarnessVersion ?? (0, version_1.getHarnessVersion)(), this.pendingSandboxToolsVersion ?? undefined);
+                    break;
+                }
+                // A pin can change while a long poll is returning a live lease. Finish
+                // that lease, but do not open another poll while the update is pending.
+                await sleep(500);
+                continue;
+            }
+            if (this.status === 'draining') {
+                // Draining means "finish what you hold, take nothing new".
+                if (this.active.size === 0) {
+                    break;
+                }
+                await sleep(1_000);
+                continue;
+            }
+            const max = this.capabilities?.maxConcurrentSessions ?? 1;
+            if (this.active.size >= max) {
+                await sleep(500);
+                continue;
+            }
+            let lease = null;
+            try {
+                lease = await this.client.lease(this.leaseWaitSeconds);
+            }
+            catch (error) {
+                if (error instanceof control_plane_1.ProtocolRefusedError) {
+                    this.fatal = new VersionRefusedError(`Control plane raised its protocol floor: ${error.message}`);
+                    break;
+                }
+                if (error instanceof control_plane_1.ControlPlaneError && error.final) {
+                    this.fatal = error;
+                    break;
+                }
+                log('Lease poll failed', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
+                await sleep(LEASE_ERROR_BACKOFF_MS);
+                continue;
+            }
+            if (!lease) {
+                // 204: no work. Poll again immediately — the wait already happened
+                // server-side, which is the entire point of a bounded long-poll.
+                continue;
+            }
+            this.observeHarnessPin(lease.harnessVersion);
+            this.observeSandboxToolsPin(lease.sandboxToolsVersion);
+            void this.runLeasedTurn(lease);
+        }
+        await this.stop();
+    }
+    /**
+     * Record a changed pin. Only managed sandboxes have the baked supervisor
+     * that can service the distinguished exit code.
+     */
+    observeHarnessPin(version) {
+        if (this.options.runtime !== 'sandbox' ||
+            typeof version !== 'string' ||
+            version.length === 0 ||
+            version === (0, version_1.getHarnessVersion)() ||
+            this.pendingHarnessVersion) {
+            return;
+        }
+        this.pendingHarnessVersion = version;
+        log('Harness upgrade pending; waiting for idle', {
+            currentHarnessVersion: (0, version_1.getHarnessVersion)(),
+            requestedHarnessVersion: version,
+            activeSessions: this.active.size
+        });
+    }
+    /**
+     * Same shape as observeHarnessPin(), for the INDEPENDENT sandbox-tools pin.
+     * A host that never reported an installed tools version (self-hosted,
+     * desktop, or a sandbox that predates this layer) has nothing to compare
+     * against and is left alone rather than treated as "version none, always
+     * behind" — that would drain and exit-75 every such host on every lease.
+     */
+    observeSandboxToolsPin(version) {
+        const installed = (0, version_1.getInstalledSandboxToolsVersion)();
+        if (this.options.runtime !== 'sandbox' ||
+            typeof version !== 'string' ||
+            version.length === 0 ||
+            installed === null ||
+            version === installed ||
+            this.pendingSandboxToolsVersion) {
+            return;
+        }
+        // THE LOOP GUARD. pf-bootstrap already tried this EXACT pin this boot
+        // cycle and it did not stick (bad hash, registry outage, a malformed
+        // value) — arming it again would drain, exit 75, reboot, hit the same
+        // failure, fall back or keep what's there, and arrive right back here
+        // with the SAME mismatch, forever, taking zero leases the whole time. A
+        // control plane that sends a genuinely different pin — including a
+        // corrected one — is unaffected, since this only suppresses an exact
+        // repeat.
+        if (version === (0, version_1.getAttemptedSandboxToolsVersion)()) {
+            log('Sandbox tools pin already attempted and not achieved this boot; not re-arming', {
+                installedSandboxToolsVersion: installed,
+                attemptedSandboxToolsVersion: version
+            });
+            return;
+        }
+        this.pendingSandboxToolsVersion = version;
+        log('Sandbox tools upgrade pending; waiting for idle', {
+            installedSandboxToolsVersion: installed,
+            requestedSandboxToolsVersion: version,
+            activeSessions: this.active.size
+        });
+    }
+    /** Stop once. A failed install is then the supervisor's terminal decision. */
+    async requestUpgrade(harnessVersion, sandboxToolsVersion) {
+        const runnerId = this.runnerId;
+        const runnerCredential = this.client.getRunnerCredential();
+        if (!runnerId || !runnerCredential) {
+            this.fatal = new Error('Cannot request a harness upgrade without a live runner credential');
+            return;
+        }
+        this.status = 'draining';
+        this.deps.onUpgradeRequested?.({
+            harnessVersion,
+            ...(sandboxToolsVersion ? { sandboxToolsVersion } : {}),
+            runnerId,
+            tenantId: this.tenantId,
+            runnerCredential
+        });
+        this.fatal = new UpgradeRequestedError(harnessVersion);
+        await this.stop({ preserveRegistration: true });
+    }
+    /**
+     * Run one leased turn.
+     *
+     * NOT awaited by the loop, so a runner allowed more than one concurrent
+     * session actually gets one. Every failure is contained here: a turn that
+     * throws must not end the lease loop, or one bad session would take the whole
+     * runner offline.
+     */
+    async runLeasedTurn(lease) {
+        const { sessionId } = lease.session;
+        // The exact loopback-proxy targets this session will reach. Keyed on these
+        // urls, this session's MCP token cannot be overwritten or revoked by a
+        // concurrent turn — each url embeds its own session id.
+        const mcpTargetUrls = (lease.session.agent.mcpServers ?? []).map((server) => server.url);
+        const controller = new AbortController();
+        this.active.set(sessionId, controller);
+        this.status = 'busy';
+        const githubWorkspace = this.workspace;
+        if (lease.githubCredential) {
+            githubWorkspace.setCredential?.(sessionId, lease.githubCredential);
+        }
+        // KEEP THE LEASE ALIVE FOR THE DURATION OF THE TURN.
+        //
+        // Ingest piggy-backs a renewal on every batch, so a chatty turn never needs
+        // this. But a turn that is slow AND SILENT — one long tool call, one slow
+        // model — would produce nothing to ingest for over LEASE_TTL_MS (120s), its
+        // lease would expire, and the watchdog would hand the SAME turn to another
+        // runner while this one is still working. The timer renews well inside that
+        // window; a `renewed:false` means another runner already owns the session,
+        // so we ABANDON rather than keep spending model budget on stolen work.
+        /*
+         * `renewal` and `runner` (below) reference EACH OTHER: `runner`'s
+         * `onApprovalStateChange` calls `renewal.setUrgent`, and (per the LONG
+         * TURNS fix) `renewalCallbacks.onModelCredential` calls
+         * `runner.updateModelCredential`. Neither can be declared strictly after
+         * the other, so this indirection breaks the cycle: `runnerRef` exists
+         * (as `null`) before `renewalCallbacks` is built, and is pointed at the
+         * real instance once it exists, a few statements below. Safe because
+         * both callbacks are event-driven and fire only later, never during this
+         * function's own synchronous setup.
+         */
+        let runnerRef = null;
+        /*
+         * THE RENEWAL IS ALSO THE APPROVAL CHANNEL. Two jobs, one call — see the
+         * long note on `APPROVAL_RENEW_INTERVAL_MS` for why the renew route and not
+         * the heartbeat, and why the cadence changes.
+         */
+        const renewalCallbacks = {
+            leaseId: lease.leaseId,
+            intervalMs: this.deps.leaseRenewIntervalMs,
+            // While a permission prompt is open, renew — and therefore collect
+            // commands — every couple of seconds instead of every minute.
+            urgentIntervalMs: this.deps.approvalRenewIntervalMs,
+            onCommands: (commands) => {
+                for (const command of commands) {
+                    this.applyCommand(command);
+                }
+            },
+            githubTokenExpiresAt: lease.githubCredential?.expiresAt,
+            onGithubCredential: (credential) => {
+                githubWorkspace.setCredential?.(sessionId, credential);
+                log('GitHub installation token refreshed in memory', {
+                    sessionId,
+                    expiresAt: credential.expiresAt
+                });
+            },
+            // See `LeaseResponse.modelTokenExpiresAt` — absent for a sandbox's
+            // per-SANDBOX key, so this simply never enters the refresh margin on
+            // that runtime and the callback never fires there.
+            modelTokenExpiresAt: lease.modelTokenExpiresAt,
+            onModelCredential: (credential) => {
+                runnerRef?.updateModelCredential(sessionId, credential.token, credential.expiresAt);
+                log('Per-turn model key refreshed in memory', {
+                    sessionId,
+                    expiresAt: credential.expiresAt
+                });
+            },
+            onLost: (reason) => {
+                log('Lease lost mid-turn; aborting', { sessionId, reason });
+                controller.abort();
+            },
+            log
+        };
+        const isolated = this.client.isolatedLeaseRenewalConfig();
+        let renewal;
+        if (isolated) {
+            try {
+                renewal = (0, lease_renewal_1.startIsolatedLeaseRenewal)({
+                    ...renewalCallbacks,
+                    url: isolated.url,
+                    runnerCredential: isolated.runnerCredential
+                });
+            }
+            catch (error) {
+                log('Could not start isolated lease renewal; using main event loop', {
+                    leaseId: lease.leaseId,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+                renewal = (0, lease_renewal_1.startLeaseRenewal)({
+                    ...renewalCallbacks,
+                    client: this.client
+                });
+            }
+        }
+        else {
+            renewal = (0, lease_renewal_1.startLeaseRenewal)({
+                ...renewalCallbacks,
+                client: this.client
+            });
+        }
+        this.activeRenewals.add(renewal);
+        // The session-scoped MCP token is installed for the duration of the turn
+        // and revoked immediately after. It never reaches the backend: the agent is
+        // pointed at the loopback proxy, and the proxy attaches this token itself.
+        //
+        // PER TARGET, NOT PROCESS-WIDE. `runLeasedTurn` is started with `void` and
+        // never awaited, so with `maxConcurrentSessions > 1` several turns are in
+        // flight at once. A single shared token holder let turn B overwrite turn A's
+        // credential and let whichever finished first revoke it out from under the
+        // other — after which the survivor's MCP calls carried the wrong session's
+        // token (or none) and the gateway answered 401, surfacing as an OAuth error
+        // and a `create_artifact` that failed for the rest of the turn.
+        this.tokens.registerTargets(mcpTargetUrls, lease.mcpToken);
+        /*
+         * ONE GATEWAY PER TURN, NOT ONE PER PROCESS.
+         *
+         * `runLeasedTurn` is started with `void` and never awaited, so with
+         * `maxConcurrentSessions > 1` several turns are in flight at once. A single
+         * shared holder would let turn B overwrite turn A's credential, and let
+         * whichever finished first REVOKE the gateway out from under the other —
+         * after which the survivor silently loses its `peakflo` provider and falls
+         * back to the host's own credentials, which is the exact failure the
+         * refusal in `SessionRunner` exists to prevent.
+         *
+         * The holder is deliberately NOT shared the way `tokens` is. That one must
+         * be re-pointed rather than replaced because the loopback MCP proxy keeps a
+         * reference for the whole process life. Nothing holds a gateway that long:
+         * `getAdapter` builds a NEW adapter for every turn, so a fresh holder per
+         * turn is both safe and strictly more correct.
+         *
+         * S4's concurrency measurement did not catch this, and it is worth saying
+         * why: all three concurrent turns used the same agent, so the credential
+         * being overwritten was byte-identical to the one replacing it. The test
+         * passed for the wrong reason.
+         */
+        const modelGateway = new model_gateway_1.SessionModelGateway();
+        const runner = new session_runner_1.SessionRunner({
+            getAdapter: (backend) => {
+                const build = this.deps.getAdapter;
+                if (!build) {
+                    throw new Error(`No adapter is wired for backend "${backend}". ` +
+                        'Pass getAdapter in HarnessDeps.');
+                }
+                return build(backend, { modelGateway });
+            },
+            modelGateway,
+            store: this.store,
+            workspace: this.workspace,
+            proxy: this.proxy,
+            secrets: this.secrets,
+            events: this.events,
+            telemetry: this.telemetry,
+            notifier: this.notifier,
+            artifacts: this.artifacts,
+            conversation: this.conversation,
+            fetchHistory: async (id) => {
+                const history = await this.client.sessionHistory(id, lease.leaseId);
+                return {
+                    backendSessionId: history.backendSessionId ?? null,
+                    // Threaded through DELIBERATELY. Dropping it here is what let a cold
+                    // runner adopt another machine's Pi session file: the guard in
+                    // `loadMemory` cannot refuse an owner it was never told.
+                    backendOwnerId: history.backendOwnerId ?? null,
+                    messages: history.messages ?? []
+                };
+            },
+            /*
+             * THE LATENCY WIRE. The runner tells the harness the moment a turn starts
+             * or stops waiting on a human, and the harness uses that to decide how
+             * hard to poll the control plane for the answer. Nothing else in the
+             * process knows a permission is outstanding.
+             */
+            onApprovalStateChange: (id, waiting) => {
+                /*
+                 * NO SET IS KEPT HERE. An earlier version also maintained an
+                 * `awaitingApproval` Set that nothing ever read — the cadence is driven
+                 * entirely by `setUrgent` below. A write-only collection invites the
+                 * next reader to assume it gates something, so it is gone rather than
+                 * left as decoration.
+                 */
+                // Event-driven, not polled: the cadence changes at the instant the
+                // prompt opens, so the first tight renewal happens ~2s later rather
+                // than up to a minute later.
+                renewal.setUrgent(waiting);
+                log('Approval state changed', { sessionId: id, waiting });
+            },
+            ingest: (id, parts, turn, final, modelMessages) => this.client
+                .ingest(id, {
+                leaseId: lease.leaseId,
+                parts,
+                turn,
+                final,
+                modelMessages
+            })
+                .then(() => undefined)
+        });
+        runnerRef = runner;
+        // Registered BEFORE the turn starts. A permission can be raised on the
+        // backend's very first tool call, and an answer that arrives before this
+        // map is populated would be dropped as "a session this runner is not
+        // running" — which is indistinguishable, in the log, from a real
+        // mis-routing.
+        this.runners.set(sessionId, runner);
+        try {
+            const result = await runner.run(lease, controller.signal);
+            log('Turn finished', {
+                sessionId,
+                stopReason: result.turn.stopReason,
+                parts: result.partsProduced
+            });
+        }
+        catch (error) {
+            // Reaching here means the CONTROL PLANE could not be told, which is the
+            // one failure the runner cannot report through the control plane. The
+            // lease will expire and the watchdog will requeue the session.
+            log('Turn failed to report', {
+                sessionId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+        finally {
+            renewal.stop();
+            this.activeRenewals.delete(renewal);
+            let workProtected = true;
+            if ((this.options.autoCommitDirtyWorktree ??
+                this.options.runtime === 'sandbox') &&
+                this.workspace.preserveAtTurnEnd) {
+                try {
+                    workProtected = await this.workspace.preserveAtTurnEnd(sessionId);
+                    if (!workProtected) {
+                        log('worktree-wip-push-failed', { sessionId });
+                    }
+                }
+                catch (error) {
+                    workProtected = false;
+                    log('worktree-wip-push-failed', {
+                        sessionId,
+                        error: error instanceof Error ? error.message : String(error)
+                    });
+                }
+            }
+            // Keep the session active until preservation finishes. A release command
+            // that arrives during the commit must defer, never delete under Git.
+            this.active.delete(sessionId);
+            this.runners.delete(sessionId);
+            // Revoke ONLY this session's tokens. A process-wide revoke here blanked
+            // the credential of every concurrent turn still running.
+            this.tokens.revokeTargets(mcpTargetUrls);
+            modelGateway.revoke();
+            githubWorkspace.clearCredential?.(sessionId);
+            if (this.pendingWorkspaceReleases.delete(sessionId)) {
+                if (workProtected) {
+                    await this.releaseSessionWorkspace(sessionId);
+                }
+                else {
+                    log('Session workspace release deferred after WIP push failure', {
+                        sessionId
+                    });
+                }
+            }
+            if (this.status === 'busy' && this.active.size === 0) {
+                this.status = 'ready';
+            }
+        }
+    }
+}
+exports.Harness = Harness;