omk-agent-core 0.98.1 → 0.98.3

package/dist/harness/agent-harness.js

@@ -1,36 +1,30 @@
 import { isContextOverflow, streamSimple, } from "omk-ai";
 import { runAgentLoop, runAgentLoopContinue } from "../agent-loop.js";
-import { collectEntriesForBranchSummary, generateBranchSummary } from "./compaction/branch-summarization.js";
+import { assertAbortAllowed, describeAbortDelivery } from "./abort-delivery.js";
+import { collectEntriesForBranchSummary } from "./compaction/branch-summarization.js";
 import { compact, DEFAULT_COMPACTION_SETTINGS, estimateContextTokens, prepareCompaction, shouldCompact, } from "./compaction/compaction.js";
+import { DeferredCommandQueue } from "./deferred-commands.js";
 import { HarnessSessionFacade } from "./harness-session.js";
 import { convertToLlm, createFailureMessage, createUserMessage } from "./messages.js";
 import { findDuplicateNames } from "./name-validation.js";
+import { OperationLifecycleController, } from "./operation-lifecycle-controller.js";
+import { PROMPT_FAMILY_KINDS, } from "./operation-lifecycle-types.js";
+import { classifyAssistantOutcome, classifyAttemptFailure, classifyAttemptOutcome, classifyNavigateTreeOutcome, collectStepErrors, combineBoundaryErrors, normalizeHarnessError, resolveOperationFailure, resolveOperationOutcome, } from "./operation-outcome.js";
 import { formatPromptTemplateInvocation } from "./prompt-templates.js";
+import { uuidv7 } from "./session/uuid.js";
+import { SessionWriteCoordinator } from "./session-write-coordinator.js";
 import { formatSkillInvocation } from "./skills.js";
 import { applyStreamOptionsPatch, cloneStreamOptions, mergeHeaders } from "./stream-options.js";
+import { SubscriberFanout } from "./subscriber-fanout.js";
 import { createSummarizationRetry } from "./summarization-retry.js";
