@peakflo/agent-harness 0.2.5-rc.1 → 0.2.5-rc.3

package/dist/adapters/coding-agent-adapter.d.ts

@@ -186,6 +186,8 @@ export interface CodingAgentAdapter {
      * not (the caller still has the transcript note either way).
      */
     steerTurn?(sessionId: string, text: string, config: SessionConfig): Promise<boolean>;
+    /** A human message. Return true only once the live backend has accepted it. */
+    steerUserMessage?(sessionId: string, text: string, config: SessionConfig): Promise<boolean>;
     /**
      * Get current session status
      */

package/dist/adapters/pi-adapter.d.ts

@@ -89,6 +89,7 @@ export declare class PiAdapter implements CodingAgentAdapter {
     private consumeStdout;
     private handleJsonlLine;
     private rejectPending;
+    private refreshSteeringActivityAtIdle;
     private handleEvent;
     private handleExtensionUiRequest;
     private uiRequestMessage;
@@ -110,6 +111,8 @@ export declare class PiAdapter implements CodingAgentAdapter {
      * into an already-running turn must not reset them.
      */
     steerTurn(sessionId: string, text: string, _config: SessionConfig): Promise<boolean>;
+    /** Resolve only when Pi emits the queued user message into the active turn. */
+    steerUserMessage(sessionId: string, text: string, _config: SessionConfig): Promise<boolean>;
     getStatus(sessionId: string, _config: SessionConfig): Promise<SessionStatus>;
     private settlePendingTurnError;
     pollMessages(sessionId: string): Promise<MessagePart[]>;

package/dist/adapters/pi-adapter.js

@@ -30,6 +30,9 @@ const MINIMUM_PI_VERSION = [0, 80, 5];
 const PI_PERMISSION_MODE_ENV = 'PEAKFLO_PI_PERMISSION_MODE';
 exports.PI_DEV_SERVER_POLICY_ENV = 'PF_DEV_SERVER_POLICY_FILE';
 const TERMINAL_ERROR_SETTLE_GRACE_MS = 1_000;
+// A tool may be silent for the full progress-guard window. Turn finalization
+// has its own short bound; this timer protects an active turn with no echo.
+const STEER_CONSUMPTION_TIMEOUT_MS = 20 * 60_000;
 const piInstanceIdCache = new Map();
 /**
  * Most model providers cap function/tool `name` at 64 characters. Pi forwards
@@ -228,6 +231,16 @@ function textFromContent(content) {
         .map((block) => String(block.text ?? ''))
         .join('');
 }
+function normalizeSteerText(text) {
+    return text.replace(/\r\n?/g, '\n').trim();
+}
+function safeSteeringError(error) {
+    // Pi may include the submitted prompt in an RPC error. Never log the error
+    // text here; even URL and token redaction cannot remove arbitrary user data.
+    return error instanceof Error && /timed out/i.test(error.message)
+        ? 'rpc-timeout'
+        : 'rpc-error';
+}
 function resultText(result) {
     if (!result || typeof result !== 'object')
         return '';
@@ -471,6 +484,8 @@ class PiAdapter {
             status: 'idle',
             lastError: null,
             pending: new Map(),
+            pendingSteers: [],
+            steeringSupported: true,
             parts: [],
             allMessages: [],
             stdoutBuffer: '',
@@ -502,6 +517,17 @@ class PiAdapter {
         };
     }
     async applySelection(session, config) {
+        // An older Pi can reject this RPC. Keep ordinary turns working and let the
+        // control plane queue any steer that this process cannot consume.
+        try {
+            await this.command(session, { type: 'set_steering_mode', mode: 'all' });
+        }
+        catch (error) {
+            console.warn(`[PiAdapter/${session.id}] Pi did not accept steering mode; this session will queue new messages: ${safeSteeringError(error)}`);
+            // We cannot prove that Pi applied the mode after a timeout. Treat both
+            // explicit rejection and transport failure as a queue fallback.
+            session.steeringSupported = false;
+        }
         if (config.model && config.model !== 'default') {
             const { provider, modelId } = this.splitModel(config.model);
             if (!provider || !modelId) {
@@ -669,12 +695,41 @@ class PiAdapter {
         }
     }
     rejectPending(session, error) {
+        for (const steer of session.pendingSteers.splice(0))
+            steer.resolve(false);
         for (const request of session.pending.values()) {
             clearTimeout(request.timer);
             request.reject(error);
         }
         session.pending.clear();
     }
+    async refreshSteeringActivityAtIdle(session) {
+        const observedTurn = session.turn;
+        try {
+            const state = await this.command(session, { type: 'get_state' });
+            if (session.turn !== observedTurn ||
+                session.status === 'error' ||
+                session.closing)
+                return;
+            if (Number(state.data?.pendingMessageCount ?? 0) > 0 ||
+                state.data?.isStreaming === true) {
+                session.status = 'busy';
+            }
+            else {
+                session.status = 'idle';
+            }
+        }
+        catch (error) {
+            console.warn(`[PiAdapter/${session.id}] Could not inspect steering queue at idle: ${safeSteeringError(error)}`);
+            if (session.turn === observedTurn &&
+                session.status !== 'error' &&
+                !session.closing)
+                session.status = 'idle';
+        }
+        // An empty queue is not proof of non-consumption: Pi can remove a message
+        // just before emitting message_start. The turn close requeues unconfirmed
+        // messages after its bounded wait.
+    }
     handleEvent(session, event) {
         if (event.type === 'response') {
             const response = event;
@@ -728,10 +783,17 @@ class PiAdapter {
                 break;
             case 'agent_settled': {
                 this.cancelPendingUiRequests(session, 'This request is no longer active.');
-                if (session.pendingTurnError)
+                if (session.pendingTurnError) {
                     this.settlePendingTurnError(session);
-                else
-                    session.status = 'idle';
+                }
+                else {
+                    session.status = session.pendingSteers.length ? 'busy' : 'idle';
+                    // Pi can settle after a tool even with a steer still queued.
+                    // Keep the session busy until this state read completes.
+                    if (session.pendingSteers.length) {
+                        void this.refreshSteeringActivityAtIdle(session);
+                    }
+                }
                 session.promptMayBeCommandOnly = false;
                 break;
             }
@@ -739,6 +801,16 @@ class PiAdapter {
                 const message = event.message;
                 if (message?.role === 'assistant')
                     session.assistantMessageOrdinal++;
+                if (message?.role === 'user') {
+                    const text = textFromContent(message.content);
+                    // Pi gives no steer ID on this event. Match the oldest equal text.
+                    // This assumes an equal user event came from Pi's prompt queue; an
+                    // unrelated equal user event could confirm the steer early.
+                    const index = session.pendingSteers.findIndex((steer) => normalizeSteerText(steer.text) === normalizeSteerText(text));
+                    if (index >= 0) {
+                        session.pendingSteers.splice(index, 1)[0].resolve(true);
+                    }
+                }
                 break;
             }
             case 'message_update':
@@ -1107,8 +1179,45 @@ class PiAdapter {
             });
             return true;
         }
-        catch {
+        catch (error) {
+            console.warn(`[PiAdapter/${session.id}] Pi could not accept a steer message: ${safeSteeringError(error)}`);
+            return false;
+        }
+    }
+    /** Resolve only when Pi emits the queued user message into the active turn. */
+    async steerUserMessage(sessionId, text, _config) {
+        const session = this.sessions.get(sessionId);
+        if (!session ||
+            session.status !== 'busy' ||
+            session.steeringSupported === false ||
+            !text)
             return false;
+        let resolveSeen;
+        const seen = new Promise((resolve) => {
+            resolveSeen = resolve;
+        });
+        const waiter = { text, resolve: resolveSeen };
+        session.pendingSteers.push(waiter);
+        // A timeout can requeue text Pi already consumed if its user event was
+        // lost. Durable exact-once recovery is tracked by task_1791540809105_ual6uq3.
+        const timer = setTimeout(() => resolveSeen(false), STEER_CONSUMPTION_TIMEOUT_MS);
+        timer.unref?.();
+        try {
+            await this.command(session, {
+                type: 'steer',
+                message: text
+            });
+            return await seen;
+        }
+        catch (error) {
+            console.warn(`[PiAdapter/${session.id}] Pi could not accept a steer message: ${safeSteeringError(error)}`);
+            return false;
+        }
+        finally {
+            clearTimeout(timer);
+            const index = session.pendingSteers.indexOf(waiter);
+            if (index >= 0)
+                session.pendingSteers.splice(index, 1);
         }
     }
     async getStatus(sessionId, _config) {

package/dist/capabilities.d.ts

@@ -32,6 +32,8 @@ import { RunnerCapabilities } from './types';
  *   `knowledge_files_list` / `knowledge_file_download` (P9).
  */
 export declare const HARNESS_FEATURES: readonly ["spaceFiles"];
+/** Steering mode was verified with Pi 0.84.3. Older Pi keeps the queue path. */
+export declare function supportsPiSteering(version: string | null): boolean;
 export interface ProbeResult {
     installed: boolean;
     version: string | null;

package/dist/capabilities.js

@@ -26,6 +26,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HARNESS_FEATURES = void 0;
+exports.supportsPiSteering = supportsPiSteering;
 exports.probe = probe;
 exports.probeCapabilities = probeCapabilities;
 const node_child_process_1 = require("node:child_process");
@@ -42,6 +43,25 @@ const PROBE_TIMEOUT_MS = 10_000;
  *   `knowledge_files_list` / `knowledge_file_download` (P9).
  */
 exports.HARNESS_FEATURES = ['spaceFiles'];
+/** Steering mode was verified with Pi 0.84.3. Older Pi keeps the queue path. */
+function supportsPiSteering(version) {
+    if (!version)
+        return false;
+    // Only a stable release was verified. A prerelease or custom build can
+    // change the RPC contract even when its base version meets the minimum.
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+    if (!match)
+        return false;
+    const parts = match.slice(1, 4).map(Number);
+    const minimum = [0, 84, 3];
+    for (let index = 0; index < minimum.length; index++) {
+        if (parts[index] > minimum[index])
+            return true;
+        if (parts[index] < minimum[index])
+            return false;
+    }
+    return true;
+}
 /**
  * The coding-agent backends this harness knows how to drive, and the command
  * that reports each one's version.
@@ -105,7 +125,7 @@ function probe(command, args = ['--version']) {
                 const raw = String(stdout).trim();
                 // Same expression as detect.js: pick the first version-like token, and
                 // fall back to the first line when a tool prints something exotic.
-                const match = raw.match(/(\d+\.\d+[\w.-]*)/);
+                const match = raw.match(/(\d+\.\d+[\w.+-]*)/);
                 finish({
                     installed: true,
                     version: match ? match[1] : raw.split('\n')[0] || null
@@ -165,7 +185,12 @@ async function probeCapabilities(options = {}) {
         git: git.installed,
         docker: docker.installed,
         maxConcurrentSessions: options.maxConcurrentSessions ?? 1,
-        features: [...exports.HARNESS_FEATURES],
+        features: [
+            ...exports.HARNESS_FEATURES,
+            ...(backends.some((backend) => backend.name === 'pi' && supportsPiSteering(backend.version))
+                ? ['steerMessages']
+                : [])
+        ],
         labels: options.labels
     };
 }

package/dist/contract.d.ts

@@ -196,6 +196,7 @@ export declare const ROUTES: {
     readonly lease: (runnerId: string, waitSeconds?: number, protocolVersion?: number) => string;
     /** Bearer: runner credential. Visibility-timeout renewal. */
     readonly leaseRenew: (runnerId: string, leaseId: string) => string;
+    readonly steerAck: (runnerId: string, leaseId: string, turnId: string) => string;
     /** Bearer: runner credential. Metadata of the knowledge files this turn may read. */
     readonly knowledgeFiles: (runnerId: string, leaseId: string) => string;
     /** Bearer: runner credential. A short-lived download URL for one knowledge file. */

package/dist/contract.js

@@ -236,6 +236,7 @@ exports.ROUTES = {
     },
     /** Bearer: runner credential. Visibility-timeout renewal. */
     leaseRenew: (runnerId, leaseId) => `/api/runners/${encodeURIComponent(runnerId)}/lease/${encodeURIComponent(leaseId)}/renew`,
+    steerAck: (runnerId, leaseId, turnId) => `/api/runners/${encodeURIComponent(runnerId)}/lease/${encodeURIComponent(leaseId)}/steer/${encodeURIComponent(turnId)}/ack`,
     /** Bearer: runner credential. Metadata of the knowledge files this turn may read. */
     knowledgeFiles: (runnerId, leaseId) => `/api/runners/${encodeURIComponent(runnerId)}/lease/${encodeURIComponent(leaseId)}/knowledge/files`,
     /** Bearer: runner credential. A short-lived download URL for one knowledge file. */

package/dist/control-plane.d.ts

@@ -150,6 +150,9 @@ export declare class ControlPlaneClient {
      * idempotent.
      */
     ingest(sessionId: string, request: Omit<IngestRequest, 'protocolVersion'>): Promise<IngestResponse>;
+    acknowledgeSteer(sessionId: string, leaseId: string, turnId: string, consumed: boolean): Promise<{
+        delivery: 'steered' | 'queued';
+    }>;
     /**
      * Read the session's model-facing conversation back from the control plane.
      *

package/dist/control-plane.js

@@ -329,6 +329,14 @@ class ControlPlaneClient {
             body: { protocolVersion: contract_1.PROTOCOL_VERSION, ...request }
         }));
     }
+    async acknowledgeSteer(sessionId, leaseId, turnId, consumed) {
+        return this.withRetry('steer-ack', () => this.send({
+            method: 'POST',
+            path: contract_1.ROUTES.steerAck(this.requireRunnerId(), leaseId, turnId),
+            token: this.requireCredential(),
+            body: { protocolVersion: contract_1.PROTOCOL_VERSION, sessionId, consumed }
+        }));
+    }
     /* ------------------------------------------------------------------ */
     /* 5b. session history — the runner's READ path                        */
     /* ------------------------------------------------------------------ */

package/dist/harness.d.ts

@@ -174,10 +174,15 @@ export declare class Harness {
     private releaseGitHubGuard;
     /** sessionId -> the controller that aborts its turn. */
     private readonly active;
+    private readonly activeLeaseIds;
     /** Renewal workers that must receive a credential rotation in flight. */
     private readonly activeRenewals;
     /** commandIds already applied. `SessionCommand` is idempotent by contract. */
     private readonly appliedCommands;
+    /** Prune lease-bound command IDs when their session turn ends. */
+    private readonly appliedCommandsBySession;
+    /** A steer can arrive on renewal while a leased runner is still starting. */
+    private readonly deferredSteers;
     /** Session-end cleanup waits for an active turn to save its dirty work. */
     private readonly pendingWorkspaceReleases;
     /**
@@ -283,14 +288,19 @@ export declare class Harness {
     private modelsNeedRefresh;
     private scheduleHeartbeat;
     private sendHeartbeat;
+    /** A bad command must not stop the others or fail a transcript ingest. */
+    private applyCommandsSafely;
+    private forgetAppliedCommand;
+    private clearAppliedCommandsForSession;
     /**
-     * Apply a command that rode back on a heartbeat.
+     * Apply a command that rode back on a heartbeat or ingest response.
      *
-     * 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.
+     * Idempotent by `commandId`, because the control plane may repeat a command
+     * until it observes the effect; it cannot dial the harness to ask.
      */
     private applyCommand;
+    /** Deliver commands received while the leased runner was still starting. */
+    private flushDeferredSteers;
     private releaseSessionWorkspace;
     /**
      * A user's answer did not reach the backend. Do the two things that keep it

package/dist/harness.js

@@ -151,10 +151,15 @@ class Harness {
     releaseGitHubGuard = null;
     /** sessionId -> the controller that aborts its turn. */
     active = new Map();
+    activeLeaseIds = 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();
+    /** Prune lease-bound command IDs when their session turn ends. */
+    appliedCommandsBySession = new Map();
+    /** A steer can arrive on renewal while a leased runner is still starting. */
+    deferredSteers = new Map();
     /** Session-end cleanup waits for an active turn to save its dirty work. */
     pendingWorkspaceReleases = new Set();
     /**
@@ -339,6 +344,7 @@ class Harness {
         }
         this.stopping = true;
         this.status = 'draining';
+        this.deferredSteers.clear();
         if (this.heartbeatTimer) {
             clearTimeout(this.heartbeatTimer);
             this.heartbeatTimer = null;
@@ -507,9 +513,7 @@ class Harness {
             }
             this.observeHarnessPin(response.harnessVersion);
             this.observeSandboxToolsPin(response.sandboxToolsVersion);
-            for (const command of response.sessionCommands ?? []) {
-                this.applyCommand(command);
-            }
+            this.applyCommandsSafely(response.sessionCommands ?? []);
             log('Reused stored runner credential', {
                 runnerId: stored.runnerId,
                 tenantId: stored.tenantId
@@ -783,9 +787,7 @@ class Harness {
             }
             this.observeHarnessPin(response.harnessVersion);
             this.observeSandboxToolsPin(response.sandboxToolsVersion);
-            for (const command of response.sessionCommands ?? []) {
-                this.applyCommand(command);
-            }
+            this.applyCommandsSafely(response.sessionCommands ?? []);
             if (response.action === 'drain') {
                 this.status = 'draining';
                 log('Control plane asked the harness to drain');
@@ -823,21 +825,85 @@ class Harness {
         }
         this.scheduleHeartbeat();
     }
+    /** A bad command must not stop the others or fail a transcript ingest. */
+    applyCommandsSafely(commands) {
+        for (const command of commands) {
+            try {
+                this.applyCommand(command);
+            }
+            catch (error) {
+                // Commands are a side channel. An application error must not reject
+                // the ingest of model output or skip the commands after this one.
+                this.forgetAppliedCommand(command);
+                log('Session command failed', {
+                    sessionId: command.sessionId,
+                    commandId: command.commandId,
+                    command: command.command,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    }
+    forgetAppliedCommand(command) {
+        this.appliedCommands.delete(command.commandId);
+        const ids = this.appliedCommandsBySession.get(command.sessionId);
+        ids?.delete(command.commandId);
+        if (ids?.size === 0)
+            this.appliedCommandsBySession.delete(command.sessionId);
+    }
+    clearAppliedCommandsForSession(sessionId) {
+        for (const id of this.appliedCommandsBySession.get(sessionId) ?? []) {
+            this.appliedCommands.delete(id);
+        }
+        this.appliedCommandsBySession.delete(sessionId);
+    }
     /**
-     * Apply a command that rode back on a heartbeat.
+     * Apply a command that rode back on a heartbeat or ingest response.
      *
-     * 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.
+     * Idempotent by `commandId`, because the control plane may repeat a command
+     * until it observes the effect; it cannot dial the harness to ask.
      */
     applyCommand(command) {
         if (this.appliedCommands.has(command.commandId)) {
             return;
         }
         this.appliedCommands.add(command.commandId);
+        const sessionCommands = this.appliedCommandsBySession.get(command.sessionId) ?? new Set();
+        sessionCommands.add(command.commandId);
+        this.appliedCommandsBySession.set(command.sessionId, sessionCommands);
+        if (command.command === 'steer') {
+            const runner = this.runners.get(command.sessionId);
+            if (!runner || !command.turnId || !command.leaseId || !command.input) {
+                if (!runner && command.turnId && command.leaseId && command.input) {
+                    this.deferredSteers.set(command.commandId, command);
+                }
+                this.forgetAppliedCommand(command);
+                // The durable turn remains queued until Pi confirms consumption.
+                return;
+            }
+            if (this.activeLeaseIds.get(command.sessionId) !== command.leaseId) {
+                this.forgetAppliedCommand(command);
+                return;
+            }
+            runner.steerMessage({
+                sessionId: command.sessionId,
+                turnId: command.turnId,
+                input: command.input,
+                acknowledge: async (consumed) => (await this.client.acknowledgeSteer(command.sessionId, command.leaseId, command.turnId, consumed)).delivery
+            });
+            return;
+        }
         if (command.command === 'abort') {
             const controller = this.active.get(command.sessionId);
-            if (controller) {
+            const activeLeaseId = this.activeLeaseIds.get(command.sessionId);
+            if (!controller || (command.optionId && !activeLeaseId)) {
+                // A command can arrive between lease claim and local runner setup.
+                // Leave its id open so the control plane's safe abort redelivery can
+                // apply it once this exact lease is active.
+                this.forgetAppliedCommand(command);
+                return;
+            }
+            if (!command.optionId || activeLeaseId === command.optionId) {
                 log('Aborting session by control-plane command', {
                     sessionId: command.sessionId
                 });
@@ -855,7 +921,7 @@ class Harness {
                 });
             }
             else {
-                void this.releaseSessionWorkspace(command.sessionId);
+                void this.releaseSessionWorkspace(command.sessionId).finally(() => this.forgetAppliedCommand(command));
             }
             return;
         }
@@ -896,7 +962,7 @@ class Harness {
                  * 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);
+                this.forgetAppliedCommand(command);
                 log('Answer arrived for a session this runner is no longer running', {
                     sessionId: command.sessionId,
                     commandId: command.commandId
@@ -964,6 +1030,16 @@ class Harness {
             });
         }
     }
+    /** Deliver commands received while the leased runner was still starting. */
+    flushDeferredSteers(sessionId, leaseId) {
+        for (const [commandId, command] of this.deferredSteers) {
+            if (command.sessionId !== sessionId)
+                continue;
+            this.deferredSteers.delete(commandId);
+            if (command.leaseId === leaseId)
+                this.applyCommandsSafely([command]);
+        }
+    }
     async releaseSessionWorkspace(sessionId) {
         try {
             const released = await this.workspace.release(sessionId, { force: true });
@@ -993,7 +1069,7 @@ class Harness {
      *    backend.
      */
     recoverFailedAnswer(runner, command, reason) {
-        this.appliedCommands.delete(command.commandId);
+        this.forgetAppliedCommand(command);
         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.
@@ -1230,15 +1306,14 @@ class Harness {
          */
         const renewalCallbacks = {
             leaseId: lease.leaseId,
+            // A running turn does not poll the lease endpoint. Ingest returns
+            // commands at each output boundary; a silent tool relies on heartbeat
+            // or this normal renewal interval, which can take up to a minute.
             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);
-                }
-            },
+            onCommands: (commands) => this.applyCommandsSafely(commands),
             githubTokenExpiresAt: lease.githubCredential?.expiresAt,
             onGithubCredential: (credential) => {
                 githubWorkspace.setCredential?.(sessionId, credential);
@@ -1395,7 +1470,9 @@ class Harness {
                 final,
                 modelMessages
             })
-                .then(() => undefined)
+                .then((response) => {
+                this.applyCommandsSafely(response.sessionCommands ?? []);
+            })
         });
         runnerRef = runner;
         // Registered BEFORE the turn starts. A permission can be raised on the
@@ -1404,6 +1481,8 @@ class Harness {
         // running" — which is indistinguishable, in the log, from a real
         // mis-routing.
         this.runners.set(sessionId, runner);
+        this.activeLeaseIds.set(sessionId, lease.leaseId);
+        this.flushDeferredSteers(sessionId, lease.leaseId);
         try {
             const result = await runner.run(lease, controller.signal);
             log('Turn finished', {
@@ -1446,6 +1525,14 @@ class Harness {
             // that arrives during the commit must defer, never delete under Git.
             this.active.delete(sessionId);
             this.runners.delete(sessionId);
+            this.activeLeaseIds.delete(sessionId);
+            // The control plane expires lease-bound commands at turn end. Keep IDs
+            // only while their lease can redeliver them; a warm runner serves many turns.
+            this.clearAppliedCommandsForSession(sessionId);
+            for (const [commandId, command] of this.deferredSteers) {
+                if (command.sessionId === sessionId)
+                    this.deferredSteers.delete(commandId);
+            }
             // Revoke ONLY this session's tokens. A process-wide revoke here blanked
             // the credential of every concurrent turn still running.
             this.tokens.revokeTargets(mcpTargetUrls);

package/dist/runtime/session-runner.d.ts

@@ -21,7 +21,7 @@
 import type { CodingAgentAdapter } from '../adapters';
 import { SessionModelGateway } from '../adapters/model-gateway';
 import { ArtifactInspector, ConversationStore, EventSink, ModelMessageRecord, Notifier, SecretProvider, Telemetry, TranscriptStore, WorkspaceProvider } from '../ports';
-import { LeaseResponse, ModelMessageInput, TranscriptPartInput, TurnMetadata } from '../types';
+import { LeaseResponse, LeasedTurnInput, ModelMessageInput, TranscriptPartInput, TurnMetadata } from '../types';
 import { KnowledgeToolHost, type KnowledgeControl } from './knowledge-tools';
 import { McpAuthProxy } from './mcp-auth-proxy';
 export interface SessionRunnerDeps {
@@ -260,6 +260,25 @@ export declare class SessionRunner {
      * three are what `answerPendingApproval` needs and cannot otherwise reach.
      */
     private turnContext;
+    private readonly pendingSteers;
+    private readonly deferredSteers;
+    private steerDispatchChain;
+    private nextSteerOrder;
+    private steeredPrompts;
+    private readonly steerEchoes;
+    private steerTurnGeneration;
+    private steerAcknowledgementsClosed;
+    private waitForSteerAcknowledgements;
+    /** A command can arrive on heartbeat or renewal while run() is in drain(). */
+    steerMessage(command: {
+        sessionId: string;
+        turnId: string;
+        input: LeasedTurnInput;
+        acknowledge: (consumed: boolean) => Promise<'steered' | 'queued'>;
+    }): void;
+    private rejectLateSteer;
+    private forgetSteerEcho;
+    private consumesSteerEcho;
     /** The approval currently shown to the user, if any. */
     private openApproval;
     /** The transcript identity of an ordinary agent question, if one is open. */
@@ -325,6 +344,7 @@ export declare class SessionRunner {
      * from the echoed text must not slip past the prefix check on that alone.
      */
     private isEchoOfTurnPrompt;
+    private isExactSteerEcho;
     /**
      * Poll the adapter until the turn goes quiet or the signal aborts.
      *

package/dist/runtime/session-runner.js

@@ -37,6 +37,8 @@ const knowledge_tools_1 = require("./knowledge-tools");
 const permission_mode_1 = require("./permission-mode");
 const projection_1 = require("./projection");
 const space_files_1 = require("./space-files");
+/** A missing Pi consumption event must not hold the lease open for its full RPC timeout. */
+const FINAL_STEER_ACK_WAIT_MS = 5_000;
 /** How often the runner asks the adapter for new output when nothing pushes. */
 const POLL_INTERVAL_MS = 2_000;
 /**
@@ -382,6 +384,150 @@ class SessionRunner {
      * three are what `answerPendingApproval` needs and cannot otherwise reach.
      */
     turnContext = null;
+    pendingSteers = new Set();
+    deferredSteers = [];
+    steerDispatchChain = Promise.resolve();
+    nextSteerOrder = 0;
+    steeredPrompts = [];
+    steerEchoes = new Map();
+    steerTurnGeneration = 0;
+    steerAcknowledgementsClosed = false;
+    async waitForSteerAcknowledgements() {
+        const pending = [...this.pendingSteers];
+        if (pending.length === 0) {
+            this.steerAcknowledgementsClosed = true;
+            return;
+        }
+        let timeout;
+        try {
+            const settled = await Promise.race([
+                Promise.allSettled(pending).then(() => true),
+                new Promise((resolve) => {
+                    timeout = setTimeout(() => resolve(false), FINAL_STEER_ACK_WAIT_MS);
+                })
+            ]);
+            if (!settled) {
+                // Final ingest releases the lease and requeues every steer that has
+                // not been acknowledged. A late acknowledgement cannot claim it.
+                this.logger.warn(`[SessionRunner] steer-final-wait-timeout session=${this.turnContext?.sessionId ?? 'unknown'} pending=${pending.length}`);
+            }
+        }
+        finally {
+            this.steerAcknowledgementsClosed = true;
+            if (timeout)
+                clearTimeout(timeout);
+        }
+    }
+    /** A command can arrive on heartbeat or renewal while run() is in drain(). */
+    steerMessage(command) {
+        const context = this.turnContext;
+        if (!context) {
+            if (this.steerAcknowledgementsClosed) {
+                this.rejectLateSteer(command);
+            }
+            else {
+                this.deferredSteers.push(command);
+            }
+            return;
+        }
+        if (context.sessionId !== command.sessionId ||
+            !context.adapter.steerUserMessage) {
+            this.rejectLateSteer(command);
+            return;
+        }
+        if (this.steerAcknowledgementsClosed) {
+            this.rejectLateSteer(command);
+            return;
+        }
+        const generation = this.steerTurnGeneration;
+        const order = this.nextSteerOrder++;
+        // Preparation (not Pi consumption) is serial. Fast sends enter Pi's queue
+        // in transcript order, so steeringMode=all can use all at one boundary.
+        const prepared = this.steerDispatchChain.then(async () => {
+            let prompt = command.input.content;
+            if (context.workspaceDir &&
+                (command.input.attachments?.length ||
+                    command.input.droppedAttachments?.length)) {
+                const sync = await (0, attachments_1.syncAttachmentsToWorkspace)(command.input.attachments, context.workspaceDir, {
+                    fetchImpl: this.deps.fetchAttachment,
+                    logger: this.logger,
+                    turnId: command.turnId
+                });
+                for (const dropped of command.input.droppedAttachments ?? []) {
+                    sync.failed.push({
+                        name: (0, attachments_1.sanitizeAttachmentName)(dropped.name),
+                        reason: dropped.reason
+                    });
+                }
+                const note = (0, attachments_1.attachmentPromptNote)(sync);
+                if (note)
+                    prompt = `${prompt}\n\n${note}`;
+            }
+            const seen = this.turnContext === context
+                ? context.adapter.steerUserMessage(context.backendSessionId, prompt, context.config)
+                : Promise.resolve(false);
+            // Pi can emit the user echo before the consumption acknowledgement
+            // returns. Filter that echo as soon as the prompt enters its queue.
+            const echoes = this.steerEchoes.get(prompt) ?? [];
+            echoes.push(command.turnId);
+            this.steerEchoes.set(prompt, echoes);
+            return { prompt, seen };
+        });
+        this.steerDispatchChain = prepared.then(() => undefined, () => undefined);
+        const task = prepared
+            .then(async ({ prompt, seen: consumed }) => {
+            const seen = await consumed;
+            if (!seen ||
+                this.steerAcknowledgementsClosed ||
+                generation !== this.steerTurnGeneration) {
+                if (!seen)
+                    this.logger.warn(`[SessionRunner] steer unconfirmed; queued for next turn (session=${command.sessionId}, turn=${command.turnId})`);
+                this.forgetSteerEcho(prompt, command.turnId);
+                // Pi rejected the steer, or its queue did not consume it. Reset the
+                // durable message now; release remains the fallback if this fails.
+                await command.acknowledge(false);
+                return;
+            }
+            // Record Pi's consumption before the network ack. If the ack hangs,
+            // final ingest must still log what Pi saw in this turn. A queued
+            // fallback can replay that text under the at-least-once crash rule.
+            this.steeredPrompts.push({ order, text: prompt });
+            await command.acknowledge(true);
+        })
+            .catch((error) => {
+            this.logger.warn(`[SessionRunner] steer failed for ${command.sessionId}: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        this.pendingSteers.add(task);
+        void task.finally(() => this.pendingSteers.delete(task));
+    }
+    rejectLateSteer(command) {
+        void command.acknowledge(false).catch((error) => {
+            this.logger.warn(`[SessionRunner] late steer reset failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    forgetSteerEcho(text, turnId) {
+        const echoes = this.steerEchoes.get(text);
+        if (!echoes)
+            return;
+        const index = echoes.indexOf(turnId);
+        if (index >= 0)
+            echoes.splice(index, 1);
+        if (echoes.length === 0)
+            this.steerEchoes.delete(text);
+    }
+    consumesSteerEcho(part) {
+        for (const [text, echoes] of this.steerEchoes) {
+            if (!this.isExactSteerEcho(part, text))
+                continue;
+            // Each matching user part consumes one steer, even when several steers
+            // have exactly the same text.
+            echoes.shift();
+            if (echoes.length === 0)
+                this.steerEchoes.delete(text);
+            return true;
+        }
+        return false;
+    }
     /** The approval currently shown to the user, if any. */
     openApproval = null;
     /** The transcript identity of an ordinary agent question, if one is open. */
@@ -439,10 +585,11 @@ class SessionRunner {
      */
     async run(lease, signal) {
         const { session } = lease;
-        const coldStart = new cold_start_steps_1.ColdStartSteps(session.sessionId, session.turnId, (line) => {
+        const logColdStart = (line) => {
             this.logger.log(line);
             this.deps.coldStartLog?.(line);
-        });
+        };
+        const coldStart = new cold_start_steps_1.ColdStartSteps(session.sessionId, session.turnId, logColdStart);
         const startedAt = new Date().toISOString();
         const release = this.deps.notifier.keepAwake();
         let workspaceDir = null;
@@ -469,6 +616,13 @@ class SessionRunner {
          */
         let turnContent = session.input.content;
         this.turnParts = [];
+        this.steerTurnGeneration++;
+        this.steerAcknowledgementsClosed = false;
+        this.pendingSteers.clear();
+        this.steeredPrompts = [];
+        this.steerDispatchChain = Promise.resolve();
+        this.nextSteerOrder = 0;
+        this.steerEchoes.clear();
         this.modelTokenExpiresAt = lease.modelTokenExpiresAt ?? null;
         this.modelKeyExpiryNoticeShown = false;
         try {
@@ -476,13 +630,21 @@ class SessionRunner {
             if (refusal)
                 throw new Error(refusal);
             // The catalogue is advisory. Fetch it while the independent workspace
-            // is prepared, then install it before the backend process starts.
+            // is prepared. Pi can start with the selected lease model while this
+            // request fills the cache for a later turn. OpenCode still waits for
+            // the reported limits before it builds its provider config.
             const endModels = coldStart.begin('model_catalogue');
+            let completedModels = null;
             const gatewayModels = session.agent.model.gatewayUrl
                 ? (0, model_gateway_1.fetchGatewayModels)({
                     baseUrl: session.agent.model.gatewayUrl,
                     apiKey: lease.modelToken
-                }).finally(endModels)
+                })
+                    .then((models) => {
+                    completedModels = models;
+                    return models;
+                })
+                    .finally(endModels)
                 : Promise.resolve([]);
             if (!session.agent.model.gatewayUrl)
                 endModels();
@@ -610,7 +772,25 @@ class SessionRunner {
                  * stop a turn whose model is already known, so we fall back to exactly
                  * the previous behaviour.
                  */
-                const fetched = await gatewayModels;
+                const useSelectedPiModel = session.agent.backend === 'pi' && !!session.agent.model.model;
+                // A Pi turn takes whichever catalogue result has arrived by now.
+                // This is deliberate: the selected model below is enough to start,
+                // while a later result fills the cache for the next turn.
+                if (useSelectedPiModel && completedModels === null) {
+                    try {
+                        logColdStart(JSON.stringify({
+                            event: 'model_catalogue_deferred',
+                            sessionId: session.sessionId,
+                            turnId: session.turnId
+                        }));
+                    }
+                    catch {
+                        // A diagnostic sink must never stop the turn.
+                    }
+                }
+                const fetched = useSelectedPiModel
+                    ? (completedModels ?? [])
+                    : await gatewayModels;
                 const named = session.agent.model.model
                     ? [
                         {
@@ -847,8 +1027,12 @@ class SessionRunner {
                 sessionId: session.sessionId,
                 backendSessionId,
                 adapter,
-                config
+                config,
+                workspaceDir
             };
+            for (const command of this.deferredSteers.splice(0)) {
+                this.steerMessage(command);
+            }
             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
@@ -946,6 +1130,7 @@ class SessionRunner {
              * turn happened to reset it.
              */
             this.turnContext = null;
+            this.deferredSteers.length = 0;
             this.closeApproval(session.sessionId);
             this.deps.knowledge?.host.bindTurn(session.sessionId, null);
             this.closeQuestion(session.sessionId);
@@ -1040,9 +1225,18 @@ class SessionRunner {
          * but a conversation that silently doubles in size every turn, which is the
          * kind of defect that looks fine for a week.
          */
+        // Give Pi a short time to confirm consumption. Final ingest requeues any
+        // unconfirmed steer; an absent event must not keep the lease alive.
+        await this.waitForSteerAcknowledgements();
         const spoken = (0, conversation_1.assistantTextFrom)(this.turnParts.filter((part) => !priorPartIdsForLog.has(part.partId)));
         const modelMessages = [
             { role: 'user', content: turnContent },
+            // This store keeps one assistant message per turn. Steers retain their
+            // order, but their exact interleaving with streamed assistant text is
+            // not represented in this compact replay log.
+            ...this.steeredPrompts
+                .sort((a, b) => a.order - b.order)
+                .map(({ text }) => ({ role: 'user', content: text })),
             ...(spoken ? [{ role: 'assistant', content: spoken }] : [])
         ];
         // Store locally FIRST, for the same reason parts are: the local copy is
@@ -1118,6 +1312,12 @@ class SessionRunner {
             return false;
         return sentPromptText.trim().startsWith(echoed);
     }
+    isExactSteerEcho(part, steeredPrompt) {
+        if (typeof part.role !== 'string' || part.role.toLowerCase() !== 'user')
+            return false;
+        const text = part.content ?? part.text;
+        return typeof text === 'string' && text.trim() === steeredPrompt.trim();
+    }
     /**
      * Poll the adapter until the turn goes quiet or the signal aborts.
      *
@@ -1269,7 +1469,11 @@ class SessionRunner {
                  * 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.filter((part) => {
+                        if (this.isEchoOfTurnPrompt(part, sentPromptText))
+                            return false;
+                        return !this.consumesSteerEcho(part);
+                    })
                     : parts;
                 /*
                  * WIRE 2: A PENDING PERMISSION BECOMES A TRANSCRIPT PART.

package/dist/types.d.ts

@@ -333,7 +333,7 @@ export interface SessionCommand {
      * 'abort' stops the turn; 'answer' resolves a pending question part;
      * 'release-workspace' removes a checkout after the session ends.
      */
-    command: 'abort' | 'answer' | 'release-workspace';
+    command: 'abort' | 'answer' | 'release-workspace' | 'steer';
     /** Set when command is 'answer' — the partId of the question being answered. */
     partId?: string;
     /** Set when command is 'answer' — the user's reply. */
@@ -350,6 +350,12 @@ export interface SessionCommand {
      * questions, and ids are none of those things.
      */
     optionId?: string;
+    /** A steer targets only this live lease. */
+    leaseId?: string;
+    /** The durable queued turn that becomes the fallback if steering fails. */
+    turnId?: string;
+    /** The message, with signed attachment URLs, from the control plane. */
+    input?: LeasedTurnInput;
     /** De-duplication key. The same commandId must be applied at most once. */
     commandId: string;
 }
@@ -788,6 +794,8 @@ export interface IngestResponse {
      * "the lease expired while it was working" bug.
      */
     leaseExpiresAt: string;
+    /** Commands collected at this model/tool boundary. Older APIs omit it. */
+    sessionCommands?: SessionCommand[];
 }
 export interface IngestRejection {
     partId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.5-rc.1",
+  "version": "0.2.5-rc.3",
   "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
   "license": "MIT",
   "type": "commonjs",