@kruntime/komputer 0.1.0

package/dist/agent-session.js

@@ -0,0 +1,3031 @@
+import { blocksToText, normalizeInput } from "./content.js";
+import { assertRuntimeEvent, EventLog } from "./events.js";
+import { KFileSystem } from "./vfs.js";
+import { VProcessTable } from "./vprocess.js";
+import { overlayMountTable } from "./drive.js";
+import { finishReceipt, makeReceipt } from "./receipts.js";
+import { normalizeKPath } from "./kstate.js";
+import { dirnamePath } from "./path.js";
+import { isExecutable } from "./fs-mode.js";
+import { id, normalizeBy, now, sleep } from "./utils.js";
+import { isGovernableShellScript, isSimpleShellCommand, parseShellCommandSegments, rewriteKPathsForRemote } from "./vbash.js";
+import { decideCommand, decideFs, decideModel, decideNetwork, decideTool, normalizeMode } from "./authority.js";
+import { K_BUILTINS } from "./shell/builtins/registry.js";
+import { builtinErrorText, runBuiltin } from "./shell/builtins/run.js";
+import { globMatcher } from "./shell/builtins/path.js";
+import { commandHelpText, commandResultToShellResult, isShellAssignmentToken, isShellIdentifier, parseShellRedirects, quoteShellWord, recordStringMap, shellArgsToInput, shellExitCode, shellWordToken } from "./shell/runtime.js";
+import { expandBraceFields, ShellExpander } from "./shell/expansion.js";
+import { parseShellControlProgram } from "./shell/control.js";
+import { parseShellFunctionProgram } from "./shell/functions.js";
+import { hardenShellSandboxRequest, validateShellSandboxRequest } from "./sandbox.js";
+import { SessionMessages } from "./agent/messages.js";
+import { SessionApprovals, normalizeApprovalDecision } from "./agent/approvals.js";
+import { sealInterruptedTurns, sealUnfinishedToolEvents, sealUnfinishedTools } from "./agent/recovery.js";
+import { abortedShellResult, defaultShellOptions, executableScriptBody, isModelResult, networkHostFromUrl, normalizeAssistantMessage, normalizeShellOptions, positionalShellEnv, recordField, resultType, signalReason, splitShellFields, stringArrayField, stringField, } from "./agent/session-utils.js";
+export { isFinalTurnEvent } from "./agent/session-utils.js";
+const MAX_K_LOCAL_CONTROL_ITERATIONS = 1000;
+const MAX_SHELL_CAPTURE_CHARS = 64 * 1024;
+const MAX_SHELL_OUTPUT_EVENT_CHARS = 16 * 1024;
+const SHELL_OUTPUT_EVENT_PREVIEW_CHARS = 4 * 1024;
+export class AgentSession {
+    runtime;
+    computer;
+    kstate;
+    agentName;
+    sessionId;
+    modeState;
+    mode;
+    disk;
+    definition;
+    home;
+    modelAlias;
+    system;
+    eventLog;
+    handlers;
+    hooks;
+    shellEnv;
+    shellEnvBase;
+    shellFunctions;
+    shellOptions;
+    messageLog;
+    approvalLog;
+    cwd;
+    fs;
+    localComputer;
+    vprocess;
+    shellExpander;
+    turnStopDepth;
+    maxTurnStopContinuations;
+    functionDepth;
+    sourceDepth;
+    fsActorStack;
+    lastExitCode;
+    closed;
+    initResult;
+    lease;
+    leaseHeartbeat;
+    constructor({ computer, agentName, sessionId, mode = 'normal', disk = 'shared' }) {
+        this.runtime = computer;
+        this.kstate = computer.kstate;
+        this.agentName = agentName;
+        this.sessionId = sessionId;
+        this.disk = disk;
+        this.definition = computer.image.agents?.[agentName] || {};
+        this.home = this.definition.home || `/home/${agentName}`;
+        this.modeState = this.normalizeModeForAgent(mode);
+        this.mode = this.modeState.name;
+        this.modelAlias = this.definition.model || 'default';
+        this.system = '';
+        this.eventLog = new EventLog(this.kstate, sessionId, agentName);
+        this.handlers = new Map();
+        this.hooks = new Map();
+        this.shellEnv = {};
+        this.shellEnvBase = undefined;
+        this.shellFunctions = {};
+        this.shellOptions = defaultShellOptions();
+        this.messageLog = new SessionMessages({
+            kstate: this.kstate,
+            sessionId,
+            isClosed: () => this.closed,
+            system: () => this.system,
+        });
+        this.approvalLog = new SessionApprovals(this.kstate, sessionId);
+        this.cwd = `${this.home}/work`;
+        this.fs = new KFileSystem(this.kstate, {
+            home: this.home,
+            sessionId,
+            mounts: disk === 'overlay' ? overlayMountTable(computer.kstate, sessionId, computer.mounts) : computer.mounts,
+            trace: (type, data) => this.traceFs(type, data),
+            by: () => this.currentFsActor(),
+            authorize: (request) => this.authorizeFs(request),
+        });
+        this.localComputer = {
+            fs: this.fs,
+            shell: {
+                cd: async (path) => {
+                    this.cwd = this.fs.path(path);
+                    await this.saveSession({ cwd: this.cwd });
+                },
+                path: {
+                    get: () => this.effectiveShellEnv().PATH,
+                    set: (value) => {
+                        this.shellEnv.PATH = value;
+                    },
+                    prepend: (path) => {
+                        this.shellEnv.PATH = updatePathList(this.effectiveShellEnv().PATH, this.fs.path(path), 'prepend');
+                    },
+                    append: (path) => {
+                        this.shellEnv.PATH = updatePathList(this.effectiveShellEnv().PATH, this.fs.path(path), 'append');
+                    },
+                },
+            },
+            env: {
+                get: (name) => {
+                    const env = this.effectiveShellEnv();
+                    return typeof name === 'string' ? env[name] : env;
+                },
+                set: (name, value) => {
+                    this.shellEnv[name] = value;
+                },
+                unset: (name) => {
+                    delete this.shellEnv[name];
+                },
+            },
+            exec: (command, options = {}) => this.execCommand(command, options),
+        };
+        this.computer = this.localComputer;
+        this.vprocess = new VProcessTable(this.kstate, sessionId, this.eventLog, computer.defaultRemote(), (name) => {
+            try {
+                return computer.getRemote(name);
+            }
+            catch {
+                return undefined;
+            }
+        }, (event) => this.emit(event));
+        this.shellExpander = new ShellExpander({
+            exec: (command) => this.withTemporaryShellState({}, () => this.execInternal(command, { by: 'system:shell-substitution' })),
+            getLastExitCode: () => this.lastExitCode,
+            setLastExitCode: (code) => { this.lastExitCode = code; },
+            getShellOptions: () => this.shellOptions,
+        });
+        this.turnStopDepth = 0;
+        this.maxTurnStopContinuations = 5;
+        this.functionDepth = 0;
+        this.sourceDepth = 0;
+        this.fsActorStack = [];
+        this.lastExitCode = 0;
+        this.closed = false;
+    }
+    async init() {
+        this.lease = await this.kstate.acquireSessionLease(this.sessionId, {
+            owner: `${this.runtime.workerId}:${this.agentName}`,
+            ttlMs: this.runtime.leaseTtlMs,
+        });
+        this.startLeaseHeartbeat();
+        await this.kstate.initSession(this.sessionId);
+        const existing = await this.kstate.readSession(this.sessionId);
+        this.initResult = { firstLogin: !existing, recovered: Boolean(existing) };
+        if (existing) {
+            if (existing.agent && existing.agent !== this.agentName) {
+                throw new Error(`session ${this.sessionId} belongs to agent ${existing.agent}, not ${this.agentName}`);
+            }
+            this.cwd = existing.cwd || this.cwd;
+            this.system = existing.system || this.system;
+            this.shellEnv = recordStringMap(existing.env);
+            const shellRecord = recordField(existing, 'shell') || {};
+            this.shellOptions = normalizeShellOptions(recordField(shellRecord, 'options'));
+            this.shellFunctions = recordStringMap(recordField(shellRecord, 'functions'));
+            this.lastExitCode = typeof existing.lastExitCode === 'number' ? existing.lastExitCode : this.lastExitCode;
+            this.modeState = this.normalizeModeForAgent(existing.mode || this.mode, existing.scope);
+            this.mode = this.modeState.name;
+        }
+        else {
+            await this.kstate.ensureRootDir(this.home);
+            await this.kstate.ensureRootDir(this.cwd);
+            await this.saveSession({
+                schema: 'k.session.v1',
+                id: this.sessionId,
+                agent: this.agentName,
+                home: this.home,
+                cwd: this.cwd,
+                env: this.shellEnv,
+                shell: this.shellSessionRecord(),
+                lastExitCode: this.lastExitCode,
+                mode: this.mode,
+                scope: this.modeState.scope,
+                model: this.modelAlias,
+                worker: {
+                    owner: this.lease.owner,
+                    token: this.lease.token,
+                    expiresAt: this.lease.expiresAt,
+                },
+                createdAt: now(),
+                status: 'ready',
+            });
+        }
+        const recoveryId = existing ? id('recovery') : undefined;
+        if (recoveryId)
+            await this.trace('recovery.start', { recoveryId, by: 'system:recovery' });
+        const recoveredProcesses = await this.vprocess.recover();
+        const recoveredReceipts = await this.reconcileRecoveredProcessReceipts(recoveredProcesses);
+        const sealedTools = await this.sealUnfinishedTools();
+        const sealedToolEvents = await this.sealUnfinishedToolEvents();
+        const sealedTurns = await this.sealInterruptedTurns();
+        if (recoveryId) {
+            const summary = { recoveryId, by: 'system:recovery', recoveredProcesses: recoveredProcesses.length, recoveredReceipts, sealedTools, sealedToolEvents, sealedTurns };
+            await this.trace('recovery.end', summary);
+            await this.signal('recovery.completed', summary);
+        }
+        return this;
+    }
+    async reconcileRecoveredProcessReceipts(processes) {
+        if (!processes.length)
+            return 0;
+        const receipts = await this.kstate.readSessionJsonl(this.sessionId, 'receipts.jsonl');
+        let reconciled = 0;
+        for (const process of processes) {
+            if (!process.receiptId || process.status === 'running')
+                continue;
+            const receipt = receipts.filter((item) => item.id === process.receiptId).at(-1);
+            if (!receipt || receipt.status !== 'uncertain')
+                continue;
+            const status = process.status === 'exited'
+                ? 'committed'
+                : process.status === 'failed'
+                    ? 'failed'
+                    : 'uncertain';
+            const error = status === 'committed'
+                ? undefined
+                : process.error || process.signal || (typeof process.exitCode === 'number' ? `exit ${process.exitCode}` : 'process outcome is uncertain after worker recovery; reconcile required');
+            const final = finishReceipt(receipt, {
+                status,
+                output: {
+                    vpid: process.vpid,
+                    jobId: process.jobId,
+                    status: process.status,
+                    exitCode: process.exitCode,
+                    signal: process.signal,
+                },
+                error,
+            });
+            await this.assertWritableSession();
+            await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', final);
+            await this.trace('receipt.finalized', {
+                receiptId: final.id,
+                kind: final.kind,
+                status,
+                code: process.exitCode,
+                signal: process.signal,
+                by: 'system:process-recovery',
+            });
+            reconciled += 1;
+        }
+        return reconciled;
+    }
+    async finalizeProcessReceiptFromWait(result) {
+        if (!result.recovered)
+            return;
+        if (!result.receiptId || result.status === 'running')
+            return;
+        const receipts = await this.kstate.readSessionJsonl(this.sessionId, 'receipts.jsonl');
+        const receipt = receipts.filter((item) => item.id === result.receiptId).at(-1);
+        if (!receipt || receipt.status !== 'uncertain')
+            return;
+        const status = result.status === 'exited'
+            ? 'committed'
+            : result.status === 'failed'
+                ? 'failed'
+                : 'uncertain';
+        const final = finishReceipt(receipt, {
+            status,
+            output: {
+                vpid: result.vpid,
+                jobId: result.jobId,
+                status: result.status,
+                exitCode: result.code,
+                signal: result.signal,
+            },
+            error: status === 'committed'
+                ? undefined
+                : result.stderr || result.signal || (typeof result.code === 'number' ? `exit ${result.code}` : 'process outcome is uncertain after wait'),
+        });
+        await this.assertWritableSession();
+        await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', final);
+        await this.trace('receipt.finalized', {
+            receiptId: final.id,
+            kind: final.kind,
+            status,
+            code: result.code,
+            signal: result.signal,
+            by: 'system:process-wait',
+        });
+    }
+    async saveSession(patch) {
+        await this.saveSessionUnchecked(patch, false);
+    }
+    async saveSessionUnchecked(patch, _leaseChecked) {
+        if (this.lease)
+            await this.assertActiveLease();
+        const current = await this.kstate.readSession(this.sessionId);
+        if (this.lease && current?.worker?.token && current.worker.token !== this.lease.token && !isExpiredWorker(current.worker)) {
+            throw new Error(`lease lost: ${this.sessionId}`);
+        }
+        const hasWorkerPatch = Object.prototype.hasOwnProperty.call(patch, 'worker');
+        const worker = hasWorkerPatch
+            ? patch.worker
+            : this.lease
+                ? { owner: this.lease.owner, token: this.lease.token, expiresAt: this.lease.expiresAt }
+                : current?.worker;
+        const next = { ...(current || {}), ...patch, updatedAt: now() };
+        if (worker)
+            next.worker = worker;
+        else
+            delete next.worker;
+        if (this.lease)
+            await this.assertActiveLease();
+        await this.kstate.writeSession(this.sessionId, next);
+    }
+    startLeaseHeartbeat() {
+        if (!this.runtime.leaseHeartbeat || this.leaseHeartbeat || !this.lease)
+            return;
+        const intervalMs = Math.max(10, Math.floor(this.runtime.leaseTtlMs / 3));
+        this.leaseHeartbeat = setInterval(() => {
+            this.renewLease().catch(() => {
+                this.closed = true;
+            });
+        }, intervalMs);
+        this.leaseHeartbeat.unref?.();
+    }
+    async renewLease() {
+        if (!this.lease || this.closed)
+            return;
+        await this.lease.renew(this.runtime.leaseTtlMs);
+        await this.saveSessionUnchecked({}, true);
+    }
+    async assertWritableSession() {
+        if (this.closed)
+            throw new Error(`session closed: ${this.sessionId}`);
+        await this.assertActiveLease();
+    }
+    async assertActiveLease() {
+        if (!this.lease)
+            return;
+        if (this.lease.assertActive) {
+            await this.lease.assertActive();
+            return;
+        }
+        await this.lease.renew(this.runtime.leaseTtlMs);
+    }
+    async canWriteWithCurrentLease() {
+        if (!this.lease)
+            return false;
+        try {
+            await this.assertActiveLease();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    normalizeModeForAgent(mode = 'normal', scope = undefined) {
+        const state = normalizeMode(mode, scope);
+        if (!state.scope?.fs?.length)
+            return state;
+        return {
+            ...state,
+            scope: {
+                ...state.scope,
+                fs: state.scope.fs.map((path) => normalizeKPath(path, this.home)),
+            },
+        };
+    }
+    async ready() {
+        await this.saveSession({ status: 'ready', system: this.system });
+    }
+    async authorizeFs(request) {
+        await this.assertWritableSession();
+        const before = await this.runHook('fs.before', request);
+        if (before.rejected) {
+            if (before.waitingApproval)
+                throw new Error(`waiting approval: ${String(before.approval?.id || '')}`);
+            throw new Error(before.reason || `fs ${request.op} rejected`);
+        }
+        const current = before.current;
+        const op = stringField(current, 'op');
+        const path = stringField(current, 'path');
+        const decision = decideFs({ mode: this.modeState, op, path });
+        if (!decision.ok)
+            throw new Error(decision.reason);
+        return current;
+    }
+    async trace(type, data = {}) {
+        await this.assertWritableSession();
+        const record = await this.kstate.appendTrace(this.sessionId, type, data);
+        await this.saveSessionUnchecked({ lastTraceSeq: record.traceSeq }, true);
+        return record;
+    }
+    async traceFs(type, data = {}) {
+        const record = await this.trace(type, data);
+        if (!isFsEffectTrace(type))
+            return record;
+        const by = normalizeBy(typeof data.by === 'string' ? data.by : this.currentFsActor());
+        const target = fsReceiptTarget(type, data);
+        const receipt = makeReceipt({
+            traceId: record.traceSeq,
+            sessionId: this.sessionId,
+            agent: this.agentName,
+            kind: type.replace(/^fs\./, 'vfs.'),
+            target,
+            summary: `${type.replace(/^fs\./, '')} ${target}`,
+            status: 'committed',
+            by,
+            input: fsReceiptInput(type, data),
+            output: { ok: true },
+        });
+        await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+        await this.trace('receipt.recorded', { receiptId: receipt.id, kind: receipt.kind, by, target });
+        return record;
+    }
+    currentFsActor() {
+        return normalizeBy(this.fsActorStack.at(-1));
+    }
+    async withFsActor(by, fn) {
+        this.fsActorStack.push(normalizeBy(by));
+        try {
+            return await fn();
+        }
+        finally {
+            this.fsActorStack.pop();
+        }
+    }
+    async emit(event) {
+        await this.assertWritableSession();
+        assertRuntimeEvent(event);
+        const boundedEvent = this.boundRuntimeEvent(event);
+        const envelope = await this.eventLog.emit(boundedEvent);
+        const handlers = this.handlers.get(boundedEvent.type) || [];
+        for (const handler of handlers) {
+            try {
+                await handler(boundedEvent, envelope);
+            }
+            catch (error) {
+                await this.trace('event.handler.error', {
+                    event: boundedEvent.type,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return envelope;
+    }
+    events(options = {}) {
+        return this.eventLog.events({ ...options, until: () => this.closed });
+    }
+    on(type, handler) {
+        if (!this.handlers.has(type))
+            this.handlers.set(type, []);
+        const handlers = this.handlers.get(type);
+        if (!handlers)
+            throw new Error(`handler list not initialized for ${type}`);
+        handlers.push(handler);
+        return () => {
+            const list = this.handlers.get(type) || [];
+            this.handlers.set(type, list.filter((item) => item !== handler));
+        };
+    }
+    hook(type, handler) {
+        if (!this.hooks.has(type))
+            this.hooks.set(type, []);
+        const hooks = this.hooks.get(type);
+        if (!hooks)
+            throw new Error(`hook list not initialized for ${type}`);
+        hooks.push(handler);
+        return () => {
+            const list = this.hooks.get(type) || [];
+            this.hooks.set(type, list.filter((item) => item !== handler));
+        };
+    }
+    hasHooks(type) {
+        return Boolean(this.hooks.get(type)?.length);
+    }
+    async runHook(type, current) {
+        let value = current;
+        const hooks = this.hooks.get(type) || [];
+        for (const handler of hooks) {
+            const ctx = this.hookContext(type, value);
+            const result = await handler(ctx);
+            const decision = result || ctx.decision || { type: 'pass' };
+            if (decision.type === 'update') {
+                value = { ...value, ...decision.patch };
+                continue;
+            }
+            if (decision.type === 'reject') {
+                return { rejected: true, reason: decision.reason, current: value };
+            }
+            if (decision.type === 'ask') {
+                const remembered = await this.approvalLog.forAction(type, value);
+                if (remembered?.status === 'allowed') {
+                    await this.consumeApproval(remembered);
+                    continue;
+                }
+                if (remembered?.status === 'pending') {
+                    await this.emitApprovalRequest(remembered);
+                    return { rejected: true, waitingApproval: true, approval: remembered, current: value };
+                }
+                const approval = await this.approvalLog.create(type, value, decision.request);
+                await this.emitApprovalRequest(approval);
+                return { rejected: true, waitingApproval: true, approval, current: value };
+            }
+        }
+        return { rejected: false, current: value };
+    }
+    hookContext(type, current) {
+        return {
+            type,
+            agent: this,
+            ctx: this.runtime.runtimeContext(this, { kind: 'hook', name: type, input: current, args: current }),
+            current,
+            data: current,
+            update: (patch) => ({ type: 'update', patch }),
+            reject: (reason) => ({ type: 'reject', reason }),
+            ask: (request) => ({ type: 'ask', request }),
+            emit: (name, data, options) => this.signal(name, data, options),
+        };
+    }
+    async signal(name, data = {}, options = {}) {
+        const level = options.level === 'warn' || options.level === 'error' ? options.level : 'info';
+        return this.emit({ type: 'signal', name, data, level });
+    }
+    async emitApprovalRequest(approval) {
+        const request = approval.request || {};
+        await this.emit({
+            type: 'approval',
+            status: 'requested',
+            approvalId: approval.id,
+            hook: approval.hook,
+            message: typeof request.message === 'string' ? request.message : 'Approval required',
+            risk: request.risk === 'low' || request.risk === 'medium' || request.risk === 'high' ? request.risk : undefined,
+            preview: request.preview,
+            current: approval.current,
+            approval,
+        });
+    }
+    async decide(approvalId, decision, options = {}) {
+        const approval = await this.approvalLog.byId(approvalId);
+        if (!approval)
+            throw new Error(`approval not found: ${approvalId}`);
+        const status = normalizeApprovalDecision(decision);
+        const row = {
+            id: approvalId,
+            status,
+            decision,
+            by: normalizeBy(options.by),
+            decidedAt: now(),
+        };
+        await this.approvalLog.append(row);
+        await this.trace('approval.decided', row);
+        await this.emit({
+            type: 'approval',
+            status: 'resolved',
+            approvalId,
+            hook: approval.hook,
+            decision: status === 'allowed' ? 'approved' : 'rejected',
+            approval,
+        });
+        if (status === 'rejected')
+            return row;
+        const result = await this.resumeApproval({ ...approval, status });
+        const done = { ...row, result };
+        await this.approvalLog.resumed(approvalId, result);
+        return done;
+    }
+    async consumeApproval(approval) {
+        await this.approvalLog.consume(approval);
+        await this.trace('approval.consumed', {
+            id: approval.id,
+            hook: approval.hook,
+            actionKey: approval.actionKey,
+        });
+    }
+    async resumeApproval(approval) {
+        const hook = approval.hook;
+        const current = approval.current || {};
+        await this.trace('approval.resume', { id: approval.id, hook });
+        if (hook === 'send.before') {
+            return this.send(current.content, recordField(current, 'options') || {});
+        }
+        if (hook === 'shell.before' || hook === 'cmd.before') {
+            return this.execInternal(stringField(current, 'shellScript') || stringField(current, 'script'), {
+                by: stringField(current, 'by') || `approval:${approval.id}`,
+                foreground: typeof current.foreground === 'boolean' ? current.foreground : undefined,
+            });
+        }
+        if (hook === 'tool.before') {
+            return this.command(stringField(current, 'command'), recordField(current, 'input') || {}, {
+                by: stringField(current, 'by') || `approval:${approval.id}`,
+            });
+        }
+        if (hook === 'tool.after') {
+            await this.trace('tool.ended', { name: current.command, resultType: resultType(current.result), approvedBy: approval.id });
+            await this.emit({ type: 'tool', status: 'completed', tool: String(current.tool || 'tool'), result: current.result, approvalId: approval.id });
+            return current.result;
+        }
+        if (hook === 'fs.before') {
+            return this.resumeFsApproval(current);
+        }
+        if (hook === 'model.before') {
+            return this.nextTurn({ inputId: stringField(current, 'inputId'), model: stringField(current, 'model') || undefined });
+        }
+        if (hook === 'model.after') {
+            const result = isModelResult(current.result) ? current.result : current;
+            return this.publishModelResult({
+                turnId: stringField(current, 'turnId') || id('turn'),
+                inputId: stringField(current, 'inputId') || undefined,
+                model: stringField(current, 'model') || this.modelAlias,
+                result,
+            });
+        }
+        if (hook === 'turn.stop') {
+            await this.trace('turn.closed', current);
+            const inputId = stringField(current, 'inputId');
+            if (inputId) {
+                await this.recordInput({
+                    inputId,
+                    turnId: stringField(current, 'turnId'),
+                    status: stringField(current, 'status') || 'completed',
+                    completedAt: now(),
+                    reason: current.reason,
+                });
+            }
+            await this.emit({ type: 'turn', ...current, status: turnStatus(current.status), turnId: stringField(current, 'turnId') || id('turn'), approvalId: approval.id });
+            return current;
+        }
+        throw new Error(`approval hook is not resumable: ${hook}`);
+    }
+    async resumeFsApproval(current) {
+        const op = stringField(current, 'op');
+        const path = stringField(current, 'path');
+        if (op === 'write') {
+            await this.fs.writeText(path, stringField(current, 'text'));
+            return { status: 'committed', op, path };
+        }
+        if (op === 'append') {
+            await this.fs.appendText(path, stringField(current, 'text'));
+            return { status: 'committed', op, path };
+        }
+        if (op === 'mkdir') {
+            await this.fs.mkdir(path);
+            return { status: 'committed', op, path };
+        }
+        if (op === 'rm') {
+            const options = recordField(current, 'options');
+            await this.fs.rm(path, options || {});
+            return { status: 'committed', op, path };
+        }
+        if (op === 'rename') {
+            await this.fs.rename(path, stringField(current, 'to'));
+            return { status: 'committed', op, path, to: stringField(current, 'to') };
+        }
+        throw new Error(`fs approval cannot resume unknown op: ${op}`);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.vprocess.detachActive();
+        try {
+            if (await this.canWriteWithCurrentLease()) {
+                await this.saveSessionUnchecked({ status: 'closed' }, true);
+                await this.signal('session.closed', { sessionId: this.sessionId, agent: this.agentName });
+                await this.saveSessionUnchecked({ worker: undefined }, true);
+            }
+        }
+        catch {
+            // Close is local cleanup first. A lost or expired lease must not keep
+            // event/message waiters, heartbeats, or process handles alive.
+        }
+        finally {
+            this.closed = true;
+            this.eventLog.wake();
+            this.messageLog.wake();
+            await this.releaseLease();
+            this.clearRuntimeHandles();
+        }
+    }
+    async detach() {
+        if (this.closed)
+            return;
+        this.vprocess.detachActive();
+        try {
+            if (await this.canWriteWithCurrentLease()) {
+                await this.trace('session.detached', { sessionId: this.sessionId, agent: this.agentName });
+                await this.signal('session.detached', { sessionId: this.sessionId, agent: this.agentName });
+                await this.saveSessionUnchecked({ worker: undefined }, true);
+            }
+        }
+        catch {
+            // Detach cannot be allowed to leak local runtime handles merely because
+            // the durable worker lease was already taken over.
+        }
+        finally {
+            this.closed = true;
+            this.eventLog.wake();
+            this.messageLog.wake();
+            await this.releaseLease();
+            this.clearRuntimeHandles();
+        }
+    }
+    /** @internal */
+    async abandonStartup() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.eventLog.wake();
+        this.messageLog.wake();
+        await this.releaseLease();
+        this.clearRuntimeHandles();
+    }
+    clearRuntimeHandles() {
+        this.handlers.clear();
+        this.hooks.clear();
+        this.eventLog.clear();
+        this.messageLog.clear();
+    }
+    async releaseLease() {
+        if (this.leaseHeartbeat) {
+            clearInterval(this.leaseHeartbeat);
+            this.leaseHeartbeat = undefined;
+        }
+        await this.lease?.release();
+        this.lease = undefined;
+    }
+    async send(input, options = {}) {
+        const by = normalizeBy(options.by);
+        const blocks = normalizeInput(input);
+        const before = await this.runHook('send.before', { content: blocks, by, options });
+        if (before.rejected) {
+            await this.trace('message.rejected', { by, reason: before.reason, hook: 'send.before' });
+            if (!before.waitingApproval) {
+                await this.emit({
+                    type: 'message',
+                    status: 'rejected',
+                    messageId: id('message'),
+                    role: 'user',
+                    by,
+                    reason: before.reason,
+                    content: blocks,
+                });
+            }
+            return { status: before.waitingApproval ? 'waiting_approval' : 'rejected', approval: before.approval, reason: before.reason };
+        }
+        const inputId = id('input');
+        const content = Array.isArray(before.current.content) ? before.current.content : blocks;
+        const message = await this.appendMessage({ role: 'user', content, by, inputId });
+        const record = { inputId, messageId: message.id, by, content, status: 'queued', queuedAt: now() };
+        await this.recordInput(record);
+        await this.trace('message.appended', { inputId, by, content });
+        await this.emit({ type: 'message', status: 'appended', messageId: String(message.id), role: 'user', by, content });
+        return { status: 'queued', inputId, messageId: message.id, by };
+    }
+    async run(input, options = {}) {
+        const sent = await this.send(input, options);
+        if (sent.status !== 'queued')
+            return { status: sent.status, text: '', reason: sent.reason, approval: sent.approval };
+        return this.nextTurn({ inputId: stringField(sent, 'inputId'), model: options.model });
+    }
+    async queue(inputs, options = {}) {
+        const results = [];
+        for (const input of inputs) {
+            results.push(await this.run(input, options));
+        }
+        return results;
+    }
+    async upload(path, data, options = {}) {
+        const text = typeof data === 'string'
+            ? data
+            : data instanceof Uint8Array
+                ? new TextDecoder().decode(data)
+                : JSON.stringify(data, null, 2);
+        await this.fs.writeFile(path, text);
+        const kPath = this.fs.path(path);
+        const bytes = new TextEncoder().encode(text).byteLength;
+        const record = { path: kPath, bytes, by: normalizeBy(options.by), at: now() };
+        await this.trace('file.uploaded', record);
+        if (options.announce) {
+            await this.send(`Uploaded ${kPath}`, { by: options.by || 'program:upload' });
+        }
+        return record;
+    }
+    async download(path, _options = {}) {
+        const text = await this.fs.readText(path);
+        const kPath = this.fs.path(path);
+        const bytes = new TextEncoder().encode(text).byteLength;
+        await this.trace('file.downloaded', { path: kPath, bytes });
+        return { path: kPath, text, bytes };
+    }
+    async nextTurn({ inputId, model } = {}) {
+        inputId = inputId || await this.nextQueuedInputId();
+        const turnId = id('turn');
+        if (inputId)
+            await this.recordInput({ inputId, status: 'running', turnId, startedAt: now() });
+        await this.trace('turn.opened', { turnId, inputId });
+        await this.emit({ type: 'turn', status: 'running', turnId });
+        let modelReq = {
+            turnId,
+            inputId,
+            model: model || this.modelAlias,
+            messages: await this.messagesForModel(),
+            mode: this.mode,
+        };
+        const before = await this.runHook('model.before', modelReq);
+        if (before.rejected) {
+            return this.endTurn({
+                turnId,
+                inputId,
+                status: before.waitingApproval ? 'waiting_approval' : 'blocked',
+                reason: before.reason || (before.waitingApproval ? 'waiting approval' : undefined),
+            });
+        }
+        modelReq = before.current;
+        const modelAuthority = decideModel({ mode: this.modeState, model: modelReq.model || 'default' });
+        if (!modelAuthority.ok) {
+            await this.trace('model.rejected', { turnId, inputId, model: modelReq.model, reason: modelAuthority.reason, mode: this.mode });
+            return this.endTurn({ turnId, inputId, status: 'blocked', reason: modelAuthority.reason });
+        }
+        const llm = this.runtime.models.get(modelReq.model || 'default');
+        const modelTrace = await this.trace('model.request', {
+            turnId,
+            inputId,
+            model: modelReq.model,
+            messageCount: modelReq.messages.length,
+        });
+        let result;
+        let contentAlreadyEmitted = false;
+        try {
+            if (llm.stream) {
+                const streamed = await this.consumeModelStream(llm.stream(modelReq), {
+                    turnId,
+                    inputId,
+                    emit: !this.hasHooks('model.after'),
+                });
+                result = streamed.result;
+                contentAlreadyEmitted = streamed.emitted;
+            }
+            else {
+                result = await llm.complete(modelReq);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            await this.trace('model.error', { turnId, inputId, message });
+            return this.endTurn({ turnId, inputId, status: 'failed', reason: message });
+        }
+        const after = await this.runHook('model.after', { result, model: modelReq.model, turnId, inputId });
+        if (after.rejected) {
+            return this.endTurn({
+                turnId,
+                inputId,
+                status: after.waitingApproval ? 'waiting_approval' : 'blocked',
+                reason: after.reason || (after.waitingApproval ? 'waiting approval' : undefined),
+            });
+        }
+        result = isModelResult(after.current.result) ? after.current.result : after.current;
+        return this.publishModelResult({ turnId, inputId, model: modelReq.model, modelTraceSeq: modelTrace.traceSeq, result, emitContent: !contentAlreadyEmitted });
+    }
+    async consumeModelStream(stream, { turnId, inputId, emit, }) {
+        const content = [];
+        let text = '';
+        let doneMessage;
+        let usage;
+        let finishReason;
+        let provider;
+        let emitted = false;
+        for await (const event of stream) {
+            if (event.type === 'content') {
+                content.push(event.content);
+                if (event.text)
+                    text += event.text;
+                else if (event.content.type === 'text' && event.content.text)
+                    text += event.content.text;
+                if (emit) {
+                    await this.emit({ type: 'content', kind: contentKind(event.content), content: event.content, text: event.text ?? event.content.text, ref: event.content.ref, path: event.content.path, turnId });
+                    emitted = true;
+                }
+            }
+            else if (event.type === 'tool') {
+                const block = {
+                    type: 'tool_use',
+                    id: event.toolUseId || id('tool'),
+                    name: event.tool,
+                    input: event.input,
+                };
+                content.push(block);
+                if (emit) {
+                    await this.emit({ type: 'tool', status: 'requested', tool: event.tool, input: event.input, opId: block.id, turnId });
+                    emitted = true;
+                }
+            }
+            else if (event.type === 'message') {
+                doneMessage = event.message;
+                usage = event.usage;
+                finishReason = event.finishReason;
+                provider = event.provider;
+            }
+            else if (event.type === 'error') {
+                throw event.error instanceof Error ? event.error : new Error(String(event.error));
+            }
+            else {
+                await this.trace('provider', { turnId, inputId, event });
+            }
+        }
+        const message = doneMessage || { role: 'assistant', content };
+        return {
+            emitted,
+            result: {
+                text: text || blocksToText(message.content || []),
+                message,
+                usage,
+                finishReason,
+                provider,
+            },
+        };
+    }
+    async publishModelResult({ turnId, inputId, model, modelTraceSeq, result, emitContent = true, }) {
+        const message = normalizeAssistantMessage(result);
+        const provider = modelProviderSummary(result.provider);
+        await this.appendMessage({ ...message, by: `model:${model || this.modelAlias}`, inputId, turnId });
+        await this.trace('model.output', {
+            turnId,
+            inputId,
+            modelTraceSeq,
+            text: result.text || blocksToText(message.content),
+            usage: result.usage,
+            provider,
+        });
+        let text = '';
+        for (const block of message.content || []) {
+            if (block.type === 'text') {
+                text += block.text ?? '';
+                if (emitContent)
+                    await this.emit({ type: 'content', kind: contentKind(block), content: block, text: block.text, ref: block.ref, path: block.path, turnId });
+            }
+            else if (block.type === 'tool_use') {
+                if (emitContent)
+                    await this.emit({ type: 'tool', status: 'requested', tool: String(block.name || 'tool'), input: block.input, opId: block.id, turnId });
+            }
+            else {
+                if (emitContent)
+                    await this.emit({ type: 'content', kind: contentKind(block), content: block, ref: block.ref, path: block.path, turnId });
+            }
+        }
+        const hasToolUse = (message.content || []).some((block) => block.type === 'tool_use');
+        if (hasToolUse) {
+            return this.endTurn({ turnId, inputId, status: 'blocked', text, reason: 'tool call pending', provider });
+        }
+        return this.endTurn({ turnId, inputId, status: 'completed', text, provider });
+    }
+    async endTurn({ turnId, inputId, status, text = '', reason = undefined, provider = undefined }) {
+        let payload = { turnId, inputId, status, text, reason, provider };
+        if (this.turnStopDepth >= this.maxTurnStopContinuations) {
+            const message = `turn.stop skipped after ${this.maxTurnStopContinuations} nested continuations to prevent recursive agent maintenance loops`;
+            await this.trace('turn.stop.skipped', { turnId, inputId, status, reason: message, maxContinuations: this.maxTurnStopContinuations });
+            await this.signal('turn.stop.max_continuations', {
+                turnId,
+                inputId,
+                status,
+                message,
+                maxContinuations: this.maxTurnStopContinuations,
+            }, { level: 'warn' });
+        }
+        else {
+            this.turnStopDepth += 1;
+            try {
+                const stop = await this.runHook('turn.stop', payload);
+                if (stop.rejected) {
+                    payload = {
+                        ...payload,
+                        ...stop.current,
+                        status: stop.waitingApproval ? 'waiting_approval' : 'blocked',
+                        reason: stop.reason || (stop.waitingApproval ? 'waiting approval' : 'turn.stop rejected finalization'),
+                    };
+                }
+                else {
+                    payload = { ...payload, ...stop.current };
+                }
+            }
+            finally {
+                this.turnStopDepth -= 1;
+            }
+        }
+        await this.trace('turn.closed', payload);
+        if (inputId) {
+            await this.recordInput({
+                inputId,
+                turnId,
+                status: stringField(payload, 'status') || 'completed',
+                completedAt: now(),
+                reason: payload.reason,
+            });
+        }
+        await this.emit({ type: 'turn', ...payload, status: turnStatus(payload.status), turnId });
+        return payload;
+    }
+    async recordInput(record) {
+        await this.assertWritableSession();
+        await this.kstate.appendSessionJsonl(this.sessionId, 'inputs.jsonl', record);
+    }
+    async nextQueuedInputId() {
+        const rows = await this.kstate.readSessionJsonl(this.sessionId, 'inputs.jsonl');
+        const latest = new Map();
+        for (const row of rows) {
+            const inputId = stringField(row, 'inputId');
+            if (inputId)
+                latest.set(inputId, row);
+        }
+        for (const row of latest.values()) {
+            if (row.status === 'queued')
+                return stringField(row, 'inputId');
+        }
+        return undefined;
+    }
+    stats() {
+        return {
+            sessionId: this.sessionId,
+            agent: this.agentName,
+            mode: this.mode,
+            disk: this.disk,
+            cwd: this.cwd,
+            closed: this.closed,
+            localEventHandlers: countHandlerMap(this.handlers),
+            localHooks: countHandlerMap(this.hooks),
+            localActiveProcesses: this.vprocess.localActiveProcessCount(),
+            shellFunctions: Object.keys(this.shellFunctions).length,
+        };
+    }
+    async exec(command, options = {}) {
+        const toolUseId = id('tool');
+        const by = normalizeBy(options.by);
+        const script = String(command);
+        const toolUseMessage = {
+            role: 'assistant',
+            by,
+            content: [{
+                    type: 'tool_use',
+                    id: toolUseId,
+                    name: 'shell',
+                    input: {
+                        script,
+                        cwd: this.cwd,
+                        foreground: options.foreground ?? !script.trimEnd().endsWith('&'),
+                    },
+                }],
+        };
+        try {
+            await this.emit({ type: 'tool', status: 'requested', tool: 'shell', input: toolUseMessage.content[0]?.input, opId: toolUseId });
+            const result = await this.execShell(command, options);
+            const bounded = this.boundShellResult(result);
+            await this.appendExecToolExchange(toolUseMessage, toolUseId, bounded, by);
+            await this.emit({ type: 'tool', status: bounded.code === 0 ? 'completed' : 'failed', tool: 'shell', result: bounded, opId: toolUseId });
+            return bounded;
+        }
+        catch (error) {
+            const result = {
+                status: 'failed',
+                code: 1,
+                stdout: '',
+                stderr: error instanceof Error ? error.message : String(error),
+            };
+            const bounded = this.boundShellResult(result);
+            await this.appendExecToolExchange(toolUseMessage, toolUseId, bounded, by);
+            await this.emit({ type: 'tool', status: 'failed', tool: 'shell', result: bounded, opId: toolUseId });
+            throw error;
+        }
+    }
+    async execInternal(command, options = {}) {
+        return this.boundShellResult(await this.execShell(command, options));
+    }
+    async execCommand(command, options = {}) {
+        if (typeof command === 'string')
+            return this.execInternal(command, options);
+        const remote = command.remote || options.remote;
+        const limits = command.limits || options.limits;
+        const stdin = command.stdin ?? options.stdin;
+        return this.execInternal([command.command, ...(command.argv || [])].filter(Boolean).map(quoteShellWord).join(' '), {
+            ...options,
+            stdin,
+            remote,
+            limits,
+            forceRemote: Boolean(remote),
+        });
+    }
+    async appendExecToolExchange(toolUseMessage, toolUseId, result, by) {
+        await this.assertWritableSession();
+        const code = typeof result.code === 'number' ? result.code : result.status === 'committed' ? 0 : 1;
+        const bounded = this.boundShellResult(result);
+        const stdout = typeof bounded.stdout === 'string' ? bounded.stdout : '';
+        const stderr = typeof bounded.stderr === 'string' ? bounded.stderr : '';
+        await this.messageLog.appendMany([
+            toolUseMessage,
+            {
+                role: 'tool',
+                by,
+                content: [{
+                        type: 'tool_result',
+                        toolUseId,
+                        name: 'shell',
+                        ok: code === 0 && result.status !== 'failed' && result.status !== 'rejected',
+                        status: typeof result.status === 'string' ? result.status : code === 0 ? 'committed' : 'failed',
+                        text: stdout || stderr,
+                        stdout,
+                        stderr,
+                        code,
+                        truncated: bounded.truncated === true ? true : undefined,
+                        stdoutTruncated: bounded.stdoutTruncated === true ? true : undefined,
+                        stderrTruncated: bounded.stderrTruncated === true ? true : undefined,
+                        stdoutOriginalChars: typeof bounded.stdoutOriginalChars === 'number' ? bounded.stdoutOriginalChars : undefined,
+                        stderrOriginalChars: typeof bounded.stderrOriginalChars === 'number' ? bounded.stderrOriginalChars : undefined,
+                        receiptId: recordField(bounded, 'receipt')?.id,
+                    }],
+            },
+        ]);
+    }
+    async execShell(command, options = {}) {
+        const aborted = abortedShellResult(options.signal);
+        if (aborted)
+            return aborted;
+        const shell = String(command);
+        const foreground = options.foreground ?? !shell.trimEnd().endsWith('&');
+        let script = foreground ? shell : shell.trimEnd().replace(/&\s*$/, '');
+        const beforeShell = await this.runHook('shell.before', { script, cwd: this.hookCwd(), by: normalizeBy(options.by) });
+        if (beforeShell.rejected) {
+            await this.trace('process.rejected', { script, reason: beforeShell.reason });
+            if (beforeShell.waitingApproval) {
+                return { status: 'waiting_approval', code: undefined, stdout: '', stderr: '', approval: beforeShell.approval, reason: beforeShell.reason };
+            }
+            return { status: 'rejected', code: 126, stdout: '', stderr: String(beforeShell.reason || 'rejected') };
+        }
+        script = stringField(beforeShell.current, 'script');
+        const functionProgram = parseShellFunctionProgram(script);
+        if (functionProgram) {
+            return this.rememberExit(await this.execKLocalFunctionProgram(functionProgram, { by: options.by, signal: options.signal }));
+        }
+        const control = parseShellControlProgram(script);
+        if (control) {
+            return this.rememberExit(await this.execKLocalControlProgram(control, { by: options.by, signal: options.signal }));
+        }
+        const redirect = parseShellRedirects(script);
+        const governedScript = redirect?.script || script;
+        if (this.mode !== 'normal' && !isGovernableShellScript(governedScript)) {
+            const reason = `${this.mode} mode denies shell syntax that K cannot govern safely`;
+            await this.trace('process.rejected', { script, reason, mode: this.mode });
+            return { status: 'rejected', code: 126, stdout: '', stderr: reason };
+        }
+        const parsed = parseShellCommandSegments(governedScript).map((segment) => this.normalizeShellSegment(segment));
+        const segmentRedirects = [];
+        for (let index = 0; index < parsed.length; index += 1) {
+            const segmentRedirect = parseShellRedirects(parsed[index].script);
+            if (!segmentRedirect)
+                continue;
+            const stripped = parseShellCommandSegments(segmentRedirect.script)[0];
+            if (!stripped)
+                continue;
+            parsed[index] = this.normalizeShellSegment({ ...stripped, separator: parsed[index].separator, background: parsed[index].background });
+            segmentRedirects[index] = segmentRedirect;
+        }
+        for (let index = 0; index < parsed.length; index += 1) {
+            const concrete = parsed[index];
+            if (concrete.assignmentOnly)
+                continue;
+            const beforeCmd = await this.runHook('cmd.before', {
+                cmd: concrete.cmd,
+                args: concrete.args,
+                env: concrete.env,
+                script: concrete.script,
+                shellScript: script,
+                cwd: this.hookCwd(),
+                by: normalizeBy(options.by),
+                foreground: foreground && !concrete.background,
+                background: !foreground || concrete.background,
+            });
+            if (beforeCmd.rejected) {
+                await this.trace('process.rejected', { cmd: concrete.cmd, args: concrete.args, reason: beforeCmd.reason });
+                if (beforeCmd.waitingApproval) {
+                    return { status: 'waiting_approval', code: undefined, stdout: '', stderr: '', approval: beforeCmd.approval, reason: beforeCmd.reason };
+                }
+                return { status: 'rejected', code: 126, stdout: '', stderr: String(beforeCmd.reason || 'rejected') };
+            }
+            const currentCmd = stringField(beforeCmd.current, 'cmd') || concrete.cmd;
+            const currentArgs = stringArrayField(beforeCmd.current, 'args') || concrete.args;
+            const currentScript = stringField(beforeCmd.current, 'script') || concrete.script;
+            const words = [currentCmd, ...currentArgs];
+            const preservesTokens = currentCmd === concrete.cmd
+                && currentArgs.length === concrete.args.length
+                && currentArgs.every((arg, argIndex) => arg === concrete.args[argIndex]);
+            parsed[index] = {
+                ...concrete,
+                cmd: currentCmd,
+                args: currentArgs,
+                script: currentScript,
+                words,
+                wordTokens: preservesTokens ? concrete.wordTokens : words.map(shellWordToken),
+                background: concrete.background,
+            };
+            const authority = decideCommand({ mode: this.modeState, cmd: currentCmd });
+            if (!authority.ok) {
+                await this.trace('process.rejected', { cmd: currentCmd, args: currentArgs, reason: authority.reason, mode: this.mode });
+                return { status: 'rejected', code: 126, stdout: '', stderr: authority.reason };
+            }
+        }
+        const cmd = parsed[0]?.cmd || 'bash';
+        const args = parsed[0]?.args || [];
+        const env = parsed[0]?.env;
+        if (parsed.length === 1 && parsed[0]?.assignmentOnly) {
+            return this.rememberExit(await this.execKLocalSequence(parsed, { by: options.by, redirects: segmentRedirects, foreground, signal: options.signal }));
+        }
+        if (!options.forceRemote && foreground && parsed.length === 1 && redirect && (K_BUILTINS.has(cmd)
+            || this.runtime.commands.has(cmd)
+            || this.shellFunctions[cmd] !== undefined
+            || await this.resolveKExecutable(cmd, env))) {
+            return this.rememberExit(await this.execKLocalSequence(parsed, { by: options.by, redirects: [redirect], foreground, signal: options.signal }));
+        }
+        if (!options.forceRemote && !foreground && await this.isKLocalSequence(parsed)) {
+            return this.rememberExit(await this.execBackgroundKLocalSequence(governedScript, parsed, {
+                by: options.by,
+                redirects: segmentRedirects,
+                signal: options.signal,
+            }));
+        }
+        if (!options.forceRemote && await this.isKLocalSequence(parsed)) {
+            return this.rememberExit(await this.execKLocalSequence(parsed, { by: options.by, redirects: segmentRedirects, foreground, signal: options.signal }));
+        }
+        if (!options.forceRemote && this.isKCommandInvocation(governedScript, parsed)) {
+            return this.rememberExit(await this.applyRedirect(await this.execKCommandFromShell({ cmd, args, argTokens: parsed[0]?.wordTokens.slice(1), script: governedScript, foreground, by: options.by, env }), redirect, options.by));
+        }
+        if (!options.forceRemote && this.isKBuiltinInvocation(governedScript, parsed)) {
+            return this.rememberExit(await this.applyRedirect(await this.execKBuiltinFromShell({ cmd, args, argTokens: parsed[0]?.wordTokens.slice(1), script: governedScript, foreground, by: options.by, env, signal: options.signal }), redirect, options.by));
+        }
+        if (parsed.length === 1 && parsed[0]?.cmd === 'return') {
+            return this.rememberExit(await this.applyRedirect(await this.execKLocalSequence(parsed, { by: options.by, redirects: segmentRedirects, foreground, signal: options.signal }), redirect, options.by));
+        }
+        if (!options.forceRemote && this.isKShellFunctionInvocation(governedScript, parsed)) {
+            return this.rememberExit(await this.applyRedirect(await this.execKShellFunctionFromShell({ cmd, args, argTokens: parsed[0]?.wordTokens.slice(1), script: governedScript, foreground, by: options.by, env, signal: options.signal }), redirect, options.by));
+        }
+        const executable = !options.forceRemote && parsed.length === 1 ? await this.resolveKExecutable(cmd, env) : undefined;
+        if (executable) {
+            return this.rememberExit(await this.applyRedirect(await this.execKExecutableFromShell({ path: executable, cmd, args, argTokens: parsed[0]?.wordTokens.slice(1), script: governedScript, foreground, by: options.by, env, signal: options.signal }), redirect, options.by));
+        }
+        const remote = options.remote ? this.runtime.getRemote(options.remote) : this.runtime.defaultRemote();
+        if (!remote.capabilities.shell) {
+            const reason = `remote ${remote.name} does not provide shell execution`;
+            await this.trace('process.unavailable', { script: shell, reason, remote: remote.name });
+            await this.emit({ type: 'process', status: 'failed', command: 'shell', argv: [], script: shell, code: 127, reason });
+            return { status: 'rejected', code: 127, stdout: '', stderr: reason };
+        }
+        let sandbox;
+        try {
+            sandbox = this.remoteShellSandbox(remote);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            await this.trace('process.rejected', { script, reason, mode: this.mode, remote: remote.name });
+            return { status: 'rejected', code: 126, stdout: '', stderr: reason };
+        }
+        if (this.mode !== 'normal' && !sandbox) {
+            const reason = `${this.mode} mode requires a remote shell with hard sandbox enforcement`;
+            await this.trace('process.rejected', { script, reason, mode: this.mode, remote: remote.name });
+            return { status: 'rejected', code: 126, stdout: '', stderr: reason };
+        }
+        const remoteRewrite = rewriteKPathsForRemote(script, (path) => {
+            const resolved = this.runtime.realPathInfo(path);
+            return resolved ? { kPath: normalizeKPath(path), realPath: resolved.realPath, mode: resolved.mode } : undefined;
+        }, this.home);
+        if (remoteRewrite.unresolved.length) {
+            const reason = `remote shell cannot access K paths without a real backing path: ${remoteRewrite.unresolved.join(', ')}`;
+            await this.trace('process.rejected', { script, reason, paths: remoteRewrite.unresolved, remote: remote.name });
+            return { status: 'rejected', code: 126, stdout: '', stderr: reason };
+        }
+        try {
+            sandbox = this.hardenReadonlyMountsForRemoteShell(remote, sandbox, remoteRewrite.resolved);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            await this.trace('process.rejected', { script, reason, mode: this.mode, remote: remote.name });
+            return { status: 'rejected', code: 126, stdout: '', stderr: reason };
+        }
+        const remoteScript = remoteRewrite.script;
+        await this.emit({ type: 'process', status: 'started', command: cmd, argv: args, script });
+        const trace = await this.trace('process.started', { cmd, args, script, remoteScript, foreground, sandbox });
+        let result;
+        const remoteCwd = this.remoteCwd();
+        if (!remoteCwd && this.kstate.realRootPath('/') !== undefined) {
+            result = {
+                vpid: id('vpid'),
+                jobId: id('job'),
+                background: false,
+                code: 1,
+                stdout: '',
+                stderr: `remote shell cwd without a real backing path: ${this.cwd}`,
+            };
+        }
+        else {
+            try {
+                result = await this.vprocess.spawnShell(remoteScript, { cwd: remoteCwd, env: this.effectiveShellEnv(options.env), stdin: options.stdin, foreground, remote, limits: options.limits, sandbox });
+            }
+            catch (error) {
+                result = {
+                    vpid: id('vpid'),
+                    jobId: id('job'),
+                    background: false,
+                    code: 1,
+                    stdout: '',
+                    stderr: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }
+        const status = result.background ? 'uncertain' : result.code === 0 ? 'committed' : 'failed';
+        const receipt = makeReceipt({
+            traceId: trace.traceSeq,
+            sessionId: this.sessionId,
+            agent: this.agentName,
+            kind: 'remote.exec',
+            target: `${remote.name}:${cmd || 'bash'}`,
+            summary: script,
+            status,
+            by: normalizeBy(options.by),
+            input: { remote: remote.name, script, sandbox, limits: options.limits },
+            output: this.boundShellReceiptOutput(result),
+            policy: sandbox ? { sandbox: { request: sandbox, attestation: result.sandbox } } : result.sandbox ? { sandbox: { attestation: result.sandbox } } : undefined,
+            error: result.code === 0 ? undefined : compactShellCaptureText(result.stderr || '').text,
+        });
+        await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+        if (result.background)
+            await this.trackBackgroundReceipt(result, receipt);
+        await this.trace('process.ended', { cmd, args, script, status, code: result.code, receiptId: receipt.id });
+        await this.emit({ type: 'process', status: processStatus(status, result.code), command: cmd, argv: args, script, code: result.code, receiptId: receipt.id });
+        return this.rememberExit({ status, receipt, ...result });
+    }
+    remoteShellSandbox(remote) {
+        if (this.mode === 'normal')
+            return undefined;
+        if (remote.capabilities.sandbox?.shell !== 'hard')
+            return undefined;
+        const scopedRealPaths = this.remoteRealPathsForScope(this.modeState.scope?.fs || []);
+        const request = hardenShellSandboxRequest({
+            mode: this.mode,
+            enforcement: 'hard',
+            readonly: this.mode === 'readonly' || this.mode === 'plan',
+            allowedPaths: scopedRealPaths.length ? scopedRealPaths : undefined,
+            allowWrite: this.mode === 'limited' ? scopedRealPaths : [],
+            allowedHosts: this.modeState.scope?.hosts ?? [],
+        });
+        request.denyWrite = this.remoteDenyWritePaths(request.denyWrite || []);
+        const errors = validateShellSandboxRequest(request);
+        if (errors.length)
+            throw new Error(`invalid remote shell sandbox request: ${errors.join('; ')}`);
+        return request;
+    }
+    hardenReadonlyMountsForRemoteShell(remote, sandbox, paths) {
+        const readonlyRealPaths = [...new Set(paths
+                .filter((path) => path.mode === 'ro')
+                .map((path) => path.realPath))];
+        if (!readonlyRealPaths.length)
+            return sandbox;
+        if (remote.capabilities.sandbox?.shell !== 'hard') {
+            throw new Error('remote shell cannot access ro K mounts without hard sandbox enforcement');
+        }
+        const request = hardenShellSandboxRequest({
+            ...(sandbox || { mode: this.mode, enforcement: 'hard' }),
+            denyWrite: [...(sandbox?.denyWrite || []), ...readonlyRealPaths],
+            allowRead: [...(sandbox?.allowRead || []), ...readonlyRealPaths],
+        });
+        const errors = validateShellSandboxRequest(request);
+        if (errors.length)
+            throw new Error(`invalid remote shell sandbox request: ${errors.join('; ')}`);
+        return request;
+    }
+    remoteRealPathsForScope(paths) {
+        return paths.map((path) => {
+            const kPath = this.shellPath(path);
+            const real = this.runtime.realPath(kPath);
+            if (!real)
+                throw new Error(`remote shell sandbox scope path has no real backing path: ${kPath}`);
+            return real;
+        });
+    }
+    remoteDenyWritePaths(paths) {
+        return [...new Set(paths.map((path) => this.remoteSandboxPath(path)))];
+    }
+    remoteSandboxPath(path) {
+        if (path === '~' || path.startsWith('~/'))
+            return this.requireRealKPath(`${this.home}${path.slice(1)}`);
+        if (path.startsWith('./') || path.startsWith('.'))
+            return this.requireRealKPath(`${this.cwd}/${path}`);
+        if (path.startsWith('/home/') || path.startsWith('/workspace') || path.startsWith('/tmp/')) {
+            return this.requireRealKPath(path);
+        }
+        return path;
+    }
+    requireRealKPath(path) {
+        const kPath = normalizeKPath(path);
+        const real = this.runtime.realPath(kPath);
+        if (!real)
+            throw new Error(`remote shell sandbox path has no real backing path: ${kPath}`);
+        return real;
+    }
+    isKCommandInvocation(script, parsed) {
+        if (parsed.length !== 1)
+            return false;
+        if (!isSimpleShellCommand(script))
+            return false;
+        const cmd = parsed[0]?.cmd;
+        return Boolean(cmd && this.runtime.commands.has(cmd));
+    }
+    isKBuiltinInvocation(script, parsed) {
+        if (parsed.length !== 1)
+            return false;
+        if (!isSimpleShellCommand(script))
+            return false;
+        const cmd = parsed[0]?.cmd;
+        return Boolean(cmd && K_BUILTINS.has(cmd));
+    }
+    isKShellFunctionInvocation(script, parsed) {
+        if (parsed.length !== 1)
+            return false;
+        if (!isSimpleShellCommand(script))
+            return false;
+        const cmd = parsed[0]?.cmd;
+        return Boolean(cmd && this.shellFunctions[cmd] !== undefined);
+    }
+    async isKLocalSequence(parsed) {
+        if (parsed.length <= 1)
+            return false;
+        for (let index = 0; index < parsed.length; index += 1) {
+            const segment = parsed[index];
+            if (!segment)
+                return false;
+            if (segment.assignmentOnly || segment.cmd === '(' || segment.cmd === 'return' || K_BUILTINS.has(segment.cmd) || this.runtime.commands.has(segment.cmd) || this.shellFunctions[segment.cmd] !== undefined)
+                continue;
+            const participatesInPipeline = segment.separator === '|' || parsed[index + 1]?.separator === '|';
+            if (!participatesInPipeline && await this.resolveKExecutable(segment.cmd, segment.env))
+                continue;
+            if (!this.runtime.defaultRemote().capabilities.shell)
+                continue;
+            return false;
+        }
+        return true;
+    }
+    async resolveKExecutable(cmd, env) {
+        const expandedEnv = await this.expandShellEnv(env || {});
+        const candidates = cmd.includes('/')
+            ? [cmd]
+            : this.effectiveShellEnv(expandedEnv).PATH.split(':').filter(Boolean).map((dir) => `${dir.replace(/\/$/, '')}/${cmd}`);
+        for (const candidate of candidates) {
+            const kPath = this.shellPath(candidate);
+            try {
+                const stat = await this.fs.stat(kPath);
+                if (stat.type === 'file' && isExecutable(stat))
+                    return this.fs.path(kPath);
+                if (stat.type === 'symlink') {
+                    const target = await this.fs.stat(await this.fs.realpath(kPath));
+                    if (target.type === 'file' && isExecutable(target))
+                        return this.fs.path(kPath);
+                }
+            }
+            catch {
+                // PATH lookup should behave like Unix: missing entries are ignored.
+            }
+        }
+        return undefined;
+    }
+    async execKLocalSequence(parsed, { by, redirects = [], foreground = true, signal } = {}) {
+        let lastCode = 0;
+        let lastResult = { status: 'committed', code: 0, stdout: '', stderr: '' };
+        let stdout = '';
+        let stderr = '';
+        let pipelineInput = '';
+        let pipelineFailureCode = 0;
+        for (let index = 0; index < parsed.length; index += 1) {
+            const aborted = abortedShellResult(signal);
+            if (aborted)
+                return { ...lastResult, ...aborted, stdout, stderr };
+            const segment = parsed[index];
+            if (segment.separator === '&&' && lastCode !== 0)
+                continue;
+            if (segment.separator === '||' && lastCode === 0)
+                continue;
+            const redirect = redirects[index];
+            const segmentForeground = foreground && !segment.background;
+            const stdin = segmentForeground
+                ? segment.separator === '|'
+                    ? pipelineInput
+                    : redirect?.stdinText !== undefined
+                        ? redirect.stdinText
+                        : redirect?.stdin
+                            ? await this.fs.readText(await this.expandRedirectPath(redirect.stdin))
+                            : ''
+                : '';
+            if (redirect) {
+                const prepared = await this.prepareRedirect(redirect, by);
+                if (!prepared.ok) {
+                    return { status: 'rejected', code: 126, stdout, stderr: `${stderr}${prepared.stderr}` };
+                }
+            }
+            const inPipeline = segment.separator === '|' || parsed[index + 1]?.separator === '|';
+            const result = inPipeline
+                ? await this.withTemporaryShellState({}, () => this.execKLocalSegment(segment, { stdin, by, foreground: segmentForeground, signal }))
+                : await this.execKLocalSegment(segment, { stdin, by, foreground: segmentForeground, signal });
+            const abortedAfterSegment = abortedShellResult(signal);
+            lastResult = result;
+            let segmentStdout = typeof result.stdout === 'string' ? result.stdout : '';
+            let segmentStderr = typeof result.stderr === 'string' ? result.stderr : '';
+            if (redirect) {
+                const redirected = await this.applyRedirectedStreams(segmentStdout, segmentStderr, redirect, by);
+                if (!redirected.ok) {
+                    return { ...result, status: 'rejected', code: 126, stdout, stderr: `${stderr}${redirected.stderr}` };
+                }
+                segmentStdout = redirected.stdout;
+                segmentStderr = redirected.stderr;
+            }
+            if (parsed[index + 1]?.separator === '|')
+                pipelineInput = segmentStdout;
+            else {
+                stdout = appendBoundedShellCapture(stdout, segmentStdout);
+                pipelineInput = '';
+            }
+            stderr = appendBoundedShellCapture(stderr, segmentStderr);
+            const segmentCode = shellExitCode(result);
+            const pipelineEndsHere = inPipeline && parsed[index + 1]?.separator !== '|';
+            if (inPipeline && segmentCode !== 0 && pipelineFailureCode === 0)
+                pipelineFailureCode = segmentCode;
+            lastCode = pipelineEndsHere && this.shellOptions.pipefail && pipelineFailureCode !== 0 ? pipelineFailureCode : segmentCode;
+            if (!inPipeline || pipelineEndsHere)
+                pipelineFailureCode = 0;
+            this.lastExitCode = lastCode;
+            if (result.status === 'rejected' || result.status === 'waiting_approval' || result.status === 'return')
+                break;
+            if (abortedAfterSegment) {
+                lastResult = { ...result, ...abortedAfterSegment };
+                break;
+            }
+            const nextSeparator = parsed[index + 1]?.separator;
+            if (this.shellOptions.errexit && lastCode !== 0 && nextSeparator !== '&&' && nextSeparator !== '||' && nextSeparator !== '|')
+                break;
+        }
+        const status = lastCode === 0 || lastResult.status !== 'committed' ? lastResult.status : 'failed';
+        return {
+            ...lastResult,
+            status,
+            code: lastCode,
+            stdout,
+            stderr,
+        };
+    }
+    async execBackgroundKLocalSequence(script, parsed, { by, redirects = [], signal } = {}) {
+        await this.emit({ type: 'process', status: 'started', command: 'shell', argv: [], script, kind: 'k.shell', background: true });
+        const trace = await this.trace('process.started', { cmd: 'shell', args: [], script, kind: 'k.shell', foreground: false, background: true });
+        const background = await this.vprocess.spawnVirtual(script, async (backgroundSignal) => {
+            const result = await this.withTemporaryShellState({}, () => this.execKLocalSequence(parsed, {
+                by,
+                redirects,
+                foreground: true,
+                signal: backgroundSignal || signal,
+            }));
+            return {
+                code: shellExitCode(result),
+                signal: typeof result.signal === 'string' ? result.signal : null,
+                stdout: typeof result.stdout === 'string' ? result.stdout : '',
+                stderr: typeof result.stderr === 'string' ? result.stderr : '',
+            };
+        }, { cwd: this.cwd, foreground: false });
+        const receipt = makeReceipt({
+            traceId: trace.traceSeq,
+            sessionId: this.sessionId,
+            agent: this.agentName,
+            kind: 'k.shell',
+            target: 'shell',
+            summary: script,
+            status: 'uncertain',
+            by: normalizeBy(by),
+            input: { script, background: true },
+            output: { vpid: background.vpid, jobId: background.jobId },
+        });
+        await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+        await this.trackBackgroundReceipt(background, receipt);
+        await this.trace('process.ended', { cmd: 'shell', args: [], script, status: 'uncertain', receiptId: receipt.id, kind: 'k.shell', background: true, vpid: background.vpid, jobId: background.jobId });
+        await this.emit({ type: 'process', status: 'uncertain', command: 'shell', argv: [], script, receiptId: receipt.id, kind: 'k.shell', background: true, opId: background.vpid, jobId: background.jobId });
+        return { status: 'uncertain', receipt, ...background };
+    }
+    async execKLocalSegment(segment, { stdin = '', by, foreground = true, signal } = {}) {
+        if (segment.assignmentOnly) {
+            await this.setShellEnv(await this.expandShellEnv(segment.env || {}) ?? {});
+            return { status: 'committed', code: 0, stdout: '', stderr: '' };
+        }
+        if (segment.cmd === '(')
+            return this.execKSubshellFromShell({ segment, by, signal });
+        if (segment.cmd === 'return')
+            return this.execShellReturn(segment);
+        return K_BUILTINS.has(segment.cmd)
+            ? this.execKBuiltinFromShell({ cmd: segment.cmd, args: segment.args, argTokens: segment.wordTokens.slice(1), script: segment.script, foreground, by, stdin, env: segment.env, signal })
+            : this.runtime.commands.has(segment.cmd)
+                ? this.execKCommandFromShell({ cmd: segment.cmd, args: segment.args, argTokens: segment.wordTokens.slice(1), script: segment.script, foreground, by, stdin, env: segment.env })
+                : this.shellFunctions[segment.cmd] !== undefined
+                    ? this.execKShellFunctionFromShell({ cmd: segment.cmd, args: segment.args, argTokens: segment.wordTokens.slice(1), script: segment.script, foreground, by, env: segment.env, signal })
+                    : this.execKExecutableFromShell({
+                        path: await this.resolveKExecutable(segment.cmd, segment.env) || segment.cmd,
+                        cmd: segment.cmd,
+                        args: segment.args,
+                        argTokens: segment.wordTokens.slice(1),
+                        script: segment.script,
+                        foreground,
+                        by,
+                        env: segment.env,
+                        signal,
+                    });
+    }
+    async execKSubshellFromShell({ segment, by, signal }) {
+        const inner = segment.args[0] || parseShellGroup(segment.script);
+        if (!inner)
+            return { status: 'failed', code: 2, stdout: '', stderr: 'subshell: missing closing )\n' };
+        const env = await this.expandShellEnv(segment.env || {});
+        return this.withTemporaryShellState({ env }, () => this.execInternal(inner, { by: by || 'shell:subshell', signal }));
+    }
+    async execKLocalFunctionProgram(program, { by, signal } = {}) {
+        let last = { status: 'committed', code: 0, stdout: '', stderr: '' };
+        let stdout = '';
+        let stderr = '';
+        if (program.prefix) {
+            last = await this.execInternal(program.prefix, { by, signal });
+            stdout = appendBoundedShellCapture(stdout, typeof last.stdout === 'string' ? last.stdout : '');
+            stderr = appendBoundedShellCapture(stderr, typeof last.stderr === 'string' ? last.stderr : '');
+            if (last.status === 'rejected' || last.status === 'waiting_approval' || shellExitCode(last) !== 0 && this.shellOptions.errexit) {
+                return { ...last, stdout, stderr };
+            }
+        }
+        this.shellFunctions[program.definition.name] = program.definition.body;
+        await this.saveSession({ shell: this.shellSessionRecord() });
+        await this.trace('shell.function', { name: program.definition.name });
+        if (program.suffix) {
+            last = await this.execInternal(program.suffix, { by, signal });
+            stdout = appendBoundedShellCapture(stdout, typeof last.stdout === 'string' ? last.stdout : '');
+            stderr = appendBoundedShellCapture(stderr, typeof last.stderr === 'string' ? last.stderr : '');
+        }
+        return { ...last, code: shellExitCode(last), stdout, stderr };
+    }
+    execShellReturn(segment) {
+        if (this.functionDepth <= 0 && this.sourceDepth <= 0)
+            return { status: 'failed', code: 2, stdout: '', stderr: 'return: can only return from a function or sourced script\n' };
+        const value = segment.args[0] ?? '0';
+        const parsed = Number.parseInt(value, 10);
+        const code = Number.isFinite(parsed) ? ((parsed % 256) + 256) % 256 : 2;
+        return { status: 'return', code, stdout: '', stderr: Number.isFinite(parsed) ? '' : `return: ${value}: numeric argument required\n` };
+    }
+    async execKLocalControlProgram(program, { by, signal } = {}) {
+        let last = { status: 'committed', code: 0, stdout: '', stderr: '' };
+        let stdout = '';
+        let stderr = '';
+        const runPart = async (script) => {
+            last = await this.execInternal(script, { by, signal });
+            stdout = appendBoundedShellCapture(stdout, typeof last.stdout === 'string' ? last.stdout : '');
+            stderr = appendBoundedShellCapture(stderr, typeof last.stderr === 'string' ? last.stderr : '');
+            if (last.status === 'rejected' || last.status === 'waiting_approval')
+                return false;
+            if (this.shellOptions.errexit && shellExitCode(last) !== 0)
+                return false;
+            return true;
+        };
+        if (program.prefix && !await runPart(program.prefix))
+            return { ...last, stdout, stderr };
+        last = await this.execKLocalControl(program.control, { by, signal });
+        stdout = appendBoundedShellCapture(stdout, typeof last.stdout === 'string' ? last.stdout : '');
+        stderr = appendBoundedShellCapture(stderr, typeof last.stderr === 'string' ? last.stderr : '');
+        if (last.status === 'rejected' || last.status === 'waiting_approval')
+            return { ...last, stdout, stderr };
+        if (this.shellOptions.errexit && shellExitCode(last) !== 0)
+            return { ...last, stdout, stderr };
+        if (program.suffix)
+            await runPart(program.suffix);
+        return { ...last, code: shellExitCode(last), stdout, stderr };
+    }
+    async execKLocalControl(control, { by, signal } = {}) {
+        if (control.type === 'if') {
+            const condition = await this.execInternal(control.condition, { by, signal });
+            const conditionCode = shellExitCode(condition);
+            const branchScript = conditionCode === 0 ? control.thenScript : control.elseScript;
+            const branch = branchScript ? await this.execInternal(branchScript, { by, signal }) : { status: 'committed', code: 0, stdout: '', stderr: '' };
+            const code = shellExitCode(branch);
+            return {
+                ...branch,
+                code,
+                stdout: appendBoundedShellCapture(typeof condition.stdout === 'string' ? condition.stdout : '', typeof branch.stdout === 'string' ? branch.stdout : ''),
+                stderr: appendBoundedShellCapture(typeof condition.stderr === 'string' ? condition.stderr : '', typeof branch.stderr === 'string' ? branch.stderr : ''),
+            };
+        }
+        if (control.type === 'for') {
+            const values = await this.expandShellArgs(control.items);
+            let last = { status: 'committed', code: 0, stdout: '', stderr: '' };
+            let stdout = '';
+            let stderr = '';
+            for (const value of values) {
+                await this.setShellEnv({ [control.name]: value });
+                last = await this.execInternal(control.body, { by, signal });
+                stdout = appendBoundedShellCapture(stdout, typeof last.stdout === 'string' ? last.stdout : '');
+                stderr = appendBoundedShellCapture(stderr, typeof last.stderr === 'string' ? last.stderr : '');
+                const code = shellExitCode(last);
+                if (last.status === 'rejected' || last.status === 'waiting_approval')
+                    break;
+                if (this.shellOptions.errexit && code !== 0)
+                    break;
+            }
+            const code = shellExitCode(last);
+            return { ...last, code, stdout, stderr };
+        }
+        if (control.type === 'case') {
+            const value = await this.expandCaseToken(control.word);
+            for (const arm of control.arms) {
+                const patterns = await Promise.all(arm.patterns.map((pattern) => this.expandCaseToken(pattern)));
+                if (!patterns.some((pattern) => globMatcher(pattern)(value)))
+                    continue;
+                const branch = arm.body ? await this.execInternal(arm.body, { by, signal }) : { status: 'committed', code: 0, stdout: '', stderr: '' };
+                return { ...branch, code: shellExitCode(branch) };
+            }
+            return { status: 'committed', code: 0, stdout: '', stderr: '' };
+        }
+        let last = { status: 'committed', code: 0, stdout: '', stderr: '' };
+        let stdout = '';
+        let stderr = '';
+        let hitLimit = true;
+        for (let iteration = 0; iteration < MAX_K_LOCAL_CONTROL_ITERATIONS; iteration += 1) {
+            const condition = await this.execInternal(control.condition, { by, signal });
+            stdout = appendBoundedShellCapture(stdout, typeof condition.stdout === 'string' ? condition.stdout : '');
+            stderr = appendBoundedShellCapture(stderr, typeof condition.stderr === 'string' ? condition.stderr : '');
+            if (condition.status === 'rejected' || condition.status === 'waiting_approval')
+                return { ...condition, stdout, stderr };
+            const conditionPassed = shellExitCode(condition) === 0;
+            if (control.type === 'while' ? !conditionPassed : conditionPassed) {
+                hitLimit = false;
+                break;
+            }
+            last = await this.execInternal(control.body, { by, signal });
+            stdout = appendBoundedShellCapture(stdout, typeof last.stdout === 'string' ? last.stdout : '');
+            stderr = appendBoundedShellCapture(stderr, typeof last.stderr === 'string' ? last.stderr : '');
+            const code = shellExitCode(last);
+            if (last.status === 'rejected' || last.status === 'waiting_approval') {
+                hitLimit = false;
+                break;
+            }
+            if (this.shellOptions.errexit && code !== 0) {
+                hitLimit = false;
+                break;
+            }
+        }
+        if (hitLimit) {
+            return { status: 'failed', code: 124, stdout, stderr: `${stderr}K local shell loop exceeded ${MAX_K_LOCAL_CONTROL_ITERATIONS} iterations\n` };
+        }
+        const code = shellExitCode(last);
+        return { ...last, code, stdout, stderr };
+    }
+    async execKCommandFromShell({ cmd, args, argTokens, script, foreground, by, stdin = '', env }) {
+        let expandedArgs;
+        let expandedEnv;
+        try {
+            expandedEnv = await this.expandShellEnv(env);
+            expandedArgs = await this.expandShellArgs(argTokens || args.map(shellWordToken));
+        }
+        catch (error) {
+            return this.failShellCommandBeforeRun({ cmd, args, script, kind: 'k.command', by: by || `shell:${cmd}`, error });
+        }
+        const command = this.runtime.commands.get(cmd);
+        if (command && expandedArgs.length === 1 && isHelpArg(expandedArgs[0])) {
+            const stdout = `${commandHelpText(cmd, command)}\n`;
+            return { status: 'committed', code: 0, stdout, stderr: '' };
+        }
+        if (!foreground) {
+            await this.emit({ type: 'process', status: 'started', command: cmd, argv: args, script, kind: 'k.command', background: true });
+            const trace = await this.trace('process.started', { cmd, args, script, kind: 'k.command', foreground, background: true });
+            const background = await this.vprocess.spawnVirtual(script, async () => {
+                try {
+                    const input = shellArgsToInput(expandedArgs);
+                    if (stdin)
+                        input.stdin = stdin;
+                    const result = await this.command(cmd, input, { by: by || `shell:${cmd}` });
+                    return { signal: null, ...commandResultToShellResult(result) };
+                }
+                catch (error) {
+                    return { code: 1, signal: null, stdout: '', stderr: commandErrorText(cmd, error) };
+                }
+            }, { cwd: this.cwd, foreground: false });
+            const receipt = makeReceipt({
+                traceId: trace.traceSeq,
+                sessionId: this.sessionId,
+                agent: this.agentName,
+                kind: 'k.command',
+                target: cmd,
+                summary: script,
+                status: 'uncertain',
+                by: normalizeBy(by || `shell:${cmd}`),
+                input: { cmd, args: expandedArgs, background: true },
+                output: { vpid: background.vpid, jobId: background.jobId },
+            });
+            await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+            await this.trackBackgroundReceipt(background, receipt);
+            await this.trace('process.ended', { cmd, args, script, status: 'uncertain', receiptId: receipt.id, kind: 'k.command', background: true, vpid: background.vpid, jobId: background.jobId });
+            await this.emit({ type: 'process', status: 'uncertain', command: cmd, argv: args, script, receiptId: receipt.id, kind: 'k.command', background: true, opId: background.vpid, jobId: background.jobId });
+            return { status: 'uncertain', receipt, ...background };
+        }
+        await this.emit({ type: 'process', status: 'started', command: cmd, argv: args, script, kind: 'k.command' });
+        const trace = await this.trace('process.started', { cmd, args, script, kind: 'k.command', foreground });
+        try {
+            const input = shellArgsToInput(expandedArgs);
+            if (stdin)
+                input.stdin = stdin;
+            const result = await this.command(cmd, input, { by: by || `shell:${cmd}` });
+            const shellResult = commandResultToShellResult(result);
+            const status = shellResult.code === 0 ? 'committed' : 'failed';
+            const receipt = makeReceipt({
+                traceId: trace.traceSeq,
+                sessionId: this.sessionId,
+                agent: this.agentName,
+                kind: 'k.command',
+                target: cmd,
+                summary: script,
+                status,
+                by: normalizeBy(by || `shell:${cmd}`),
+                input: { cmd, args: expandedArgs },
+                output: this.boundShellReceiptOutput(result),
+                error: status === 'failed' ? compactShellCaptureText(shellResult.stderr || `exit ${shellResult.code}`).text : undefined,
+            });
+            await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+            await this.emitShellOutput(shellResult);
+            await this.trace('process.ended', { cmd, args, script, status, code: shellResult.code, receiptId: receipt.id, kind: 'k.command' });
+            await this.emit({ type: 'process', status: processStatus(status, shellResult.code), command: cmd, argv: args, script, code: shellResult.code, receiptId: receipt.id, kind: 'k.command' });
+            return { status, receipt, ...shellResult };
+        }
+        catch (error) {
+            const stderr = commandErrorText(cmd, error);
+            const receipt = makeReceipt({
+                traceId: trace.traceSeq,
+                sessionId: this.sessionId,
+                agent: this.agentName,
+                kind: 'k.command',
+                target: cmd,
+                summary: script,
+                status: 'failed',
+                by: normalizeBy(by || `shell:${cmd}`),
+                input: { cmd, args: expandedArgs },
+                error: stderr,
+            });
+            await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+            if (stderr)
+                await this.emit({ type: 'process', status: 'output', text: stderr, stream: 'stderr', command: cmd, kind: 'k.command' });
+            await this.trace('process.ended', { cmd, args, script, status: 'failed', code: 1, receiptId: receipt.id, kind: 'k.command' });
+            await this.emit({ type: 'process', status: 'failed', command: cmd, argv: args, script, code: 1, receiptId: receipt.id, kind: 'k.command' });
+            return { status: 'failed', code: 1, stdout: '', stderr, receipt };
+        }
+    }
+    async execKBuiltinFromShell({ cmd, args, argTokens, script, foreground, by, stdin = '', env, signal }) {
+        let expandedArgs;
+        let expandedEnv;
+        try {
+            expandedEnv = await this.expandShellEnv(env);
+            expandedArgs = await this.expandShellArgs(argTokens || args.map(shellWordToken));
+        }
+        catch (error) {
+            return this.failShellCommandBeforeRun({ cmd, args, script, kind: 'k.builtin', by: by || `shell:${cmd}`, error });
+        }
+        if (!foreground) {
+            await this.emit({ type: 'process', status: 'started', command: cmd, argv: args, script, kind: 'k.builtin', background: true });
+            const trace = await this.trace('process.started', { cmd, args, script, kind: 'k.builtin', foreground, background: true });
+            const background = await this.vprocess.spawnVirtual(script, async (signal) => {
+                try {
+                    const output = await this.runBuiltin(cmd, expandedArgs, '', signal, expandedEnv, by || `shell:${cmd}`);
+                    return { code: output.code, signal: null, stdout: output.stdout, stderr: output.stderr };
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        return { code: 130, signal: 'SIGTERM', stdout: '', stderr: '' };
+                    return { code: 1, signal: null, stdout: '', stderr: builtinErrorText(cmd, error) };
+                }
+            }, { cwd: this.cwd, foreground: false });
+            const receipt = makeReceipt({
+                traceId: trace.traceSeq,
+                sessionId: this.sessionId,
+                agent: this.agentName,
+                kind: 'k.builtin',
+                target: cmd,
+                summary: script,
+                status: 'uncertain',
+                by: normalizeBy(by || `shell:${cmd}`),
+                input: { cmd, args: expandedArgs, background: true },
+                output: { vpid: background.vpid, jobId: background.jobId },
+            });
+            await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+            await this.trackBackgroundReceipt(background, receipt);
+            await this.trace('process.ended', { cmd, args, script, status: 'uncertain', receiptId: receipt.id, kind: 'k.builtin', background: true, vpid: background.vpid, jobId: background.jobId });
+            await this.emit({ type: 'process', status: 'uncertain', command: cmd, argv: args, script, receiptId: receipt.id, kind: 'k.builtin', background: true, opId: background.vpid, jobId: background.jobId });
+            return { status: 'uncertain', receipt, ...background };
+        }
+        await this.emit({ type: 'process', status: 'started', command: cmd, argv: args, script, kind: 'k.builtin' });
+        const trace = await this.trace('process.started', { cmd, args, script, kind: 'k.builtin', foreground });
+        try {
+            const output = await this.runBuiltin(cmd, expandedArgs, stdin, signal, expandedEnv, by || `shell:${cmd}`);
+            const status = output.code === 0 ? 'committed' : 'failed';
+            const receipt = makeReceipt({
+                traceId: trace.traceSeq,
+                sessionId: this.sessionId,
+                agent: this.agentName,
+                kind: 'k.builtin',
+                target: cmd,
+                summary: script,
+                status,
+                by: normalizeBy(by || `shell:${cmd}`),
+                input: { cmd, args: expandedArgs, stdin: stdin ? '[stdin]' : undefined },
+                output: this.boundShellReceiptOutput(output),
+                error: status === 'failed' ? compactShellCaptureText(output.stderr || `exit ${output.code}`).text : undefined,
+            });
+            await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+            if (output.stdout)
+                await this.emit({ type: 'process', status: 'output', text: output.stdout, stream: 'stdout', command: cmd, kind: 'k.builtin' });
+            if (output.stderr)
+                await this.emit({ type: 'process', status: 'output', text: output.stderr, stream: 'stderr', command: cmd, kind: 'k.builtin' });
+            await this.trace('process.ended', { cmd, args, script, status, code: output.code, receiptId: receipt.id, kind: 'k.builtin' });
+            await this.emit({ type: 'process', status: processStatus(status, output.code), command: cmd, argv: args, script, code: output.code, receiptId: receipt.id, kind: 'k.builtin' });
+            return { status, code: output.code, stdout: output.stdout, stderr: output.stderr, receipt };
+        }
+        catch (error) {
+            const stderr = builtinErrorText(cmd, error);
+            const code = signal?.aborted ? 130 : 1;
+            const signalName = signal?.aborted ? signalReason(signal) : undefined;
+            const receipt = makeReceipt({
+                traceId: trace.traceSeq,
+                sessionId: this.sessionId,
+                agent: this.agentName,
+                kind: 'k.builtin',
+                target: cmd,
+                summary: script,
+                status: 'failed',
+                by: normalizeBy(by || `shell:${cmd}`),
+                input: { cmd, args: expandedArgs, stdin: stdin ? '[stdin]' : undefined },
+                error: stderr,
+            });
+            await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+            if (stderr)
+                await this.emit({ type: 'process', status: 'output', text: stderr, stream: 'stderr', command: cmd, kind: 'k.builtin' });
+            await this.trace('process.ended', { cmd, args, script, status: 'failed', code, signal: signalName, receiptId: receipt.id, kind: 'k.builtin' });
+            await this.emit({ type: 'process', status: 'failed', command: cmd, argv: args, script, code, signal: signalName, receiptId: receipt.id, kind: 'k.builtin' });
+            return { status: 'failed', code, signal: signalName, stdout: '', stderr, receipt };
+        }
+    }
+    async execKShellFunctionFromShell({ cmd, args, argTokens, script, foreground, by, env, signal }) {
+        const body = this.shellFunctions[cmd];
+        if (body === undefined)
+            return this.failShellCommandBeforeRun({ cmd, args, script, kind: 'k.executable', by: by || `function:${cmd}`, error: new Error(`function not found: ${cmd}`) });
+        let expandedArgs;
+        let expandedEnv;
+        try {
+            expandedEnv = await this.expandShellEnv(env);
+            expandedArgs = await this.expandShellArgs(argTokens || args.map(shellWordToken));
+        }
+        catch (error) {
+            return this.failShellCommandBeforeRun({ cmd, args, script, kind: 'k.executable', by: by || `function:${cmd}`, error });
+        }
+        const run = async (runSignal) => {
+            const positional = { ...(expandedEnv || {}), ...positionalShellEnv(cmd, expandedArgs) };
+            this.functionDepth += 1;
+            try {
+                const result = await this.withTemporaryShellEnvKeys(positional, () => this.execInternal(body, { by: by || `function:${cmd}`, signal: runSignal || signal }));
+                if (result.status !== 'return')
+                    return result;
+                const code = shellExitCode(result);
+                return { ...result, status: code === 0 ? 'committed' : 'failed', code };
+            }
+            finally {
+                this.functionDepth -= 1;
+            }
+        };
+        if (!foreground) {
+            await this.emit({ type: 'process', status: 'started', command: cmd, argv: args, script, kind: 'k.function', background: true });
+            const trace = await this.trace('process.started', { cmd, args, script, kind: 'k.function', foreground, background: true });
+            const background = await this.vprocess.spawnVirtual(script, async (backgroundSignal) => {
+                const result = await run(backgroundSignal);
+                return {
+                    code: shellExitCode(result),
+                    signal: typeof result.signal === 'string' ? result.signal : null,
+                    stdout: typeof result.stdout === 'string' ? result.stdout : '',
+                    stderr: typeof result.stderr === 'string' ? result.stderr : '',
+                };
+            }, { cwd: this.cwd, foreground: false });
+            const receipt = makeReceipt({
+                traceId: trace.traceSeq,
+                sessionId: this.sessionId,
+                agent: this.agentName,
+                kind: 'k.function',
+                target: cmd,
+                summary: script,
+                status: 'uncertain',
+                by: normalizeBy(by || `function:${cmd}`),
+                input: { cmd, args: expandedArgs, background: true },
+                output: { vpid: background.vpid, jobId: background.jobId },
+            });
+            await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+            await this.trackBackgroundReceipt(background, receipt);
+            await this.trace('process.ended', { cmd, args, script, status: 'uncertain', receiptId: receipt.id, kind: 'k.function', background: true, vpid: background.vpid, jobId: background.jobId });
+            await this.emit({ type: 'process', status: 'uncertain', command: cmd, argv: args, script, receiptId: receipt.id, kind: 'k.function', background: true, opId: background.vpid, jobId: background.jobId });
+            return { status: 'uncertain', receipt, ...background };
+        }
+        await this.emit({ type: 'process', status: 'started', command: cmd, argv: args, script, kind: 'k.function' });
+        const trace = await this.trace('process.started', { cmd, args, script, kind: 'k.function', foreground });
+        try {
+            const result = await run(signal);
+            const code = shellExitCode(result);
+            const status = code === 0 ? 'committed' : 'failed';
+            const shellResult = { stdout: typeof result.stdout === 'string' ? result.stdout : '', stderr: typeof result.stderr === 'string' ? result.stderr : '' };
+            const receipt = makeReceipt({
+                traceId: trace.traceSeq,
+                sessionId: this.sessionId,
+                agent: this.agentName,
+                kind: 'k.function',
+                target: cmd,
+                summary: script,
+                status,
+                by: normalizeBy(by || `function:${cmd}`),
+                input: { cmd, args: expandedArgs },
+                output: this.boundShellReceiptOutput(result),
+                error: status === 'failed' ? compactShellCaptureText(shellResult.stderr).text : undefined,
+            });
+            await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+            await this.trace('process.ended', { cmd, args, script, status, code, receiptId: receipt.id, kind: 'k.function' });
+            await this.emit({ type: 'process', status: processStatus(status, code), command: cmd, argv: args, script, code, receiptId: receipt.id, kind: 'k.function' });
+            return { status, code, receipt, ...shellResult };
+        }
+        catch (error) {
+            return this.failShellCommandBeforeRun({ cmd, args, script, kind: 'k.executable', by: by || `function:${cmd}`, error });
+        }
+    }
+    async execKExecutableFromShell({ path, cmd, args, argTokens, script, foreground, by, env, signal }) {
+        let expandedArgs;
+        let expandedEnv;
+        try {
+            expandedEnv = await this.expandShellEnv(env);
+            expandedArgs = await this.expandShellArgs(argTokens || args.map(shellWordToken));
+        }
+        catch (error) {
+            return this.failShellCommandBeforeRun({ cmd, args, script, kind: 'k.executable', by: by || `shell:${cmd}`, error });
+        }
+        const run = async (runSignal) => {
+            const body = executableScriptBody(await this.fs.readText(path));
+            if (!body.trim())
+                return { status: 'committed', code: 0, stdout: '', stderr: '' };
+            const positional = positionalShellEnv(path, expandedArgs);
+            return this.withTemporaryShellState({ env: positional }, () => this.execInternal(body, { by: by || `shell:${cmd}`, signal: runSignal || signal }));
+        };
+        if (!foreground) {
+            await this.emit({ type: 'process', status: 'started', command: cmd, argv: args, script, path, kind: 'k.executable', background: true });
+            const trace = await this.trace('process.started', { cmd, args, script, path, kind: 'k.executable', foreground, background: true });
+            const background = await this.vprocess.spawnVirtual(script, async (backgroundSignal) => {
+                const result = await run(backgroundSignal);
+                return {
+                    code: shellExitCode(result),
+                    signal: typeof result.signal === 'string' ? result.signal : null,
+                    stdout: typeof result.stdout === 'string' ? result.stdout : '',
+                    stderr: typeof result.stderr === 'string' ? result.stderr : '',
+                };
+            }, { cwd: this.cwd, foreground: false });
+            const receipt = makeReceipt({
+                traceId: trace.traceSeq,
+                sessionId: this.sessionId,
+                agent: this.agentName,
+                kind: 'k.executable',
+                target: path,
+                summary: script,
+                status: 'uncertain',
+                by: normalizeBy(by || `shell:${cmd}`),
+                input: { path, cmd, args: expandedArgs, background: true },
+                output: { vpid: background.vpid, jobId: background.jobId },
+            });
+            await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+            await this.trackBackgroundReceipt(background, receipt);
+            await this.trace('process.ended', { cmd, args, script, path, status: 'uncertain', receiptId: receipt.id, kind: 'k.executable', background: true, vpid: background.vpid, jobId: background.jobId });
+            await this.emit({ type: 'process', status: 'uncertain', command: cmd, argv: args, script, path, receiptId: receipt.id, kind: 'k.executable', background: true, opId: background.vpid, jobId: background.jobId });
+            return { status: 'uncertain', receipt, ...background };
+        }
+        await this.emit({ type: 'process', status: 'started', command: cmd, argv: args, script, path, kind: 'k.executable' });
+        const trace = await this.trace('process.started', { cmd, args, script, path, kind: 'k.executable', foreground });
+        try {
+            const result = await run(signal);
+            const code = shellExitCode(result);
+            const status = code === 0 ? 'committed' : 'failed';
+            const shellResult = { stdout: typeof result.stdout === 'string' ? result.stdout : '', stderr: typeof result.stderr === 'string' ? result.stderr : '' };
+            const receipt = makeReceipt({
+                traceId: trace.traceSeq,
+                sessionId: this.sessionId,
+                agent: this.agentName,
+                kind: 'k.executable',
+                target: path,
+                summary: script,
+                status,
+                by: normalizeBy(by || `shell:${cmd}`),
+                input: { path, cmd, args: expandedArgs },
+                output: this.boundShellReceiptOutput(result),
+                error: status === 'failed' ? compactShellCaptureText(shellResult.stderr).text : undefined,
+            });
+            await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+            await this.trace('process.ended', { cmd, args, script, path, status, code, receiptId: receipt.id, kind: 'k.executable' });
+            await this.emit({ type: 'process', status: processStatus(status, code), command: cmd, argv: args, script, path, code, receiptId: receipt.id, kind: 'k.executable' });
+            return { status, code, receipt, ...shellResult };
+        }
+        catch (error) {
+            return this.failShellCommandBeforeRun({ cmd, args, script, kind: 'k.executable', by: by || `shell:${cmd}`, error });
+        }
+    }
+    async failShellCommandBeforeRun({ cmd, args, script, kind, by, error }) {
+        const stderr = error instanceof Error ? error.message : String(error);
+        await this.emit({ type: 'process', status: 'started', command: cmd, argv: args, script, kind });
+        const trace = await this.trace('process.started', { cmd, args, script, kind, foreground: true });
+        const receipt = makeReceipt({
+            traceId: trace.traceSeq,
+            sessionId: this.sessionId,
+            agent: this.agentName,
+            kind,
+            target: cmd,
+            summary: script,
+            status: 'failed',
+            by: normalizeBy(by),
+            input: { cmd, args },
+            error: stderr,
+        });
+        await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', receipt);
+        if (stderr)
+            await this.emit({ type: 'process', status: 'output', text: stderr, stream: 'stderr', command: cmd, kind });
+        await this.trace('process.ended', { cmd, args, script, status: 'failed', code: 1, receiptId: receipt.id, kind });
+        await this.emit({ type: 'process', status: 'failed', command: cmd, argv: args, script, code: 1, receiptId: receipt.id, kind });
+        return { status: 'failed', code: 1, stdout: '', stderr, receipt };
+    }
+    finalizeBackgroundReceipt(receipt, done) {
+        if (!done)
+            return;
+        void done.then(async (result) => {
+            if (this.closed)
+                return;
+            await this.assertWritableSession();
+            const detached = result.signal === 'SIGDETACH';
+            const status = detached ? 'uncertain' : result.code === 0 ? 'committed' : 'failed';
+            const final = finishReceipt(receipt, {
+                status,
+                output: this.boundShellReceiptOutput(result),
+                error: detached
+                    ? 'background process detached before completion; recovery must reconcile outcome'
+                    : status === 'failed'
+                        ? compactShellCaptureText(result.stderr || result.signal || `exit ${result.code}`).text
+                        : undefined,
+            });
+            await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', final);
+            await this.trace('receipt.finalized', {
+                receiptId: receipt.id,
+                kind: receipt.kind,
+                status,
+                code: result.code,
+                signal: result.signal,
+            });
+        }).catch(async (error) => {
+            if (this.closed)
+                return;
+            await this.assertWritableSession();
+            const message = error instanceof Error ? error.message : String(error);
+            const final = finishReceipt(receipt, {
+                status: 'uncertain',
+                error: message,
+            });
+            await this.kstate.appendSessionJsonl(this.sessionId, 'receipts.jsonl', final);
+            await this.trace('receipt.finalized', {
+                receiptId: receipt.id,
+                kind: receipt.kind,
+                status: 'uncertain',
+                error: message,
+            });
+        }).catch(() => undefined);
+    }
+    async trackBackgroundReceipt(process, receipt) {
+        await this.vprocess.attachReceipt(process.vpid, receipt.id);
+        this.finalizeBackgroundReceipt(receipt, process.done);
+    }
+    async runBuiltin(cmd, args, stdin = '', signal, localEnv, by) {
+        return this.withFsActor(by || `builtin:${cmd}`, () => runBuiltin({
+            cwd: this.cwd,
+            home: this.home,
+            agentName: this.agentName,
+            sessionId: this.sessionId,
+            fs: this.fs,
+            commands: this.runtime.commands,
+            functions: new Set(Object.keys(this.shellFunctions)),
+            shellPath: (path) => this.shellPath(path),
+            cd: (path) => this.localComputer.shell.cd(path),
+            env: () => this.effectiveShellEnv(localEnv),
+            setEnv: (name, value) => this.setShellEnv({ [name]: value }),
+            unsetEnv: (name) => this.unsetShellEnv(name),
+            shellOptions: () => this.shellOptions,
+            setShellOptions: (patch) => this.setShellOptions(patch),
+            sleep: (ms, sleepSignal) => sleep(ms, sleepSignal),
+            jobs: () => this.jobs(),
+            processes: () => this.processes(),
+            kill: (target, signal) => this.vprocess.kill(target, signal),
+            wait: async (target) => {
+                const result = await this.vprocess.wait(target);
+                await this.finalizeProcessReceiptFromWait(result);
+                return result;
+            },
+            foreground: async (target) => {
+                const result = await this.vprocess.foreground(target);
+                await this.finalizeProcessReceiptFromWait(result);
+                return result;
+            },
+            background: (target) => this.vprocess.background(target),
+            fetchNetwork: (url, init) => this.fetchNetwork(url, init),
+            exec: (script, options) => {
+                const scopedEnv = options?.replaceEnv ? options?.env : { ...(localEnv || {}), ...(options?.env || {}) };
+                const hasScopedEnv = Boolean(scopedEnv && Object.keys(scopedEnv).length);
+                return hasScopedEnv || options?.replaceEnv
+                    ? this.withTemporaryShellState({
+                        env: scopedEnv,
+                        replaceEnv: options?.replaceEnv,
+                    }, () => this.execInternal(script, { by: `builtin:${cmd}`, signal: options?.signal || signal }))
+                    : this.execInternal(script, { by: `builtin:${cmd}`, signal: options?.signal || signal });
+            },
+            source: (script, options) => this.withTemporaryShellEnvKeys({ ...(localEnv || {}), ...(options?.env || {}) }, async () => {
+                this.sourceDepth += 1;
+                try {
+                    return await this.execInternal(script, { by: `builtin:${cmd}`, signal: options?.signal || signal });
+                }
+                finally {
+                    this.sourceDepth -= 1;
+                }
+            }),
+            trace: (type, data) => this.trace(type, data).then(() => undefined),
+        }, cmd, args, stdin, signal));
+    }
+    async fetchNetwork(url, init = {}) {
+        const host = networkHostFromUrl(url);
+        const authority = decideNetwork({ mode: this.modeState, host });
+        if (!authority.ok) {
+            await this.trace('net.rejected', { url, host, reason: authority.reason, mode: this.mode });
+            throw new Error(authority.reason);
+        }
+        return this.runtime.fetchNetwork(url, init);
+    }
+    async applyRedirectedStreams(stdout, stderr, redirect, by) {
+        let stdoutTarget = { kind: 'visible', stream: 'stdout' };
+        let stderrTarget = { kind: 'visible', stream: 'stderr' };
+        for (const op of redirect.ops) {
+            if (op.fd === 'stdout')
+                stdoutTarget = { kind: 'file', path: op.path, append: op.append };
+            else if ('to' in op)
+                stderrTarget = stdoutTarget;
+            else
+                stderrTarget = { kind: 'file', path: op.path, append: op.append };
+        }
+        const visible = { stdout: '', stderr: '' };
+        const files = [];
+        const route = (target, text) => {
+            if (target.kind === 'visible') {
+                if (text)
+                    visible[target.stream] += text;
+            }
+            else
+                files.push({ ...target, text });
+        };
+        route(stdoutTarget, stdout);
+        route(stderrTarget, stderr);
+        try {
+            const firstWrite = new Set();
+            await this.withFsActor(by || 'shell:redirection', async () => {
+                for (const file of files) {
+                    const target = await this.expandRedirectPath(file.path);
+                    await this.assertRedirectTargetWritable(target);
+                    const key = target;
+                    if (file.append || firstWrite.has(key))
+                        await this.fs.appendText(target, file.text);
+                    else {
+                        await this.fs.writeText(target, file.text);
+                        firstWrite.add(key);
+                    }
+                }
+            });
+            return { ok: true, stdout: visible.stdout, stderr: visible.stderr };
+        }
+        catch (error) {
+            return { ok: false, stderr: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    async prepareRedirect(redirect, by) {
+        try {
+            const opened = new Set();
+            await this.withFsActor(by || 'shell:redirection', async () => {
+                for (const op of redirect.ops) {
+                    if (!('path' in op))
+                        continue;
+                    const target = await this.expandRedirectPath(op.path);
+                    await this.assertRedirectTargetWritable(target);
+                    if (op.append || opened.has(target))
+                        await this.fs.appendText(target, '');
+                    else {
+                        await this.fs.writeText(target, '');
+                        opened.add(target);
+                    }
+                }
+            });
+            return { ok: true };
+        }
+        catch (error) {
+            return { ok: false, stderr: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    async expandRedirectPath(path) {
+        const expanded = await this.shellExpander.expandToken(shellWordToken(path), this.effectiveShellEnv());
+        return this.shellPath(expanded);
+    }
+    async assertRedirectTargetWritable(path) {
+        const parent = dirnamePath(path);
+        const stat = await this.fs.stat(parent);
+        if (stat.type !== 'dir')
+            throw new Error(`redirection target parent is not a directory: ${parent}`);
+        const target = await this.fs.stat(path).catch(() => undefined);
+        if (target?.type === 'dir')
+            throw new Error(`redirection target is a directory: ${path}`);
+    }
+    async expandShellArgs(args, localEnv = {}) {
+        const env = this.effectiveShellEnv(localEnv);
+        const expanded = [];
+        for (const arg of args) {
+            const word = await this.shellExpander.expandWord(arg, env);
+            const fields = word.split ? splitShellFields(word.text) : [word.text];
+            for (const field of fields) {
+                const braceFields = shouldExpandBraces(arg) ? expandBraceFields(field) : [field];
+                for (const braceField of braceFields)
+                    expanded.push(...await this.expandGlobArg({ ...arg, text: braceField }));
+            }
+        }
+        return expanded;
+    }
+    async expandCaseToken(token, localEnv = {}) {
+        const env = this.effectiveShellEnv(localEnv);
+        return (await this.shellExpander.expandWord(token, env)).text;
+    }
+    async expandShellEnv(env = {}) {
+        const entries = Object.entries(env);
+        if (!entries.length)
+            return undefined;
+        const expanded = {};
+        for (const [name, value] of entries) {
+            expanded[name] = await this.shellExpander.expandToken(shellWordToken(value), { ...this.effectiveShellEnv(), ...expanded });
+        }
+        return expanded;
+    }
+    async expandGlobArg(arg) {
+        if (!arg.globbable || !/[*?\[]/.test(arg.text))
+            return [arg.text];
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(arg.text))
+            return [arg.text];
+        const slashIndex = arg.text.lastIndexOf('/');
+        const inputDir = slashIndex >= 0 ? arg.text.slice(0, slashIndex) || '/' : '.';
+        const pattern = slashIndex >= 0 ? arg.text.slice(slashIndex + 1) : arg.text;
+        const absolute = this.shellPath(inputDir);
+        try {
+            const entries = await this.fs.readdir(absolute);
+            const matcher = globMatcher(pattern);
+            const prefix = slashIndex >= 0 ? `${arg.text.slice(0, slashIndex).replace(/\/$/, '')}/` : '';
+            const matches = entries
+                .filter((entry) => matcher(entry.name))
+                .map((entry) => `${prefix}${entry.name}`)
+                .sort();
+            return matches.length ? matches : [arg.text];
+        }
+        catch {
+            return [arg.text];
+        }
+    }
+    defaultShellEnv() {
+        return {
+            HOME: this.home,
+            PWD: this.cwd,
+            USER: this.agentName,
+            K_SESSION: this.sessionId,
+            PATH: `${this.home}/bin:/usr/local/bin:/usr/bin:/bin`,
+        };
+    }
+    effectiveShellEnv(...patches) {
+        return {
+            ...(this.shellEnvBase ?? this.defaultShellEnv()),
+            ...this.shellEnv,
+            ...Object.assign({}, ...patches.filter(Boolean)),
+        };
+    }
+    async setShellEnv(patch) {
+        for (const [name, value] of Object.entries(patch)) {
+            if (!isShellIdentifier(name))
+                throw new Error(`invalid environment variable name: ${name}`);
+            this.shellEnv[name] = value;
+        }
+        await this.saveSession({ env: this.shellEnv });
+    }
+    async unsetShellEnv(name) {
+        if (!isShellIdentifier(name))
+            throw new Error(`invalid environment variable name: ${name}`);
+        delete this.shellEnv[name];
+        await this.saveSession({ env: this.shellEnv });
+    }
+    async setShellOptions(patch) {
+        this.shellOptions = normalizeShellOptions({ ...this.shellOptions, ...patch });
+        await this.saveSession({ shell: this.shellSessionRecord() });
+    }
+    async withTemporaryShellState({ env, replaceEnv = false }, fn) {
+        const previousBase = this.shellEnvBase ? { ...this.shellEnvBase } : undefined;
+        const previous = { ...this.shellEnv };
+        const previousCwd = this.cwd;
+        const previousOptions = { ...this.shellOptions };
+        if (replaceEnv) {
+            this.shellEnvBase = {};
+            this.shellEnv = { ...(env || {}) };
+        }
+        else {
+            this.shellEnv = { ...this.shellEnv, ...(env || {}) };
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            this.shellEnvBase = previousBase;
+            this.shellEnv = previous;
+            this.cwd = previousCwd;
+            this.shellOptions = previousOptions;
+            await this.saveSession({ env: this.shellEnv });
+            await this.saveSession({ cwd: this.cwd, shell: this.shellSessionRecord() });
+        }
+    }
+    shellSessionRecord() {
+        return { options: this.shellOptions, functions: this.shellFunctions };
+    }
+    async withTemporaryShellEnvKeys(env, fn) {
+        const keys = Object.keys(env);
+        const previous = new Map(keys.map((key) => [key, this.shellEnv[key]]));
+        this.shellEnv = { ...this.shellEnv, ...env };
+        await this.saveSession({ env: this.shellEnv });
+        try {
+            return await fn();
+        }
+        finally {
+            for (const key of keys) {
+                const value = previous.get(key);
+                if (value === undefined)
+                    delete this.shellEnv[key];
+                else
+                    this.shellEnv[key] = value;
+            }
+            await this.saveSession({ env: this.shellEnv });
+        }
+    }
+    async rememberExit(result) {
+        if (result.background !== true) {
+            this.lastExitCode = shellExitCode(result);
+            await this.saveSession({ lastExitCode: this.lastExitCode });
+        }
+        return result;
+    }
+    normalizeShellSegment(segment) {
+        const group = parseShellGroup(segment.script);
+        if (group !== undefined) {
+            return {
+                ...segment,
+                cmd: '(',
+                args: [group],
+                words: ['(', group],
+                wordTokens: [shellWordToken('('), shellWordToken(group)],
+            };
+        }
+        const env = {};
+        const wordTokens = [...segment.wordTokens];
+        while (wordTokens.length && isShellAssignmentToken(wordTokens[0])) {
+            const assignment = wordTokens.shift();
+            if (!assignment)
+                continue;
+            const index = assignment.text.indexOf('=');
+            env[assignment.text.slice(0, index)] = assignment.text.slice(index + 1);
+        }
+        const words = wordTokens.map((word) => word.text);
+        if (!words.length && Object.keys(env).length) {
+            return { ...segment, cmd: 'export', args: [], words: [], wordTokens: [], env, assignmentOnly: true };
+        }
+        if (wordTokens.length === segment.wordTokens.length)
+            return segment;
+        return {
+            ...segment,
+            cmd: words[0] || segment.cmd,
+            args: words.slice(1),
+            words,
+            wordTokens,
+            env,
+            script: words.map(quoteShellWord).join(' '),
+        };
+    }
+    async withTemporaryMode(mode, fn) {
+        const previous = this.modeState;
+        const next = this.normalizeModeForAgent(mode);
+        this.modeState = next;
+        this.mode = next.name;
+        try {
+            return await fn();
+        }
+        finally {
+            this.modeState = previous;
+            this.mode = previous.name;
+        }
+    }
+    async emitShellOutput(result, extra = {}) {
+        if (result.stdout)
+            await this.emit({ type: 'process', status: 'output', text: result.stdout, stream: 'stdout', ...extra });
+        if (result.stderr)
+            await this.emit({ type: 'process', status: 'output', text: result.stderr, stream: 'stderr', ...extra });
+    }
+    boundRuntimeEvent(event) {
+        if (event.type !== 'process' || event.status !== 'output' || typeof event.text !== 'string')
+            return event;
+        const compact = compactShellOutputEventText(event.text);
+        if (!compact.truncated)
+            return event;
+        return {
+            ...event,
+            text: compact.text,
+            truncated: true,
+            originalChars: compact.originalChars,
+            omittedChars: compact.omittedChars,
+            previewChars: compact.previewChars,
+            tailChars: compact.tailChars,
+        };
+    }
+    boundShellResult(result) {
+        const next = { ...result };
+        let truncated = result.truncated === true;
+        const stdout = typeof result.stdout === 'string' ? compactShellCaptureText(result.stdout) : undefined;
+        const stderr = typeof result.stderr === 'string' ? compactShellCaptureText(result.stderr) : undefined;
+        if (stdout) {
+            next.stdout = stdout.text;
+            if (stdout.truncated || isCompactedShellText(stdout.text)) {
+                truncated = true;
+                next.stdoutTruncated = true;
+                if (stdout.truncated) {
+                    next.stdoutOriginalChars = stdout.originalChars;
+                    next.stdoutOmittedChars = stdout.omittedChars;
+                    next.stdoutTailChars = stdout.tailChars;
+                }
+            }
+        }
+        if (stderr) {
+            next.stderr = stderr.text;
+            if (stderr.truncated || isCompactedShellText(stderr.text)) {
+                truncated = true;
+                next.stderrTruncated = true;
+                if (stderr.truncated) {
+                    next.stderrOriginalChars = stderr.originalChars;
+                    next.stderrOmittedChars = stderr.omittedChars;
+                    next.stderrTailChars = stderr.tailChars;
+                }
+            }
+        }
+        if (truncated)
+            next.truncated = true;
+        return next;
+    }
+    boundShellReceiptOutput(output) {
+        if (!output || typeof output !== 'object' || Array.isArray(output))
+            return output;
+        const record = output;
+        const next = { ...record };
+        let truncated = record.truncated === true;
+        for (const field of ['stdout', 'stderr', 'text']) {
+            if (typeof record[field] !== 'string')
+                continue;
+            const compact = compactShellCaptureText(record[field]);
+            next[field] = compact.text;
+            if (compact.truncated || isCompactedShellText(compact.text)) {
+                truncated = true;
+                next[`${field}Truncated`] = true;
+                if (compact.truncated) {
+                    next[`${field}OriginalChars`] = compact.originalChars;
+                    next[`${field}OmittedChars`] = compact.omittedChars;
+                    next[`${field}TailChars`] = compact.tailChars;
+                }
+            }
+        }
+        if (truncated)
+            next.truncated = true;
+        return next;
+    }
+    async applyRedirect(result, redirect, by) {
+        if (!redirect)
+            return result;
+        const stdout = typeof result.stdout === 'string' ? result.stdout : '';
+        const stderr = typeof result.stderr === 'string' ? result.stderr : '';
+        try {
+            const redirected = await this.applyRedirectedStreams(stdout, stderr, redirect, by);
+            if (!redirected.ok)
+                return { ...result, status: 'rejected', code: 126, stdout: '', stderr: redirected.stderr };
+            const next = { ...result };
+            next.stdout = redirected.stdout;
+            next.stderr = redirected.stderr;
+            return next;
+        }
+        catch (error) {
+            const stderr = error instanceof Error ? error.message : String(error);
+            return { ...result, status: 'rejected', code: 126, stdout: '', stderr };
+        }
+    }
+    async command(name, input = {}, options = {}) {
+        const command = this.runtime.commands.get(name);
+        if (!command)
+            throw new Error(`command not found: ${name}`);
+        if (command.agent && command.agent !== this.agentName)
+            throw new Error(`command ${name} belongs to agent ${command.agent}`);
+        const by = normalizeBy(options.by || (typeof input.by === 'string' ? input.by : undefined));
+        const toolName = `command:${name}`;
+        const before = await this.runHook('tool.before', { tool: toolName, command: name, input, by });
+        if (before.rejected) {
+            await this.trace('tool.rejected', { name, input, by, reason: before.reason, hook: 'tool.before' });
+            if (before.waitingApproval)
+                return { status: 'waiting_approval', approval: before.approval, reason: before.reason };
+            throw new Error(before.reason || `tool.before rejected ${toolName}`);
+        }
+        const currentInput = recordField(before.current, 'input') || input;
+        const authority = decideTool({ mode: this.modeState, tool: toolName, command: name });
+        if (!authority.ok) {
+            await this.trace('tool.rejected', { name, input: currentInput, by, reason: authority.reason, mode: this.mode });
+            throw new Error(authority.reason);
+        }
+        const toolUseId = id('tool');
+        const ctx = this.runtime.runtimeContext(this, { kind: 'command', name, input: currentInput, args: currentInput });
+        await this.emit({ type: 'tool', status: 'requested', tool: toolName, input: currentInput, opId: toolUseId });
+        await this.trace('tool.started', { name, input: currentInput, by, toolUseId });
+        let result;
+        if (command.kind === 'shell') {
+            const argv = stringArrayField(currentInput, 'argv') || [];
+            const invocationMode = command.readonly === true
+                ? 'readonly'
+                : typeof command.mode === 'string'
+                    ? command.mode
+                    : undefined;
+            const runShell = () => this.withTemporaryShellState({ env: positionalShellEnv(name, argv) }, () => this.execInternal(String(command.script ?? ''), { by: options.by || `command:${name}` }));
+            result = invocationMode ? await this.withTemporaryMode(invocationMode, runShell) : await runShell();
+        }
+        else if (command.kind === 'markdown') {
+            const args = Object.keys(currentInput).length ? `\n\nInput:\n${JSON.stringify(currentInput, null, 2)}` : '';
+            const invocationMode = command.readonly === true
+                ? 'readonly'
+                : typeof command.mode === 'string'
+                    ? command.mode
+                    : undefined;
+            const runMarkdown = () => this.run(`${String(command.prompt ?? '')}${args}`, { by: options.by || `command:${name}`, model: typeof command.model === 'string' ? command.model : undefined });
+            result = invocationMode ? await this.withTemporaryMode(invocationMode, runMarkdown) : await runMarkdown();
+        }
+        else {
+            if (!command.handler)
+                throw new Error(`command has no handler: ${name}`);
+            const handler = command.handler;
+            result = await this.withFsActor(options.by ? by : `command:${name}`, () => Promise.resolve(handler(ctx, currentInput)));
+        }
+        const after = await this.runHook('tool.after', { tool: toolName, command: name, input: currentInput, result, by });
+        if (after.rejected) {
+            await this.trace('tool.output_rejected', { name, by, reason: after.reason, hook: 'tool.after' });
+            if (after.waitingApproval)
+                return { status: 'waiting_approval', approval: after.approval, reason: after.reason };
+            throw new Error(after.reason || `tool.after rejected ${toolName}`);
+        }
+        result = 'result' in after.current ? after.current.result : result;
+        await this.trace('tool.ended', { name, resultType: resultType(result), toolUseId });
+        await this.emit({ type: 'tool', status: 'completed', tool: toolName, result, opId: toolUseId });
+        return result;
+    }
+    async processes() {
+        return this.vprocess.processes();
+    }
+    async jobs() {
+        return this.vprocess.jobs();
+    }
+    remoteCwd() {
+        return this.runtime.realPath(this.cwd);
+    }
+    hookCwd() {
+        return this.kstate.realRootPath(this.cwd) || this.cwd;
+    }
+    shellPath(path) {
+        if (!path)
+            return this.cwd;
+        if (path === '~' || path.startsWith('~/') || path.startsWith('/'))
+            return path;
+        return `${this.cwd.replace(/\/$/, '')}/${path}`;
+    }
+    async appendMessage(message) {
+        await this.assertWritableSession();
+        return this.messageLog.append(message);
+    }
+    async messagesForModel() {
+        return this.messageLog.forModel();
+    }
+    get messages() {
+        return this.messageLog.view();
+    }
+    async checkpoint({ label } = {}) {
+        await this.assertWritableSession();
+        const traceRows = await this.kstate.trace(this.sessionId);
+        const messages = await this.kstate.readSessionJsonl(this.sessionId, 'messages.full.jsonl');
+        const checkpoint = {
+            id: id('checkpoint'),
+            label,
+            createdAt: now(),
+            sessionId: this.sessionId,
+            traceSeq: traceRows.at(-1)?.traceSeq ?? -1,
+            messageSeq: messages.at(-1)?.seq ?? -1,
+            cwd: this.cwd,
+            env: { ...this.shellEnv },
+            shell: this.shellSessionRecord(),
+            lastExitCode: this.lastExitCode,
+            mode: this.mode,
+            scope: this.modeState.scope,
+            system: this.system,
+        };
+        await this.assertWritableSession();
+        await this.kstate.writeSessionJson(this.sessionId, `checkpoints/${checkpoint.id}.json`, checkpoint);
+        await this.trace('checkpoint.created', checkpoint);
+        return checkpoint;
+    }
+    async fork({ from, mode = this.mode, scope, disk = 'shared', hooks = true } = {}) {
+        await this.assertWritableSession();
+        const forkId = id(`${this.sessionId}.fork`);
+        const forkMode = scope
+            ? { name: typeof mode === 'string' ? mode : mode.name, scope }
+            : mode;
+        const forked = new AgentSession({
+            computer: this.runtime,
+            agentName: this.agentName,
+            sessionId: forkId,
+            mode: forkMode,
+            disk,
+        });
+        try {
+            await forked.init();
+            if (hooks)
+                this.runtime.installHooks(forked);
+            const checkpoint = typeof from === 'string'
+                ? await this.kstate.readSessionJson(this.sessionId, `checkpoints/${from}.json`, undefined)
+                : from;
+            await this.assertWritableSession();
+            const maxSeq = typeof checkpoint?.messageSeq === 'number' ? checkpoint.messageSeq : undefined;
+            for (const name of ['messages.full.jsonl', 'messages.current.jsonl']) {
+                const rows = await this.kstate.readSessionJsonl(this.sessionId, name);
+                const selected = maxSeq === undefined ? rows : rows.filter((row) => (row.seq ?? -1) <= maxSeq);
+                await this.assertWritableSession();
+                await this.kstate.writeSessionJsonl(forkId, name, selected);
+            }
+            const modeState = forked.normalizeModeForAgent(forkMode);
+            forked.modeState = modeState;
+            forked.mode = modeState.name;
+            forked.cwd = typeof checkpoint?.cwd === 'string' ? checkpoint.cwd : this.cwd;
+            forked.shellEnv = recordStringMap(recordField(checkpoint || {}, 'env') || this.shellEnv);
+            const checkpointShell = recordField(checkpoint || {}, 'shell') || this.shellSessionRecord();
+            forked.shellOptions = normalizeShellOptions(recordField(checkpointShell, 'options'));
+            forked.shellFunctions = recordStringMap(recordField(checkpointShell, 'functions'));
+            forked.lastExitCode = typeof checkpoint?.lastExitCode === 'number' ? checkpoint.lastExitCode : this.lastExitCode;
+            forked.system = typeof checkpoint?.system === 'string' ? checkpoint.system : this.system;
+            await this.assertWritableSession();
+            await forked.saveSession({
+                parentSessionId: this.sessionId,
+                disk,
+                forkedFrom: checkpoint?.id,
+                mode: modeState.name,
+                scope: modeState.scope,
+                cwd: forked.cwd,
+                env: forked.shellEnv,
+                shell: forked.shellSessionRecord(),
+                lastExitCode: forked.lastExitCode,
+                system: forked.system,
+                hooks: hooks ? 'inherit' : 'none',
+            });
+            await this.assertWritableSession();
+            this.runtime.sessions.set(`${this.agentName}\0${forkId}`, forked);
+            await this.trace('session.forked', { childSessionId: forkId, mode: modeState.name, scope: modeState.scope, disk, from: checkpoint?.id });
+            return forked;
+        }
+        catch (error) {
+            this.runtime.sessions.delete(`${this.agentName}\0${forkId}`);
+            await forked.abandonStartup().catch(() => undefined);
+            await this.kstate.removeSession(forkId).catch(() => undefined);
+            throw error;
+        }
+    }
+    async sealUnfinishedTools() {
+        return sealUnfinishedTools(this);
+    }
+    async sealUnfinishedToolEvents() {
+        return sealUnfinishedToolEvents(this);
+    }
+    async sealInterruptedTurns() {
+        return sealInterruptedTurns(this);
+    }
+}
+function parseShellGroup(script) {
+    const text = script.trim();
+    if (!text.startsWith('(') || !text.endsWith(')'))
+        return undefined;
+    let quote;
+    let escaping = false;
+    let substitutionDepth = 0;
+    let depth = 0;
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        const next = text[index + 1];
+        if (escaping) {
+            escaping = false;
+            continue;
+        }
+        if (char === '\\' && quote !== "'") {
+            escaping = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote)
+                quote = undefined;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === '$' && next === '(') {
+            substitutionDepth += 1;
+            index += 1;
+            continue;
+        }
+        if (substitutionDepth > 0) {
+            if (char === '(')
+                substitutionDepth += 1;
+            else if (char === ')')
+                substitutionDepth -= 1;
+            continue;
+        }
+        if (char === '(')
+            depth += 1;
+        else if (char === ')') {
+            depth -= 1;
+            if (depth === 0 && index !== text.length - 1)
+                return undefined;
+            if (depth < 0)
+                return undefined;
+        }
+    }
+    return depth === 0 ? text.slice(1, -1).trim() : undefined;
+}
+function isFsEffectTrace(type) {
+    return type === 'fs.write'
+        || type === 'fs.append'
+        || type === 'fs.mkdir'
+        || type === 'fs.rm'
+        || type === 'fs.rename'
+        || type === 'fs.symlink'
+        || type === 'fs.chmod'
+        || type === 'fs.utime';
+}
+function fsReceiptTarget(type, data) {
+    if (type === 'fs.rename')
+        return `${String(data.from || '')} -> ${String(data.to || '')}`;
+    return String(data.path || '');
+}
+function fsReceiptInput(type, data) {
+    if (type === 'fs.write')
+        return { path: data.path, bytes: data.bytes };
+    if (type === 'fs.append')
+        return { path: data.path, bytes: data.bytes };
+    if (type === 'fs.rename')
+        return { from: data.from, to: data.to };
+    if (type === 'fs.rm')
+        return { path: data.path, recursive: data.recursive, force: data.force };
+    if (type === 'fs.symlink')
+        return { path: data.path, target: data.target };
+    if (type === 'fs.chmod')
+        return { path: data.path, mode: data.mode };
+    if (type === 'fs.utime')
+        return { path: data.path, mtime: data.mtime };
+    return { path: data.path };
+}
+function modelProviderSummary(provider) {
+    if (!provider)
+        return undefined;
+    const summary = {};
+    for (const key of ['name', 'model', 'requestId', 'cacheRef']) {
+        const value = provider[key];
+        if (typeof value === 'string')
+            summary[key] = value;
+    }
+    return Object.keys(summary).length ? summary : undefined;
+}
+function countHandlerMap(map) {
+    let total = 0;
+    for (const handlers of map.values())
+        total += handlers.length;
+    return total;
+}
+function appendBoundedShellCapture(current, next) {
+    if (!next)
+        return current;
+    return compactShellCaptureText(`${current}${next}`).text;
+}
+function compactShellCaptureText(text) {
+    return compactText(String(text), MAX_SHELL_CAPTURE_CHARS, 0);
+}
+function compactShellOutputEventText(text) {
+    return compactText(String(text), MAX_SHELL_OUTPUT_EVENT_CHARS, SHELL_OUTPUT_EVENT_PREVIEW_CHARS);
+}
+function compactText(text, limit, requestedPreviewChars) {
+    const originalChars = text.length;
+    if (originalChars <= limit) {
+        return { text, truncated: false, originalChars, omittedChars: 0, previewChars: requestedPreviewChars || undefined, tailChars: originalChars };
+    }
+    const previewChars = Math.min(requestedPreviewChars, Math.max(0, limit));
+    let tailChars = Math.max(0, limit - previewChars);
+    let omittedChars = Math.max(0, originalChars - previewChars - tailChars);
+    let marker = truncationMarker(omittedChars);
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        tailChars = Math.max(0, limit - previewChars - marker.length);
+        omittedChars = Math.max(0, originalChars - previewChars - tailChars);
+        const nextMarker = truncationMarker(omittedChars);
+        if (nextMarker.length === marker.length) {
+            marker = nextMarker;
+            break;
+        }
+        marker = nextMarker;
+    }
+    if (marker.length >= limit) {
+        const tail = text.slice(-limit);
+        return { text: tail, truncated: true, originalChars, omittedChars: originalChars - tail.length, tailChars: tail.length };
+    }
+    tailChars = Math.max(0, limit - previewChars - marker.length);
+    omittedChars = Math.max(0, originalChars - previewChars - tailChars);
+    const preview = previewChars > 0 ? text.slice(0, previewChars) : '';
+    const tail = tailChars > 0 ? text.slice(-tailChars) : '';
+    return {
+        text: `${preview}${truncationMarker(omittedChars)}${tail}`,
+        truncated: true,
+        originalChars,
+        omittedChars,
+        previewChars: previewChars || undefined,
+        tailChars,
+    };
+}
+function truncationMarker(omittedChars) {
+    return `\n...[truncated ${omittedChars} chars]...\n`;
+}
+function isCompactedShellText(text) {
+    return /\n\.\.\.\[truncated \d+ chars\]\.\.\.\n/.test(text);
+}
+function commandErrorText(command, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.startsWith(`${command}:`) ? message : `${command}: ${message}`;
+}
+function isHelpArg(value) {
+    return value === '--help' || value === '-h';
+}
+function isExpiredWorker(worker) {
+    const expiresAt = typeof worker.expiresAt === 'string' ? Date.parse(worker.expiresAt) : Number.NaN;
+    return Number.isFinite(expiresAt) && expiresAt <= Date.now();
+}
+function contentKind(block) {
+    if (block.type === 'text')
+        return 'text';
+    if (block.type === 'reasoning' || block.type === 'thinking')
+        return 'reasoning';
+    if (block.type === 'image')
+        return 'image';
+    if (block.type === 'audio')
+        return 'audio';
+    if (block.type === 'video')
+        return 'video';
+    return 'data';
+}
+function processStatus(status, code) {
+    if (status === 'uncertain')
+        return 'uncertain';
+    if (status === 'cancelled' || status === 'aborted')
+        return 'cancelled';
+    if (status === 'failed' || status === 'rejected')
+        return 'failed';
+    if (typeof code === 'number')
+        return code === 0 ? 'completed' : 'failed';
+    return status === 'committed' || status === 'completed' ? 'completed' : 'failed';
+}
+function turnStatus(status) {
+    if (status === 'queued')
+        return 'queued';
+    if (status === 'running')
+        return 'running';
+    if (status === 'waiting_approval')
+        return 'waiting_approval';
+    if (status === 'blocked')
+        return 'blocked';
+    if (status === 'failed')
+        return 'failed';
+    if (status === 'cancelled')
+        return 'cancelled';
+    return 'completed';
+}
+function shouldExpandBraces(token) {
+    let hasUnquotedBrace = false;
+    for (const part of token.parts) {
+        if (!part.text.includes('{') && !part.text.includes('}'))
+            continue;
+        if (part.quote)
+            return false;
+        hasUnquotedBrace = true;
+    }
+    return hasUnquotedBrace;
+}
+function updatePathList(current, entry, side) {
+    const normalized = entry.replace(/\/+$/, '') || '/';
+    const parts = String(current || '').split(':').filter(Boolean).filter((part) => part !== normalized);
+    return side === 'prepend'
+        ? [normalized, ...parts].join(':')
+        : [...parts, normalized].join(':');
+}
+//# sourceMappingURL=agent-session.js.map