-import { AgentHarnessError, BranchSummaryError, CompactionError, SessionError, toError } from "./types.js";
-const SUBSCRIBER_EVENT_TYPE = "*";
-function normalizeHarnessError(error, fallbackCode) {
-    if (error instanceof AgentHarnessError)
-        return error;
-    const cause = toError(error);
-    if (cause instanceof SessionError)
-        return new AgentHarnessError("session", cause.message, cause);
-    if (cause instanceof CompactionError)
-        return new AgentHarnessError("compaction", cause.message, cause);
-    if (cause instanceof BranchSummaryError)
-        return new AgentHarnessError("branch_summary", cause.message, cause);
-    return new AgentHarnessError(fallbackCode, cause.message, cause);
-}
+import { resolveNavigationTarget, runBranchSummary } from "./tree-navigation.js";
+import { AgentHarnessError, toError } from "./types.js";
 export class AgentHarness {
     env;
     session;
     sessionFacade;
-    phase = "idle";
-    runAbortController;
-    runPromise;
-    pendingSessionWrites = [];
+    lifecycle;
+    sessionWrites;
     model;
     thinkingLevel;
     systemPrompt;
@@ -46,10 +40,17 @@ export class AgentHarness {
     followUpQueueMode;
     nextTurnQueue = [];
     handlers = new Map();
+    subscribers = new SubscriberFanout();
+    deferredCommands = new DeferredCommandQueue(() => this.lifecycle.getSnapshot().tag === "idle");
     constructor(options) {
         this.env = options.env;
         this.session = options.session;
-        this.sessionFacade = new HarnessSessionFacade(this.session, () => this.phase, this.pendingSessionWrites);
+        this.sessionWrites = new SessionWriteCoordinator(this.session);
+        this.lifecycle = new OperationLifecycleController({
+            createOperationId: () => uuidv7(),
+            now: () => Date.now(),
+        });
+        this.sessionFacade = new HarnessSessionFacade(this.session, () => this.currentPhase(), this.sessionWrites);
         this.resources = options.resources ?? {};
         this.streamOptions = cloneStreamOptions(options.streamOptions);
         this.compactionSettings = { ...DEFAULT_COMPACTION_SETTINGS, ...options.compaction };
@@ -70,24 +71,15 @@ export class AgentHarness {
         this.followUpQueueMode = options.followUpMode ?? "one-at-a-time";
     }
     async emitOwn(event, signal) {
-        for (const listener of this.handlers.get(SUBSCRIBER_EVENT_TYPE) ?? []) {
-            try {
-                await listener(event, signal);
-            }
-            catch (error) {
-                throw normalizeHarnessError(error, "hook");
-            }
-        }
+        await this.emitAny(event, signal);
     }
+    /** Subscriber fan-out; the self-wait barrier lives in `SubscriberFanout`. */
     async emitAny(event, signal) {
-        for (const listener of this.handlers.get(SUBSCRIBER_EVENT_TYPE) ?? []) {
-            try {
-                await listener(event, signal);
-            }
-            catch (error) {
-                throw normalizeHarnessError(error, "hook");
-            }
-        }
+        await this.subscribers.emit(event, this.lifecycle.getCurrentOperation()?.operationId, signal);
+    }
+    /** Fail closed when an awaited listener tries to wait on its own operation. */
+    rejectCurrentOperationSelfWait(api) {
+        this.subscribers.assertNotSelfWait(api, this.lifecycle.getCurrentOperation()?.operationId);
     }
     async emitHook(event) {
         const handlers = this.handlers.get(event.type);
@@ -156,23 +148,92 @@ export class AgentHarness {
             nextTurn: [...this.nextTurnQueue],
         });
     }
-    startRunPromise() {
-        let finish = () => { };
-        const runPromise = new Promise((resolve) => {
-            finish = resolve;
+    /**
+     * Facade write-gate vocabulary mapped from lifecycle state. `settling` maps
+     * to "idle": the queue is drained by the settlement finalizer first, and
+     * listener writes persist after it through the coordinator tail.
+     */
+    currentPhase() {
+        const snapshot = this.lifecycle.getSnapshot();
+        if (snapshot.tag !== "active")
+            return "idle";
+        switch (snapshot.operation.kind) {
+            case "manual_compaction":
+                return "compaction";
+            case "tree_navigation":
+                return "branch_summary";
+            default:
+                return "turn";
+        }
+    }
+    /** Config writes persist immediately outside an active operation and queue during one. */
+    async persistConfigChange(write) {
+        if (this.lifecycle.getSnapshot().tag !== "active") {
+            await this.sessionWrites.persistAfterPending(write);
+        }
+        else {
+            this.sessionWrites.enqueue(write);
+        }
+    }
+    /**
+     * Single wrapper for every public operation: begin a lease, run the body,
+     * then settle exactly once. The final flush and the `settled` event happen
+     * inside the settling barrier; a finalizer failure never reports success.
+     */
+    async runOperation(kind, fallbackCode, body, classifyResult) {
+        const lease = this.lifecycle.begin(kind);
+        let result;
+        let bodyError;
+        // Everything after a successful begin() runs inside one capture region. A
+        // throwing `operation_started` listener must not escape before settle(),
+        // or the lifecycle would stay active and wedge the harness at "busy".
+        try {
+            await this.emitOwn({ type: "operation_started", operation: lease.operation });
+            result = await body(lease);
+        }
+        catch (error) {
+            bodyError = error;
+        }
+        // The final flush precedes classification: a persistence failure after a
+        // provider success must never record or report a completed operation.
+        let flushError;
+        try {
+            await this.sessionWrites.flush();
+        }
+        catch (error) {
+            flushError = error;
+        }
+        const outcome = resolveOperationOutcome({
+            signalAborted: lease.signal.aborted,
+            result,
+            bodyError,
+            flushError,
+            classifyResult,
+            fallbackCode,
         });
-        this.runPromise = runPromise;
-        return {
-            runPromise,
-            finishRunPromise: () => {
-                // A settled/agent_end listener may have started a new run while this
-                // one was still unwinding; only clear state still owned by this run.
-                if (this.runPromise === runPromise) {
-                    this.runPromise = undefined;
-                }
-                finish();
-            },
-        };
+        let settleError;
+        try {
+            await this.lifecycle.settle(lease, outcome, async () => {
+                await this.emitOwn({
+                    type: "settled",
+                    nextTurnCount: this.nextTurnQueue.length,
+                    operationId: lease.operation.operationId,
+                    outcome,
+                    attemptCount: this.lifecycle.getAttemptSummaries(lease).length,
+                }, lease.signal);
+            });
+        }
+        catch (error) {
+            settleError = error;
+        }
+        // Deferred commands registered from this operation's callbacks run now that
+        // the lifecycle is idle. Not awaited: this call's result must not depend on
+        // work a listener scheduled.
+        void this.deferredCommands.drain();
+        const failure = resolveOperationFailure({ bodyError, flushError, settleError, fallbackCode });
+        if (failure !== undefined)
+            throw failure;
+        return result;
     }
     async createTurnState() {
         const context = await this.session.buildContext();
@@ -258,7 +319,7 @@ export class AgentHarness {
             throw normalizeHarnessError(error, "hook");
         }
     }
-    createLoopConfig(getTurnState, setTurnState) {
+    createLoopConfig(getTurnState, setTurnState, lease) {
         const turnState = getTurnState();
         return {
             model: turnState.model,
@@ -292,7 +353,13 @@ export class AgentHarness {
                     : undefined;
             },
             prepareNextTurn: async () => {
-                await this.flushPendingSessionWrites();
+                await this.sessionWrites.flush();
+                if (lease) {
+                    const snapshot = this.lifecycle.getSnapshot();
+                    if (snapshot.tag === "active" && snapshot.stage === "save_point") {
+                        this.lifecycle.setStage(lease, "attempt_running");
+                    }
+                }
                 const nextTurnState = await this.createTurnState();
                 setTurnState(nextTurnState);
                 return {
@@ -316,40 +383,7 @@ export class AgentHarness {
         if (missing.length > 0)
             throw new AgentHarnessError("invalid_argument", `Unknown tool(s): ${missing.join(", ")}`);
     }
-    async flushPendingSessionWrites() {
-        while (this.pendingSessionWrites.length > 0) {
-            const write = this.pendingSessionWrites[0];
-            if (write.type === "message") {
-                await this.session.appendMessage(write.message);
-            }
-            else if (write.type === "model_change") {
-                await this.session.appendModelChange(write.provider, write.modelId);
-            }
-            else if (write.type === "thinking_level_change") {
-                await this.session.appendThinkingLevelChange(write.thinkingLevel);
-            }
-            else if (write.type === "active_tools_change") {
-                await this.session.appendActiveToolsChange(write.activeToolNames);
-            }
-            else if (write.type === "custom") {
-                await this.session.appendCustomEntry(write.customType, write.data);
-            }
-            else if (write.type === "custom_message") {
-                await this.session.appendCustomMessageEntry(write.customType, write.content, write.display, write.details);
-            }
-            else if (write.type === "label") {
-                await this.session.appendLabel(write.targetId, write.label);
-            }
-            else if (write.type === "session_info") {
-                await this.session.appendSessionName(write.name ?? "");
-            }
-            else if (write.type === "leaf") {
-                await this.session.getStorage().setLeafId(write.targetId);
-            }
-            this.pendingSessionWrites.shift();
-        }
-    }
-    async handleAgentEvent(event, signal) {
+    async handleAgentEvent(event, signal, lease) {
         if (event.type === "message_end") {
             await this.session.appendMessage(event.message);
             await this.emitAny(event, signal);
@@ -363,39 +397,48 @@ export class AgentHarness {
             catch (error) {
                 eventError = error;
             }
-            const hadPendingMutations = this.pendingSessionWrites.length > 0;
-            await this.flushPendingSessionWrites();
-            if (eventError)
-                throw eventError;
+            // The flush runs even after a failing listener so accepted writes are
+            // not stranded; a failing flush must then report next to that listener
+            // error, not in place of it.
+            const hadPendingMutations = this.sessionWrites.hasPending();
+            let flushError;
+            try {
+                await this.sessionWrites.flush();
+            }
+            catch (error) {
+                flushError = error;
+            }
+            if (lease) {
+                const snapshot = this.lifecycle.getSnapshot();
+                if (snapshot.tag === "active" && snapshot.stage === "attempt_running") {
+                    this.lifecycle.setStage(lease, "save_point");
+                }
+            }
+            const failure = combineBoundaryErrors([eventError, flushError], "turn_end listener failed and the save-point flush failed", "hook");
+            if (failure !== undefined)
+                throw failure;
             await this.emitOwn({ type: "save_point", hadPendingMutations });
             return;
         }
         if (event.type === "agent_end") {
-            // Finish this run's cleanup before flipping to "idle": listeners observing
-            // agent_end/settled may start the next prompt() immediately, and that run
-            // must not inherit state still owned by the run that just completed.
-            await this.flushPendingSessionWrites();
-            if (this.runAbortController && this.runAbortController.signal === signal) {
-                this.runAbortController = undefined;
-            }
-            this.phase = "idle";
+            // agent_end is an attempt event: flush its accepted writes, but lifecycle
+            // settlement and the settled event belong to OperationLease.settle().
+            await this.sessionWrites.flush();
             await this.emitAny(event, signal);
-            await this.emitOwn({ type: "settled", nextTurnCount: this.nextTurnQueue.length }, signal);
             return;
         }
         await this.emitAny(event, signal);
     }
-    async emitRunFailure(model, error, aborted, signal, completedMessages) {
+    async emitRunFailure(model, error, aborted, signal, completedMessages, lease) {
         const failureMessage = createFailureMessage(model, error, aborted);
         const messages = [...completedMessages, failureMessage];
-        await this.handleAgentEvent({ type: "message_start", message: failureMessage }, signal);
-        await this.handleAgentEvent({ type: "message_end", message: failureMessage }, signal);
-        await this.handleAgentEvent({ type: "turn_end", message: failureMessage, toolResults: [] }, signal);
-        await this.handleAgentEvent({ type: "agent_end", messages }, signal);
+        await this.handleAgentEvent({ type: "message_start", message: failureMessage }, signal, lease);
+        await this.handleAgentEvent({ type: "message_end", message: failureMessage }, signal, lease);
+        await this.handleAgentEvent({ type: "turn_end", message: failureMessage, toolResults: [] }, signal, lease);
+        await this.handleAgentEvent({ type: "agent_end", messages }, signal, lease);
         return messages;
     }
-    async executeTurn(turnState, text, options) {
-        const runOwner = this.runPromise;
+    async executeTurn(lease, turnState, text, options) {
         let messages = [createUserMessage(text, options?.images)];
         if (this.nextTurnQueue.length > 0) {
             const queuedMessages = this.nextTurnQueue.splice(0);
@@ -417,65 +460,99 @@ export class AgentHarness {
         });
         if (beforeResult?.messages)
             messages = [...messages, ...beforeResult.messages];
-        const result = await this.executeAgentRun(turnState, this.createContext(turnState, beforeResult?.systemPrompt), messages);
-        return await this.recoverContextOverflow(result, runOwner);
+        const result = await this.executeAgentRun(lease, "initial", turnState, this.createContext(turnState, beforeResult?.systemPrompt), messages);
+        return await this.recoverContextOverflow(lease, result);
+    }
+    /**
+     * Sole attempt boundary: begin, announce, run, classify, close, announce, flush.
+     *
+     * Once `beginAttempt()` succeeds the attempt is closed exactly once on every
+     * path, so `count(attempt_started) == count(attempt_finished)` holds even when
+     * the `attempt_started` observer throws. `attempt_finished` is emitted only
+     * after the attempt is already closed, so a throwing observer can fail the
+     * operation but can never reopen committed attempt state. The closing flush
+     * is not a `finally`: a `finally` that awaits a throwing flush would replace
+     * the body error, hiding the provider or listener failure from the audit trail.
+     */
+    async runAttempt(lease, reason, body, classify) {
+        const attemptLease = this.lifecycle.beginAttempt(lease, reason);
+        let result;
+        let bodyError;
+        try {
+            await this.emitOwn({ type: "attempt_started", attempt: attemptLease.attempt }, lease.signal);
+            result = await body(attemptLease);
+        }
+        catch (error) {
+            bodyError = error;
+        }
+        const outcome = bodyError === undefined ? classify(result) : classifyAttemptFailure(bodyError);
+        this.lifecycle.finishAttempt(lease, attemptLease, outcome);
+        let observerError;
+        try {
+            await this.emitOwn({ type: "attempt_finished", summary: this.lifecycle.getAttemptSummary(lease, attemptLease) }, lease.signal);
+        }
+        catch (error) {
+            observerError = error;
+        }
+        let flushError;
+        try {
+            await this.sessionWrites.flush();
+        }
+        catch (error) {
+            flushError = error;
+        }
+        const failure = combineBoundaryErrors([bodyError, observerError, flushError], "Attempt failed and its attempt_finished reporting or closing flush failed", "unknown");
+        if (failure !== undefined)
+            throw failure;
+        return result;
     }
-    async executeAgentRun(turnState, context, initialMessages) {
+    async executeAgentRun(lease, reason, turnState, context, initialMessages) {
         let activeTurnState = turnState;
-        const abortController = new AbortController();
-        const getTurnState = () => activeTurnState;
-        const setTurnState = (nextTurnState) => {
-            activeTurnState = nextTurnState;
-        };
-        this.runAbortController = abortController;
-        const completedMessages = [];
-        const emit = async (event) => {
-            if (event.type === "message_end")
-                completedMessages.push(event.message);
-            await this.handleAgentEvent(event, abortController.signal);
-        };
-        const runResultPromise = (async () => {
+        return await this.runAttempt(lease, reason, async (attemptLease) => {
+            const signal = attemptLease.signal;
+            const getTurnState = () => activeTurnState;
+            const setTurnState = (nextTurnState) => {
+                activeTurnState = nextTurnState;
+            };
+            const completedMessages = [];
+            const emit = async (event) => {
+                if (event.type === "message_end")
+                    completedMessages.push(event.message);
+                await this.handleAgentEvent(event, signal, lease);
+            };
+            let newMessages;
             try {
-                const loopConfig = this.createLoopConfig(getTurnState, setTurnState);
+                const loopConfig = this.createLoopConfig(getTurnState, setTurnState, lease);
                 const streamFn = this.createStreamFn(getTurnState);
-                return initialMessages
-                    ? await runAgentLoop(initialMessages, context, loopConfig, emit, abortController.signal, streamFn)
-                    : await runAgentLoopContinue(context, loopConfig, emit, abortController.signal, streamFn);
+                newMessages = initialMessages
+                    ? await runAgentLoop(initialMessages, context, loopConfig, emit, signal, streamFn)
+                    : await runAgentLoopContinue(context, loopConfig, emit, signal, streamFn);
             }
             catch (error) {
                 try {
-                    return await this.emitRunFailure(activeTurnState.model, error, abortController.signal.aborted, abortController.signal, completedMessages);
+                    newMessages = await this.emitRunFailure(activeTurnState.model, error, signal.aborted, signal, completedMessages, lease);
                 }
                 catch (failureError) {
                     const cause = new AggregateError([toError(error), toError(failureError)], "Agent run failed and failure reporting failed");
                     throw new AgentHarnessError("unknown", cause.message, cause);
                 }
             }
-        })();
-        try {
-            const newMessages = await runResultPromise;
             for (let i = newMessages.length - 1; i >= 0; i--) {
                 const message = newMessages[i];
                 if (message.role === "assistant")
                     return message;
             }
             throw new AgentHarnessError("invalid_state", "AgentHarness prompt completed without an assistant message");
-        }
-        finally {
-            try {
-                await this.flushPendingSessionWrites();
-            }
-            finally {
-                if (this.runAbortController === abortController)
-                    this.runAbortController = undefined;
-            }
-        }
-    }
-    async recoverContextOverflow(message, runOwner) {
-        if (this.runPromise !== runOwner ||
-            this.phase !== "idle" ||
-            !this.compactionSettings.enabled ||
-            !isContextOverflow(message, this.model.contextWindow)) {
+        }, (message) => classifyAttemptOutcome(message, activeTurnState.model.contextWindow));
+    }
+    /**
+     * One-shot overflow recovery inside the originating operation. The lease is
+     * proof that this operation still owns the harness, so no run-ownership or
+     * phase re-check is needed; a strict lifecycle makes a newer operation
+     * starting mid-recovery impossible.
+     */
+    async recoverContextOverflow(lease, message) {
+        if (!this.compactionSettings.enabled || !isContextOverflow(message, this.model.contextWindow)) {
             return message;
         }
         if (!this.getApiKeyAndHeaders)
@@ -491,16 +568,15 @@ export class AgentHarness {
             return message;
         }
         await this.session.moveTo(leaf.parentId);
-        this.phase = "retry";
+        this.lifecycle.setStage(lease, "recovering_overflow");
         try {
-            const compacted = await this.runCompaction({ automatic: true });
+            const compacted = await this.runCompaction({ automatic: true, signal: lease.signal });
             if (!compacted) {
                 await this.session.moveTo(leafId);
-                this.phase = "idle";
                 return message;
             }
             const turnState = await this.createTurnState();
-            return await this.executeAgentRun(turnState, this.createContext(turnState));
+            return await this.executeAgentRun(lease, "context_overflow_recovery", turnState, this.createContext(turnState));
         }
         catch (error) {
             await this.session.moveTo(leafId);
@@ -508,76 +584,49 @@ export class AgentHarness {
         }
     }
     async prompt(text, options) {
-        if (this.phase !== "idle")
-            throw new AgentHarnessError("busy", "AgentHarness is busy");
-        this.phase = "turn";
-        const { runPromise, finishRunPromise } = this.startRunPromise();
-        try {
+        return this.runOperation("prompt", "unknown", async (lease) => {
             const turnState = await this.createTurnState();
-            return await this.executeTurn(turnState, text, options);
-        }
-        catch (error) {
-            // Only reset the phase if this call still owns the run; a listener may
-            // have started the next run while this one was unwinding.
-            if (this.runPromise === runPromise)
-                this.phase = "idle";
-            throw normalizeHarnessError(error, "unknown");
-        }
-        finally {
-            finishRunPromise();
-        }
+            return await this.executeTurn(lease, turnState, text, options);
+        }, classifyAssistantOutcome);
     }
     async skill(name, additionalInstructions) {
-        if (this.phase !== "idle")
-            throw new AgentHarnessError("busy", "AgentHarness is busy");
-        this.phase = "turn";
-        const { runPromise, finishRunPromise } = this.startRunPromise();
-        try {
+        return this.runOperation("skill", "unknown", async (lease) => {
             const turnState = await this.createTurnState();
             const skill = (turnState.resources.skills ?? []).find((candidate) => candidate.name === name);
             if (!skill)
                 throw new AgentHarnessError("invalid_argument", `Unknown skill: ${name}`);
-            return await this.executeTurn(turnState, formatSkillInvocation(skill, additionalInstructions));
-        }
-        catch (error) {
-            if (this.runPromise === runPromise)
-                this.phase = "idle";
-            throw normalizeHarnessError(error, "unknown");
-        }
-        finally {
-            finishRunPromise();
-        }
+            return await this.executeTurn(lease, turnState, formatSkillInvocation(skill, additionalInstructions));
+        }, classifyAssistantOutcome);
     }
     async promptFromTemplate(name, args = []) {
-        if (this.phase !== "idle")
-            throw new AgentHarnessError("busy", "AgentHarness is busy");
-        this.phase = "turn";
-        const { runPromise, finishRunPromise } = this.startRunPromise();
-        try {
+        return this.runOperation("prompt_template", "unknown", async (lease) => {
             const turnState = await this.createTurnState();
             const template = (turnState.resources.promptTemplates ?? []).find((candidate) => candidate.name === name);
             if (!template)
                 throw new AgentHarnessError("invalid_argument", `Unknown prompt template: ${name}`);
-            return await this.executeTurn(turnState, formatPromptTemplateInvocation(template, args));
-        }
-        catch (error) {
-            if (this.runPromise === runPromise)
-                this.phase = "idle";
-            throw normalizeHarnessError(error, "unknown");
-        }
-        finally {
-            finishRunPromise();
+            return await this.executeTurn(lease, turnState, formatPromptTemplateInvocation(template, args));
+        }, classifyAssistantOutcome);
+    }
+    /**
+     * Steering and follow-up input is consumed only by a running agent attempt.
+     * A structural operation (`compact`, `navigateTree`) runs none, so accepting
+     * input there would silently inject it into an unrelated later prompt.
+     */
+    expectQueueConsumer(action) {
+        const snapshot = this.lifecycle.getSnapshot();
+        if (snapshot.tag !== "active")
+            throw new AgentHarnessError("invalid_state", `Cannot ${action} while idle`);
+        if (!PROMPT_FAMILY_KINDS.includes(snapshot.operation.kind)) {
+            throw new AgentHarnessError("invalid_state", `Cannot ${action} during ${snapshot.operation.kind}: no agent attempt can consume it`);
         }
     }
     async steer(text, options) {
-        if (this.phase === "idle")
-            throw new AgentHarnessError("invalid_state", "Cannot steer while idle");
+        this.expectQueueConsumer("steer");
         this.steerQueue.push(createUserMessage(text, options?.images));
         await this.emitQueueUpdate();
     }
     async followUp(text, options) {
-        if (this.phase === "idle")
-            throw new AgentHarnessError("invalid_state", "Cannot follow up while idle");
+        this.expectQueueConsumer("follow up");
         this.followUpQueue.push(createUserMessage(text, options?.images));
         await this.emitQueueUpdate();
     }
@@ -629,6 +678,7 @@ export class AgentHarness {
         if (!compactResult.ok)
             throw compactResult.error;
         const result = compactResult.value;
+        options.beforeCommit?.();
         const entryId = await this.session.appendCompaction(result.summary, result.firstKeptEntryId, result.tokensBefore, result.details, provided !== undefined);
         const entry = await this.session.getEntry(entryId);
         if (entry?.type === "compaction") {
@@ -647,28 +697,26 @@ export class AgentHarness {
         return { ...context, messages: convertToLlm(persisted.messages) };
     }
     async compact(customInstructions) {
-        if (this.phase !== "idle")
-            throw new AgentHarnessError("busy", "compact() requires idle harness");
-        this.phase = "compaction";
-        try {
-            const result = await this.runCompaction({ automatic: false, customInstructions });
+        return this.runOperation("manual_compaction", "compaction", async (lease) => {
+            this.lifecycle.setStage(lease, "structural_running");
+            const result = await this.runCompaction({
+                automatic: false,
+                customInstructions,
+                beforeCommit: () => {
+                    this.lifecycle.setStage(lease, "committing");
+                },
+            });
             if (!result)
                 throw new AgentHarnessError("compaction", "Nothing to compact");
             return result;
-        }
-        catch (error) {
-            throw normalizeHarnessError(error, "compaction");
-        }
-        finally {
-            this.phase = "idle";
-        }
+        });
     }
     async navigateTree(targetId, options) {
-        if (this.phase !== "idle")
-            throw new AgentHarnessError("busy", "navigateTree() requires idle harness");
-        this.phase = "branch_summary";
-        try {
+        return this.runOperation("tree_navigation", "branch_summary", async (lease) => {
+            this.lifecycle.setStage(lease, "structural_running");
             const oldLeafId = await this.session.getLeafId();
+            // No-op navigation mutates nothing, so it completes without ever
+            // entering the `committing` stage.
             if (oldLeafId === targetId)
                 return { cancelled: false };
             const targetEntry = await this.session.getEntry(targetId);
@@ -699,52 +747,24 @@ export class AgentHarness {
                 const auth = await this.getApiKeyAndHeaders?.(model);
                 if (!auth)
                     throw new AgentHarnessError("auth", "No auth available for branch summary");
-                const branchSummary = await generateBranchSummary(entries, {
+                const branchSummary = await runBranchSummary({
+                    entries,
                     model,
                     apiKey: auth.apiKey,
                     headers: auth.headers,
-                    signal: new AbortController().signal,
                     customInstructions: hookResult?.customInstructions ?? options?.customInstructions,
                     replaceInstructions: hookResult?.replaceInstructions ?? options?.replaceInstructions,
-                    ...createSummarizationRetry("branch_summary", this.streamOptions.summarizationRetry, (event) => this.emitOwn(event)),
+                    summarizationRetry: this.streamOptions.summarizationRetry,
+                    emit: (event) => this.emitOwn(event),
                 });
-                if (!branchSummary.ok) {
-                    if (branchSummary.error.code === "aborted")
-                        return { cancelled: true };
-                    throw new AgentHarnessError("branch_summary", branchSummary.error.message, branchSummary.error);
-                }
-                summaryText = branchSummary.value.summary;
-                summaryDetails = {
-                    readFiles: branchSummary.value.readFiles,
-                    modifiedFiles: branchSummary.value.modifiedFiles,
-                };
-            }
-            let editorText;
-            let newLeafId;
-            if (targetEntry.type === "message" && targetEntry.message.role === "user") {
-                newLeafId = targetEntry.parentId;
-                const content = targetEntry.message.content;
-                editorText =
-                    typeof content === "string"
-                        ? content
-                        : content
-                            .filter((c) => c.type === "text")
-                            .map((c) => c.text)
-                            .join("");
-            }
-            else if (targetEntry.type === "custom_message") {
-                newLeafId = targetEntry.parentId;
-                editorText =
-                    typeof targetEntry.content === "string"
-                        ? targetEntry.content
-                        : targetEntry.content
-                            .filter((c) => c.type === "text")
-                            .map((c) => c.text)
-                            .join("");
-            }
-            else {
-                newLeafId = targetId;
-            }
+                if (branchSummary.cancelled)
+                    return { cancelled: true };
+                summaryText = branchSummary.summary;
+                summaryDetails = branchSummary.details;
+            }
+            const { newLeafId, editorText } = resolveNavigationTarget(targetEntry, targetId);
+            // Single declared commit point of a tree navigation.
+            this.lifecycle.setStage(lease, "committing");
             const summaryId = await this.session.moveTo(newLeafId, summaryText
                 ? { summary: summaryText, details: summaryDetails, fromHook: hookResult?.summary !== undefined }
                 : undefined);
@@ -761,13 +781,7 @@ export class AgentHarness {
                 fromHook: hookResult?.summary !== undefined,
             });
             return { cancelled: false, editorText, summaryEntry };
-        }
-        catch (error) {
-            throw normalizeHarnessError(error, "branch_summary");
-        }
-        finally {
-            this.phase = "idle";
-        }
+        }, classifyNavigateTreeOutcome);
     }
     getModel() {
         return this.model;
@@ -775,12 +789,9 @@ export class AgentHarness {
     async setModel(model) {
         try {
             const previousModel = this.model;
-            if (this.phase === "idle") {
-                await this.session.appendModelChange(model.provider, model.id);
-            }
-            else {
-                this.pendingSessionWrites.push({ type: "model_change", provider: model.provider, modelId: model.id });
-            }
+            const nextProvider = model.provider;
+            const nextModelId = model.id;
+            await this.persistConfigChange({ type: "model_change", provider: nextProvider, modelId: nextModelId });
             this.model = model;
             await this.emitOwn({ type: "model_update", model, previousModel, source: "set" });
         }
@@ -794,12 +805,7 @@ export class AgentHarness {
     async setThinkingLevel(level) {
         try {
             const previousLevel = this.thinkingLevel;
-            if (this.phase === "idle") {
-                await this.session.appendThinkingLevelChange(level);
-            }
-            else {
-                this.pendingSessionWrites.push({ type: "thinking_level_change", thinkingLevel: level });
-            }
+            await this.persistConfigChange({ type: "thinking_level_change", thinkingLevel: level });
             this.thinkingLevel = level;
             await this.emitOwn({ type: "thinking_level_update", level, previousLevel });
         }
@@ -818,12 +824,7 @@ export class AgentHarness {
             this.validateToolNames(nextActiveToolNames, nextTools);
             const previousToolNames = [...this.tools.keys()];
             const previousActiveToolNames = [...this.activeToolNames];
-            if (this.phase === "idle") {
-                await this.session.appendActiveToolsChange(nextActiveToolNames);
-            }
-            else {
-                this.pendingSessionWrites.push({ type: "active_tools_change", activeToolNames: [...nextActiveToolNames] });
-            }
+            await this.persistConfigChange({ type: "active_tools_change", activeToolNames: [...nextActiveToolNames] });
             this.tools = nextTools;
             this.activeToolNames = [...nextActiveToolNames];
             await this.emitOwn({
@@ -844,16 +845,12 @@ export class AgentHarness {
     }
     async setActiveTools(toolNames) {
         try {
-            this.validateToolNames(toolNames);
+            const nextActiveToolNames = [...toolNames];
+            this.validateToolNames(nextActiveToolNames);
             const previousToolNames = [...this.tools.keys()];
             const previousActiveToolNames = [...this.activeToolNames];
-            if (this.phase === "idle") {
-                await this.session.appendActiveToolsChange(toolNames);
-            }
-            else {
-                this.pendingSessionWrites.push({ type: "active_tools_change", activeToolNames: [...toolNames] });
-            }
-            this.activeToolNames = [...toolNames];
+            await this.persistConfigChange({ type: "active_tools_change", activeToolNames: [...nextActiveToolNames] });
+            this.activeToolNames = [...nextActiveToolNames];
             await this.emitOwn({
                 type: "tools_update",
                 toolNames: [...this.tools.keys()],
@@ -899,31 +896,44 @@ export class AgentHarness {
     async setStreamOptions(streamOptions) {
         this.streamOptions = cloneStreamOptions(streamOptions);
     }
+    /**
+     * Deliver the abort signal to the current operation without waiting for it to
+     * settle. Safe from an operation's own callbacks: nothing here awaits
+     * settlement, so it cannot form the cycle `abort()` has to refuse.
+     */
+    requestAbort() {
+        assertAbortAllowed(this.lifecycle.getSnapshot());
+        return describeAbortDelivery(this.lifecycle.requestAbort());
+    }
+    /**
+     * Queue work to run once the harness is idle and return its ref immediately.
+     *
+     * This is the callback-safe way to schedule follow-up work: awaiting
+     * `waitForIdle()` or `abort()` from a callback of the operation being settled
+     * deadlocks, because settlement awaits that callback. The ref reports the
+     * command's outcome and cancels it while it is still queued.
+     */
+    async runWhenIdle(command) {
+        return this.deferredCommands.enqueue(command);
+    }
     async abort() {
-        if (this.phase !== "idle" && this.phase !== "turn")
-            throw new AgentHarnessError("invalid_state", `Cannot abort during ${this.phase}`);
+        // Aborting awaits the captured operation's settlement, so a listener of that
+        // same operation must never reach the wait below.
+        this.rejectCurrentOperationSelfWait("abort()");
+        assertAbortAllowed(this.lifecycle.getSnapshot());
+        // Capture the current operation before delivering any signal: an operation
+        // started later by a settlement listener is never this call's target.
+        const capture = this.lifecycle.requestAbort();
         const clearedSteer = this.steerQueue.splice(0);
         const clearedFollowUp = this.followUpQueue.splice(0);
-        this.runAbortController?.abort();
-        const errors = [];
-        try {
-            await this.emitQueueUpdate();
-        }
-        catch (error) {
-            errors.push(toError(error));
-        }
-        try {
-            await this.waitForIdle();
-        }
-        catch (error) {
-            errors.push(toError(error));
-        }
-        try {
-            await this.emitOwn({ type: "abort", clearedSteer, clearedFollowUp });
-        }
-        catch (error) {
-            errors.push(toError(error));
-        }
+        const errors = await collectStepErrors([
+            () => this.emitQueueUpdate(),
+            async () => {
+                if (capture.target)
+                    await capture.target.settled;
+            },
+            () => this.emitOwn({ type: "abort", clearedSteer, clearedFollowUp }),
+        ]);
         if (errors.length > 0) {
             const cause = errors.length === 1 ? errors[0] : new AggregateError(errors, "Abort completed with errors");
             throw normalizeHarnessError(cause, "hook");
@@ -931,20 +941,12 @@ export class AgentHarness {
         return { clearedSteer, clearedFollowUp };
     }
     async waitForIdle() {
-        // Runs can chain: a settled listener may start the next prompt() before the
-        // previous run's promise resolves, so keep waiting until no run is active.
-        while (this.runPromise) {
-            await this.runPromise;
-        }
+        this.rejectCurrentOperationSelfWait("waitForIdle()");
+        // Delegates to the lifecycle: resolves once no operation is active or settling.
+        await this.lifecycle.waitForIdle();
     }
     subscribe(listener) {
-        let handlers = this.handlers.get(SUBSCRIBER_EVENT_TYPE);
-        if (!handlers) {
-            handlers = new Set();
-            this.handlers.set(SUBSCRIBER_EVENT_TYPE, handlers);
-        }
-        handlers.add(listener);
-        return () => handlers.delete(listener);
+        return this.subscribers.subscribe(listener);
     }
     on(type, handler) {
         let handlers = this.handlers.get(type);