opencode-muse 0.2.0 → 0.3.0

package/README.md

@@ -16,7 +16,7 @@ Add the published package to your project-level `opencode.jsonc` (or
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugins": ["opencode-muse@0.2.0"],
+  "plugins": ["opencode-muse@0.3.0"],
 }
 ```
 
@@ -41,7 +41,10 @@ EOF
 
 The locally packed package passed provider discovery and a text-turn smoke
 test. Muse models and a text turn were also confirmed in OpenChamber after
-restarting it. The verified Muse CLI and SDK version is 1.4.12.
+restarting it. Verified Muse CLI versions are 1.4.12 and 1.4.13 (the SDK
+stays 1.4.12; a newer CLI fingerprint starts with a recorded warning
+instead of failing). See
+[#21](https://github.com/pgquiles/opencode-muse/issues/21).
 
 ## Authentication
 
@@ -101,9 +104,10 @@ setup placeholder rather than advertising a model that will fail on use.
   warning instead of failing closed; a missing/malformed fingerprint or an
   unsupported envelope version still fails closed. See
   [#21](https://github.com/pgquiles/opencode-muse/issues/21).
-- **Billing and simultaneous work:** Pay-as-you-go behavior has not yet been
-  tested. The plugin also allows only one active writer per workspace, so a
-  new turn may be reported as busy while another is still finishing.
+- **Billing and simultaneous work:** Pay-as-you-go catalog and text turns pass
+  on Muse 1.4.13 (see the compatibility matrix). The plugin also allows only
+  one active writer per workspace, so a new turn may be reported as busy
+  while another is still finishing.
 
 ## Troubleshooting
 

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type MuseBridgeErrorCode = "MUSE_HOST_START_FAILED" | "MUSE_STARTUP_TIMEOUT" | "MUSE_COMMAND_TIMEOUT" | "MUSE_REQUEST_TIMEOUT" | "MUSE_COMMAND_REJECTED" | "MUSE_PROTOCOL_ERROR" | "MUSE_TRANSPORT_ERROR" | "MUSE_HOST_CLOSED" | "MUSE_REGISTRY_ERROR" | "MUSE_REGISTRY_STORAGE_ERROR" | "MUSE_WORKSPACE_BUSY" | "MUSE_WORKSPACE_LOCK_CORRUPT" | "MUSE_TURN_FAILED" | "MUSE_TURN_UNQUEUED" | "MUSE_UNSUPPORTED_REQUEST" | "MUSE_UNSUPPORTED_INPUT" | "MUSE_RECOVERY_CHOICE_REQUIRED" | "MUSE_TRANSCRIPT_DIVERGED";
+export type MuseBridgeErrorCode = "MUSE_HOST_START_FAILED" | "MUSE_STARTUP_TIMEOUT" | "MUSE_COMMAND_TIMEOUT" | "MUSE_REQUEST_TIMEOUT" | "MUSE_COMMAND_REJECTED" | "MUSE_PROTOCOL_ERROR" | "MUSE_TRANSPORT_ERROR" | "MUSE_HOST_CLOSED" | "MUSE_REGISTRY_ERROR" | "MUSE_REGISTRY_STORAGE_ERROR" | "MUSE_WORKSPACE_BUSY" | "MUSE_WORKSPACE_LOCK_CORRUPT" | "MUSE_TURN_FAILED" | "MUSE_TURN_UNQUEUED" | "MUSE_UNSUPPORTED_REQUEST" | "MUSE_UNSUPPORTED_INPUT" | "MUSE_RECOVERY_CHOICE_REQUIRED" | "MUSE_TRANSCRIPT_DIVERGED" | "MUSE_APPROVAL_PENDING";
 /** Safe plugin error: never attach raw CLI stderr, MSP text, prompts, or payloads. */
 export declare class MuseBridgeError extends Error {
     readonly code: MuseBridgeErrorCode;
@@ -90,3 +90,6 @@ export declare class MuseRecoveryChoiceRequiredError extends MuseBridgeError {
 export declare class MuseTranscriptDivergedError extends MuseBridgeError {
     constructor();
 }
+export declare class MuseApprovalPendingError extends MuseBridgeError {
+    constructor();
+}

package/dist/errors.js

@@ -179,3 +179,9 @@ export class MuseTranscriptDivergedError extends MuseBridgeError {
         this.name = "MuseTranscriptDivergedError";
     }
 }
+export class MuseApprovalPendingError extends MuseBridgeError {
+    constructor() {
+        super("MUSE_APPROVAL_PENDING", "Muse turn is parked awaiting an approval verdict; answer the pending prompt first", true);
+        this.name = "MuseApprovalPendingError";
+    }
+}

package/dist/model/language-model.d.ts

@@ -1,6 +1,6 @@
 import type { LanguageModelV3, LanguageModelV3CallOptions } from "@ai-sdk/provider";
 import type { MspNotification } from "../msp/client.js";
-import { type ContextFragment, type ExtractedTurnPart } from "./prompt.js";
+import { type ApprovalResponse, type ContextFragment, type ExtractedTurnPart } from "./prompt.js";
 import type { MuseModelSelection, RequestContext } from "../types.js";
 export interface MuseTurnHost {
     mintCommandId(): string;
@@ -31,11 +31,24 @@ export interface MuseTurnSession {
     updateCursor?(cursor: string): Promise<void>;
     recordTurnCompleted?(turnId: string, terminal: string, usage?: Record<string, unknown>): Promise<void>;
     release?(): Promise<void>;
+    /** Cross-turn chunk dedup for approval prompts; shared per OpenCode session. */
+    emittedApprovalPrompts?: Set<string>;
+    /** Set by the session manager when this call must attach to a parked turn. */
+    joinParkedTurnId?: string;
+    /** Bumped by the manager when a newer call takes over this session's output. */
+    streamEpoch?: number;
+    /** When true, the lease already moved to the joining call: detach, never interrupt or release. */
+    handoffLeaseToJoiner?: boolean;
+    /** Settle every still-pending approval verdict as denied (cancel path). */
+    cancelParkedApprovals?(): Promise<void> | void;
 }
 export interface MuseLanguageRuntime {
     selectionIndex: ReadonlyMap<string, MuseModelSelection>;
     resolveSession(context: RequestContext): Promise<MuseTurnSession>;
     videoChunkBytes?: number;
+    settleApprovalResponses?(sessionID: string, responses: ApprovalResponse[]): Promise<string[]>;
+    hasParkedApprovals?(sessionID: string): boolean | Promise<boolean>;
+    disarmParkedJoin?(sessionID: string): void;
 }
 export interface MuseTurnExecution {
     turnId: string;

package/dist/model/language-model.js

@@ -4,7 +4,7 @@ import { notificationCursorKey } from "../msp/notification.js";
 import { MUSE_CONTEXT_HEADERS, readRequestContext } from "./context.js";
 import { classifyMetaRequest, makeCompactionDigest, makeLocalTitle } from "./meta.js";
 import { promptContainsCompactionFingerprint } from "../session/fingerprint.js";
-import { extractTurnInput, validateModelOptions, } from "./prompt.js";
+import { extractApprovalResponses, extractTurnInput, validateModelOptions, } from "./prompt.js";
 import { MuseStreamMapper } from "./stream.js";
 const DEFAULT_VIDEO_CHUNK_BYTES = 6 * 1024 * 1024;
 function fingerprint(method, params) {
@@ -148,57 +148,88 @@ export async function runMuseTurn(context, input, options, runtime, transcriptFi
     let subscription;
     let firstNotification;
     let subscriptionController;
+    const joinTurnId = session.joinParkedTurnId;
+    session.joinParkedTurnId = undefined;
+    const joinedTurn = joinTurnId !== undefined;
+    if (!joinedTurn) {
+        // A fresh turn starts a new ownership epoch; stale handoff markers die here.
+        session.handoffLeaseToJoiner = false;
+    }
     const cancel = () => {
         if (cancelPromise)
             return cancelPromise;
+        // A superseded stream detaches silently: the joining call owns the turn now.
+        if (!joinedTurn && session.handoffLeaseToJoiner)
+            return Promise.resolve();
+        const denyParked = async () => {
+            try {
+                await session.cancelParkedApprovals?.();
+            }
+            catch {
+                // The verdict latch settles denied on its own timeout; a cancel-time
+                // settle failure must not mask the interrupt below.
+            }
+        };
         if (!turnId || !disposition) {
             abortRequested = true;
-            return Promise.resolve();
+            return denyParked();
         }
         const unqueue = disposition === "queued";
         const method = unqueue ? "turn/unqueue" : "turn/interrupt";
         const params = unqueue
             ? { sessionId: session.sessionId, turnId }
             : { sessionId: session.sessionId, turnId, retract: true };
-        cancelPromise = submitCommand(session, method, session.host.mintCommandId(), params).then(() => { });
+        cancelPromise = denyParked().then(() => submitCommand(session, method, session.host.mintCommandId(), params).then(() => { }));
         return cancelPromise;
     };
     const onAbort = () => { abortRequested = true; void cancel().catch(() => { }); };
     options.abortSignal?.addEventListener("abort", onAbort, { once: true });
     try {
-        if (!sameSelection(session.currentSelection, context.museSelection)) {
-            const model = {
-                providerId: context.museSelection.providerId,
-                modelId: context.museSelection.modelId,
-            };
-            if (context.museSelection.profileId !== null)
-                model.profileId = context.museSelection.profileId;
-            await submitCommand(session, "session/setModel", session.host.mintCommandId(), {
-                sessionId: session.sessionId,
-                model,
-            });
+        const turnCommandId = session.host.mintCommandId();
+        if (joinedTurn) {
+            // Attach to the parked turn: no turn/start, no model switch, no
+            // acceptance record. The settled verdict already resumed it server-side.
+            turnId = joinTurnId;
+            disposition = "joined";
+            subscriptionController = new AbortController();
+            subscription = session.host.subscribe(session.sessionId, session.replayAfterCursor, subscriptionController.signal)[Symbol.asyncIterator]();
+            firstNotification = subscription.next();
+            accepted = true;
         }
-        const inputParts = await mapVideoParts(session, input, options.abortSignal, runtime.videoChunkBytes);
-        if (options.abortSignal?.aborted)
-            throw new DOMException("Muse request aborted before turn start", "AbortError");
-        subscriptionController = new AbortController();
-        subscription = session.host.subscribe(session.sessionId, session.replayAfterCursor, subscriptionController.signal)[Symbol.asyncIterator]();
-        firstNotification = subscription.next();
-        const commandId = session.host.mintCommandId();
-        const params = {
-            sessionId: session.sessionId,
-            input: inputParts,
-        };
-        if (context.effort)
-            params.reasoningEffort = context.effort;
-        const ack = await submitCommand(session, "turn/start", commandId, params);
-        if (typeof ack.turnId !== "string" || typeof ack.disposition !== "string") {
-            throw new MspProtocolError("turn/start");
+        else {
+            if (!sameSelection(session.currentSelection, context.museSelection)) {
+                const model = {
+                    providerId: context.museSelection.providerId,
+                    modelId: context.museSelection.modelId,
+                };
+                if (context.museSelection.profileId !== null)
+                    model.profileId = context.museSelection.profileId;
+                await submitCommand(session, "session/setModel", session.host.mintCommandId(), {
+                    sessionId: session.sessionId,
+                    model,
+                });
+            }
+            const inputParts = await mapVideoParts(session, input, options.abortSignal, runtime.videoChunkBytes);
+            if (options.abortSignal?.aborted)
+                throw new DOMException("Muse request aborted before turn start", "AbortError");
+            subscriptionController = new AbortController();
+            subscription = session.host.subscribe(session.sessionId, session.replayAfterCursor, subscriptionController.signal)[Symbol.asyncIterator]();
+            firstNotification = subscription.next();
+            const params = {
+                sessionId: session.sessionId,
+                input: inputParts,
+            };
+            if (context.effort)
+                params.reasoningEffort = context.effort;
+            const ack = await submitCommand(session, "turn/start", turnCommandId, params);
+            if (typeof ack.turnId !== "string" || typeof ack.disposition !== "string") {
+                throw new MspProtocolError("turn/start");
+            }
+            turnId = ack.turnId;
+            disposition = ack.disposition;
+            accepted = true;
+            await session.recordTurnAccepted?.(turnCommandId, turnId);
         }
-        turnId = ack.turnId;
-        disposition = ack.disposition;
-        accepted = true;
-        await session.recordTurnAccepted?.(commandId, turnId);
         if (abortRequested)
             await cancel();
         const events = {
@@ -268,11 +299,16 @@ export async function runMuseTurn(context, input, options, runtime, transcriptFi
                     options.abortSignal?.removeEventListener("abort", onAbort);
                     subscriptionController?.abort();
                     await subscription?.return?.();
-                    await session.release?.();
+                    // The joining call owns the lease now; the superseded owner detaches
+                    // without releasing. The first release wins; exactly one runs.
+                    if (session.handoffLeaseToJoiner)
+                        session.handoffLeaseToJoiner = false;
+                    else
+                        await session.release?.();
                 }
             },
         };
-        return { turnId, commandId, disposition, events, cancel };
+        return { turnId, commandId: turnCommandId, disposition, events, cancel };
     }
     catch (error) {
         options.abortSignal?.removeEventListener("abort", onAbort);
@@ -315,7 +351,10 @@ export async function runMuseTurn(context, input, options, runtime, transcriptFi
                 finally {
                     subscriptionController?.abort();
                     await subscription?.return?.().catch(() => { });
-                    await session.release?.().catch(() => { });
+                    if (session.handoffLeaseToJoiner)
+                        session.handoffLeaseToJoiner = false;
+                    else
+                        await session.release?.().catch(() => { });
                 }
             })();
         }
@@ -325,7 +364,8 @@ export async function runMuseTurn(context, input, options, runtime, transcriptFi
             await subscription?.return?.();
             const commandMethod = error?.method;
             const ambiguousTurnStart = commandMethod === "turn/start" && !(error instanceof MspCommandRejectedError);
-            if (!ambiguousTurnStart)
+            // A failed join never owned the lease; the parked owner still holds it.
+            if (!ambiguousTurnStart && !joinedTurn)
                 await session.release?.();
         }
         throw error;
@@ -399,7 +439,7 @@ function localMetaStream(kind, text) {
     });
 }
 export function createMuseLanguageModel(runtime, modelID) {
-    const doPrepare = async (options) => {
+    const doPrepare = async (options, allowParkedJoin) => {
         const requestKind = classifyCall(options);
         if (requestKind !== "agent")
             throw new MuseUnsupportedRequestError(requestKind);
@@ -414,22 +454,82 @@ export function createMuseLanguageModel(runtime, modelID) {
         const initialExtraction = extractTurnInput(options.prompt, [], [], { signal: options.abortSignal });
         if (!initialExtraction.ok)
             throw inputErrorToException(initialExtraction.error);
+        const approvalResponses = extractApprovalResponses(options.prompt);
+        if (!allowParkedJoin && approvalResponses.length > 0) {
+            if (await runtime.hasParkedApprovals?.(context.sessionID)) {
+                throw new MuseUnsupportedRequestError("approval-response");
+            }
+            await runtime.settleApprovalResponses?.(context.sessionID, approvalResponses);
+        }
+        if (allowParkedJoin && approvalResponses.length > 0) {
+            if (!runtime.settleApprovalResponses) {
+                if (await runtime.hasParkedApprovals?.(context.sessionID)) {
+                    throw new MuseUnsupportedRequestError("approval-response");
+                }
+            }
+            else {
+                await runtime.settleApprovalResponses(context.sessionID, approvalResponses);
+            }
+        }
         const session = await runtime.resolveSession(context);
+        // Set by the manager when the settled verdicts matched a parked turn.
+        const joining = session.joinParkedTurnId !== undefined;
         if (session.contextError) {
-            await session.release?.();
+            if (joining)
+                runtime.disarmParkedJoin?.(context.sessionID);
+            else
+                await session.release?.();
             throw new MuseUnsupportedRequestError(session.contextError);
         }
         const observedCompaction = (session.compactionFingerprints ?? []).some((candidate) => promptContainsCompactionFingerprint(options.prompt, candidate));
         const extracted = extractTurnInput(options.prompt, observedCompaction ? [] : session.previousTranscriptFingerprints, session.contextAllowlist, { signal: options.abortSignal });
         if (!extracted.ok) {
-            await session.release?.();
+            if (joining && extracted.error.code === "no-new-user-input") {
+                try {
+                    const execution = await runMuseTurn(context, [], options, {
+                        ...runtime,
+                        resolveSession: async () => session,
+                    }, session.previousTranscriptFingerprints);
+                    return {
+                        context,
+                        execution,
+                        mapper: new MuseStreamMapper(execution.turnId, session.emittedApprovalPrompts),
+                        warnings: ignoredOptionWarnings(supportedOptions.options.ignoredOptions),
+                        epoch: session.streamEpoch,
+                        session,
+                    };
+                }
+                catch (error) {
+                    runtime.disarmParkedJoin?.(context.sessionID);
+                    throw error;
+                }
+            }
+            if (joining)
+                runtime.disarmParkedJoin?.(context.sessionID);
+            else
+                await session.release?.();
             throw inputErrorToException(extracted.error);
         }
-        const execution = await runMuseTurn(context, extracted.parts, options, {
-            ...runtime,
-            resolveSession: async () => session,
-        }, extracted.nextTranscriptFingerprints);
-        return { context, execution, mapper: new MuseStreamMapper(execution.turnId), warnings: ignoredOptionWarnings(supportedOptions.options.ignoredOptions) };
+        let execution;
+        try {
+            execution = await runMuseTurn(context, extracted.parts, options, {
+                ...runtime,
+                resolveSession: async () => session,
+            }, extracted.nextTranscriptFingerprints);
+        }
+        catch (error) {
+            if (joining)
+                runtime.disarmParkedJoin?.(context.sessionID);
+            throw error;
+        }
+        return {
+            context,
+            execution,
+            mapper: new MuseStreamMapper(execution.turnId, session.emittedApprovalPrompts),
+            warnings: ignoredOptionWarnings(supportedOptions.options.ignoredOptions),
+            epoch: session.streamEpoch,
+            session,
+        };
     };
     return {
         specificationVersion: "v3",
@@ -446,7 +546,7 @@ export function createMuseLanguageModel(runtime, modelID) {
             }
             if (requestKind === "unsupported-generate")
                 throw new MuseUnsupportedRequestError("generate");
-            const prepared = await doPrepare(options);
+            const prepared = await doPrepare(options, true);
             let outputClosed = false;
             let controllerRef;
             const closeOutput = () => {
@@ -465,6 +565,14 @@ export function createMuseLanguageModel(runtime, modelID) {
                     void (async () => {
                         try {
                             for await (const notification of prepared.execution.events) {
+                                // A newer call took over this session's output: end this
+                                // stream without a finish part. The generator's finally
+                                // detaches the lease to the joining call.
+                                if (prepared.epoch !== undefined && prepared.session.streamEpoch !== undefined
+                                    && prepared.session.streamEpoch !== prepared.epoch) {
+                                    closeOutput();
+                                    break;
+                                }
                                 const parts = prepared.mapper.accept(notification);
                                 for (const part of parts) {
                                     if (outputClosed)
@@ -508,10 +616,14 @@ export function createMuseLanguageModel(runtime, modelID) {
             }
             if (requestKind === "unsupported-generate")
                 throw new MuseUnsupportedRequestError("generate");
-            const prepared = await doPrepare(options);
+            const prepared = await doPrepare(options, false);
             let terminalError;
             const iterator = prepared.execution.events[Symbol.asyncIterator]();
             while (true) {
+                if (prepared.epoch !== undefined && prepared.session.streamEpoch !== undefined
+                    && prepared.session.streamEpoch !== prepared.epoch) {
+                    break;
+                }
                 const next = await iterator.next();
                 if (next.done)
                     break;

package/dist/model/prompt.d.ts

@@ -65,4 +65,14 @@ export declare const DEFAULT_MAX_MEDIA_BYTES: number;
 export declare const DEFAULT_MAX_INLINE_IMAGE_BYTES: number;
 export declare function fingerprintVisibleTranscript(prompt: LanguageModelV3Prompt): string[];
 export declare function extractTurnInput(prompt: LanguageModelV3Prompt, previousTranscriptFingerprints: readonly string[], contextAllowlist: readonly ContextFragment[], options?: ExtractTurnInputOptions): ExtractTurnInputResult;
+export interface ApprovalResponse {
+    approvalId: string;
+    approved: boolean;
+}
+/**
+ * Collect OpenCode's answers to previously emitted `tool-approval-request`
+ * chunks. Malformed entries are ignored; the caller treats an unmatched
+ * response as stale and drops it rather than failing the turn.
+ */
+export declare function extractApprovalResponses(prompt: LanguageModelV3Prompt): ApprovalResponse[];
 export declare function validateModelOptions(options: ModelOptionsInput): ModelOptionsResult;

package/dist/model/prompt.js

@@ -150,6 +150,32 @@ export function extractTurnInput(prompt, previousTranscriptFingerprints, context
         return { ok: false, error: inputError("no-new-user-input") };
     return { ok: true, parts, nextTranscriptFingerprints: currentFingerprints };
 }
+/**
+ * Collect OpenCode's answers to previously emitted `tool-approval-request`
+ * chunks. Malformed entries are ignored; the caller treats an unmatched
+ * response as stale and drops it rather than failing the turn.
+ */
+export function extractApprovalResponses(prompt) {
+    const responses = [];
+    for (const message of prompt) {
+        if (message.role !== "user")
+            continue;
+        const content = message.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const part of content) {
+            if (typeof part !== "object" || part === null)
+                continue;
+            const candidate = part;
+            if (candidate.type !== "tool-approval-response")
+                continue;
+            if (typeof candidate.approvalId !== "string" || typeof candidate.approved !== "boolean")
+                continue;
+            responses.push({ approvalId: candidate.approvalId, approved: candidate.approved });
+        }
+    }
+    return responses;
+}
 export function validateModelOptions(options) {
     if (options.responseFormat?.type === "json") {
         return { ok: false, error: inputError("unsupported-response-format", { field: "responseFormat" }) };

package/dist/model/stream.d.ts

@@ -9,6 +9,7 @@ export type MuseStreamPart = Record<string, unknown>;
 /** Maps typed Muse view facts to text/reasoning-only V3 events and safe usage. */
 export declare class MuseStreamMapper {
     readonly turnId: string;
+    private readonly emittedApprovals;
     private readonly itemKinds;
     private readonly itemStarted;
     private readonly reasoningStarted;
@@ -23,7 +24,7 @@ export declare class MuseStreamMapper {
     private currentFinishReason;
     terminal?: string;
     failure?: Error;
-    constructor(turnId: string);
+    constructor(turnId: string, emittedApprovals?: Set<string>);
     get generatedText(): string;
     get content(): Array<{
         type: "text";
@@ -36,6 +37,7 @@ export declare class MuseStreamMapper {
         raw: string;
     } | undefined;
     accept(notification: MspNotification): MuseStreamPart[];
+    private approvalRequestedEvent;
     private itemStartedEvent;
     private itemDeltaEvent;
     private itemCompletedEvent;

package/dist/model/stream.js

@@ -13,6 +13,7 @@ function terminalFinishReason(terminal) {
 /** Maps typed Muse view facts to text/reasoning-only V3 events and safe usage. */
 export class MuseStreamMapper {
     turnId;
+    emittedApprovals;
     itemKinds = new Map();
     itemStarted = new Set();
     reasoningStarted = new Set();
@@ -27,8 +28,9 @@ export class MuseStreamMapper {
     currentFinishReason;
     terminal;
     failure;
-    constructor(turnId) {
+    constructor(turnId, emittedApprovals = new Set()) {
         this.turnId = turnId;
+        this.emittedApprovals = emittedApprovals;
     }
     get generatedText() {
         return this.textParts.map((part) => part.text).join("");
@@ -80,10 +82,30 @@ export class MuseStreamMapper {
                 return this.finishWasSent ? [] : [this.finishPart("other", "retracted")];
             case "turn/completed":
                 return this.turnCompleted(params);
+            case "approval/requested":
+                return this.approvalRequestedEvent(params);
             default:
                 return [];
         }
     }
+    approvalRequestedEvent(params) {
+        const approvalId = params.approvalId;
+        const toolCallId = params.toolCallId;
+        if (typeof approvalId !== "string" || typeof toolCallId !== "string")
+            return [];
+        const requirementId = typeof params.currentRequirementId === "string" ? params.currentRequirementId : "";
+        const stageKey = `${approvalId} ${requirementId}`;
+        if (this.emittedApprovals.has(stageKey))
+            return [];
+        this.emittedApprovals.add(stageKey);
+        const toolName = params.toolName;
+        return [{
+                type: "tool-approval-request",
+                approvalId,
+                toolCallId,
+                ...(typeof toolName === "string" ? { providerMetadata: { muse: { toolName } } } : {}),
+            }];
+    }
     itemStartedEvent(params) {
         const item = params.item;
         if (!item || item.turnId !== this.turnId || typeof item.itemId !== "string")

package/dist/msp/approvals.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Map an OpenCode boolean approval verdict onto an MSP approval choice id.
+ *
+ * @param choices The `choices` array from the `approval/request` payload.
+ * @param approved True when OpenCode approved, false when denied.
+ * @returns The selected `choiceId`, or null when no single safe choice fits.
+ *   Null means the caller must fail closed (deny with a fresh-session hint).
+ */
+export interface ApprovalRequestParams {
+    approvalId: string;
+    currentRequirementId: string;
+    availableChoices: readonly unknown[];
+    sessionId: string;
+    turnId: string;
+    toolCallId: string;
+    toolName?: string;
+}
+export type ApprovalVerdict = {
+    approved: boolean;
+    params: ApprovalRequestParams;
+} | {
+    approved: false;
+    timedOut: true;
+    params: ApprovalRequestParams;
+} | {
+    alreadyDecided: true;
+    params: ApprovalRequestParams;
+};
+/**
+ * Per-session latch for MSP approval round trips. Mirrors the SDK router's
+ * discipline without duplicating it: one verdict per approval, a new stage
+ * (requirement id) replaces nothing but parks alongside, decided stages
+ * never re-park, and an undecided wait fails closed as denied on timeout.
+ * Late verdicts for settled approvals are dropped as stale.
+ */
+export declare class ApprovalExchange {
+    private readonly options;
+    private readonly pending;
+    private readonly decided;
+    constructor(options?: {
+        timeoutMs: number;
+    });
+    pendingApprovalIds(): string[];
+    /** The Muse turn that opened a pending approval, if it is still parked. */
+    pendingApprovalTurnId(approvalId: string): string | undefined;
+    requestApproval(params: unknown): Promise<ApprovalVerdict>;
+    settle(approvalId: string, approved: boolean): boolean;
+    markDecided(approvalId: string, requirementId: string): void;
+    private timeOut;
+    private clear;
+}
+export declare function selectApprovalChoiceId(choices: readonly unknown[], approved: boolean): string | null;

package/dist/msp/approvals.js

@@ -0,0 +1,146 @@
+// Selection of an MSP approval choice id from an OpenCode-style boolean verdict.
+//
+// OpenCode owns persistence (its "always allow" equivalent suppresses future
+// prompts before MSP is ever asked), so a bare `true` maps to the minimal
+// grant: one `once`-scoped approve choice. Anything broader or ambiguous
+// fails closed by returning null, and `localPersistent` choices are never
+// selected: the plugin must not create host-side persistent policy.
+function validChoices(choices) {
+    const valid = [];
+    for (const entry of choices) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const candidate = entry;
+        if (typeof candidate.choiceId !== "string")
+            continue;
+        if (candidate.decision !== "approve" && candidate.decision !== "reject")
+            continue;
+        if (typeof candidate.scope !== "string")
+            continue;
+        valid.push({ choiceId: candidate.choiceId, decision: candidate.decision, scope: candidate.scope });
+    }
+    return valid;
+}
+function singleChoiceId(choices) {
+    return choices.length === 1 ? choices[0].choiceId : null;
+}
+function asApprovalRequestParams(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const params = value;
+    if (typeof params.approvalId !== "string")
+        return null;
+    if (typeof params.currentRequirementId !== "string")
+        return null;
+    if (!Array.isArray(params.availableChoices))
+        return null;
+    if (typeof params.sessionId !== "string")
+        return null;
+    if (typeof params.turnId !== "string")
+        return null;
+    if (typeof params.toolCallId !== "string")
+        return null;
+    return {
+        approvalId: params.approvalId,
+        currentRequirementId: params.currentRequirementId,
+        availableChoices: params.availableChoices,
+        sessionId: params.sessionId,
+        turnId: params.turnId,
+        toolCallId: params.toolCallId,
+        ...(typeof params.toolName === "string" ? { toolName: params.toolName } : {}),
+    };
+}
+/**
+ * Per-session latch for MSP approval round trips. Mirrors the SDK router's
+ * discipline without duplicating it: one verdict per approval, a new stage
+ * (requirement id) replaces nothing but parks alongside, decided stages
+ * never re-park, and an undecided wait fails closed as denied on timeout.
+ * Late verdicts for settled approvals are dropped as stale.
+ */
+export class ApprovalExchange {
+    options;
+    pending = new Map();
+    decided = new Set();
+    constructor(options = { timeoutMs: 10 * 60 * 1000 }) {
+        this.options = options;
+    }
+    pendingApprovalIds() {
+        return [...this.pending.keys()];
+    }
+    /** The Muse turn that opened a pending approval, if it is still parked. */
+    pendingApprovalTurnId(approvalId) {
+        const stages = this.pending.get(approvalId)?.stages.values();
+        return stages?.next().value?.params.turnId;
+    }
+    requestApproval(params) {
+        const parsed = asApprovalRequestParams(params);
+        if (parsed === null)
+            return Promise.reject(new Error("unroutable-approval-request"));
+        const stageKey = `${parsed.approvalId} ${parsed.currentRequirementId}`;
+        if (this.decided.has(stageKey)) {
+            return Promise.resolve({ alreadyDecided: true, params: parsed });
+        }
+        const existing = this.pending.get(parsed.approvalId);
+        if (existing) {
+            const staged = existing.stages.get(parsed.currentRequirementId);
+            if (staged) {
+                staged.params = parsed;
+                return staged.promise;
+            }
+            let resolveStage;
+            const promise = new Promise((resolve) => { resolveStage = resolve; });
+            existing.stages.set(parsed.currentRequirementId, { params: parsed, resolve: resolveStage, promise });
+            return promise;
+        }
+        let resolveStage;
+        const promise = new Promise((resolve) => { resolveStage = resolve; });
+        const pending = {
+            approvalId: parsed.approvalId,
+            stages: new Map([[parsed.currentRequirementId, { params: parsed, resolve: resolveStage, promise }]]),
+            timer: undefined,
+        };
+        pending.timer = setTimeout(() => this.timeOut(parsed.approvalId), this.options.timeoutMs);
+        this.pending.set(parsed.approvalId, pending);
+        return promise;
+    }
+    settle(approvalId, approved) {
+        const pending = this.pending.get(approvalId);
+        if (!pending)
+            return false;
+        this.clear(approvalId);
+        for (const stage of pending.stages.values()) {
+            stage.resolve({ approved, params: stage.params });
+        }
+        return true;
+    }
+    markDecided(approvalId, requirementId) {
+        this.decided.add(`${approvalId} ${requirementId}`);
+        this.clear(approvalId);
+    }
+    timeOut(approvalId) {
+        const pending = this.pending.get(approvalId);
+        if (!pending)
+            return;
+        this.clear(approvalId);
+        for (const stage of pending.stages.values()) {
+            stage.resolve({ approved: false, timedOut: true, params: stage.params });
+        }
+    }
+    clear(approvalId) {
+        const pending = this.pending.get(approvalId);
+        if (pending?.timer !== undefined)
+            clearTimeout(pending.timer);
+        this.pending.delete(approvalId);
+    }
+}
+export function selectApprovalChoiceId(choices, approved) {
+    const valid = validChoices(choices);
+    const wantedDecision = approved ? "approve" : "reject";
+    const once = valid.filter((choice) => choice.decision === wantedDecision && choice.scope === "once");
+    if (once.length === 1)
+        return once[0].choiceId;
+    if (once.length > 1)
+        return null;
+    const session = valid.filter((choice) => choice.decision === wantedDecision && choice.scope === "session");
+    return singleChoiceId(session);
+}

package/dist/msp/client.d.ts

@@ -6,12 +6,17 @@ export interface MspNotification {
     params?: Record<string, unknown>;
     emittedAtMs?: number;
 }
+export interface MspServerRequest {
+    method: string;
+    params?: Record<string, unknown>;
+}
 export interface MspConnectionLike {
     readonly closed?: Promise<void>;
     command(method: string, params: Record<string, unknown>, options?: CommandOptions): Promise<Record<string, unknown>>;
     request(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
     mintCommandId(): string;
     onNotification(handler: (notification: MspNotification) => void): void;
+    onServerRequest?(handler: (request: MspServerRequest) => Promise<Record<string, unknown>>): void;
     onProtocolError?(handler: (error: unknown) => void): void;
     close(): Promise<void>;
 }
@@ -19,6 +24,7 @@ export interface MspClientOptions {
     commandTimeoutMs?: number;
     requestTimeoutMs?: number;
     closeConnection?: boolean;
+    onServerRequest?: (request: MspServerRequest) => Promise<Record<string, unknown>>;
     onFatal?: () => void;
 }
 /** Thin typed facade over the SDK connection; it never logs or retains wire payloads. */

package/dist/msp/client.js

@@ -107,6 +107,10 @@ export class MspClient {
         this.requestTimeoutMs = options.requestTimeoutMs ?? this.commandTimeoutMs;
         this.closeConnection = options.closeConnection ?? true;
         connection.onNotification((notification) => this.publish(notification));
+        if (options.onServerRequest) {
+            const handler = options.onServerRequest;
+            connection.onServerRequest?.((request) => handler(request));
+        }
         connection.onProtocolError?.(() => {
             if (this.observedProtocolFailure)
                 return;

package/dist/msp/host.d.ts

@@ -1,5 +1,6 @@
 import { type FingerprintWarning, type MspHandshake, type SpawnMspConnectionOptions } from "@muse-code/sdk";
-import { MspClient, type MspConnectionLike, type MspNotification } from "./client.js";
+import { MspClient, type MspConnectionLike, type MspNotification, type MspServerRequest } from "./client.js";
+import { ApprovalExchange } from "./approvals.js";
 export interface MspHostRuntime {
     connection: MspConnectionLike;
     initializeResult: Record<string, unknown>;
@@ -24,6 +25,13 @@ export interface MspHostOptions {
         version: string;
     };
     capabilities?: Parameters<MspHandshake["initialize"]>[0]["capabilities"];
+    onServerRequest?: (request: MspServerRequest) => Promise<Record<string, unknown>>;
+    approvalTimeoutMs?: number;
+    onApprovalParked?: (info: {
+        museTurnId: string;
+        approvalId: string;
+    }) => void;
+    onApprovalUnparked?: (approvalId: string) => void;
 }
 export interface MspHostDependencies {
     createHandshake?: (options: SpawnMspConnectionOptions) => MspHandshakeLike;
@@ -41,9 +49,13 @@ export declare class MspHost {
     readonly initializeResult: Record<string, unknown>;
     /** Set when the served schema fingerprint differs from the SDK pin. Warns, never blocks. */
     readonly fingerprintWarning?: FingerprintWarning;
+    /** Per-session latch for approval round trips; settled by OpenCode verdicts. */
+    readonly approvals: ApprovalExchange;
     readonly exited: Promise<MspHostExit>;
     private state;
     private closePromise;
+    private readonly onApprovalParked;
+    private readonly onApprovalUnparked;
     private constructor();
     static start(options?: MspHostOptions, dependencies?: MspHostDependencies): Promise<MspHost>;
     get isClosed(): boolean;
@@ -53,5 +65,7 @@ export declare class MspHost {
     }): Promise<TResult>;
     request<TResult extends object = Record<string, unknown>>(method: string, params?: Record<string, unknown>): Promise<TResult>;
     subscribe(sessionId: string, after?: string, signal?: AbortSignal): AsyncIterable<MspNotification>;
+    private handleServerRequest;
+    private handleApprovalRequest;
     close(): Promise<void>;
 }

package/dist/msp/host.js

@@ -1,6 +1,7 @@
 import { MspError, checkServedFingerprint, EXPECTED_SCHEMA_FINGERPRINT, MuseHostStartError as SdkHostStartError, spawnMspConnection, } from "@muse-code/sdk";
 import { MspCommandTimeoutError, MspHostClosedError, MspHostStartError, MspInitializeRejectedError, MspSchemaMismatchError, MspStartupTimeoutError, MspTransportError, } from "../errors.js";
 import { MspClient } from "./client.js";
+import { ApprovalExchange, selectApprovalChoiceId } from "./approvals.js";
 function defaultHandshake(options) {
     const handshake = spawnMspConnection(options);
     return {
@@ -70,17 +71,28 @@ export class MspHost {
     initializeResult;
     /** Set when the served schema fingerprint differs from the SDK pin. Warns, never blocks. */
     fingerprintWarning;
+    /** Per-session latch for approval round trips; settled by OpenCode verdicts. */
+    approvals;
     exited;
     state = "open";
     closePromise;
+    onApprovalParked;
+    onApprovalUnparked;
     constructor(runtime, options, fingerprintWarning) {
         this.runtime = runtime;
         this.initializeResult = runtime.initializeResult;
         this.fingerprintWarning = fingerprintWarning;
+        this.approvals = new ApprovalExchange({ timeoutMs: options.approvalTimeoutMs ?? 10 * 60 * 1000 });
+        this.onApprovalParked = options.onApprovalParked;
+        this.onApprovalUnparked = options.onApprovalUnparked;
+        const customServerRequest = options.onServerRequest;
         this.client = new MspClient(runtime.connection, {
             commandTimeoutMs: options.commandTimeoutMs,
             requestTimeoutMs: options.requestTimeoutMs,
             closeConnection: false,
+            onServerRequest: customServerRequest
+                ? (request) => customServerRequest(request)
+                : (request) => this.handleServerRequest(request),
             onFatal: () => {
                 queueMicrotask(() => { void this.close().catch(() => { }); });
             },
@@ -175,6 +187,66 @@ export class MspHost {
             throw new MspHostClosedError();
         return this.client.subscribe(sessionId, after, signal);
     }
+    async handleServerRequest(request) {
+        if (request.method === "approval/request")
+            return this.handleApprovalRequest(request.params);
+        // Mirror the SDK's own client: answered methods ack with {}; every other
+        // server-request method keeps the bare-connection -32601.
+        throw new MspError({
+            code: -32601,
+            message: `method not found: ${request.method}`,
+            data: { kind: "methodNotFound", retryable: false },
+        });
+    }
+    async handleApprovalRequest(params) {
+        let verdict;
+        try {
+            const pending = this.approvals.requestApproval(params);
+            const raw = (params ?? {});
+            if (typeof raw.approvalId === "string" && typeof raw.turnId === "string"
+                && this.approvals.pendingApprovalIds().includes(raw.approvalId)) {
+                this.onApprovalParked?.({ museTurnId: raw.turnId, approvalId: raw.approvalId });
+            }
+            verdict = await pending;
+        }
+        catch {
+            // Unroutable (malformed) approval requests are dropped like the SDK
+            // drops them; the server holds the turn under its own default-deny.
+            return {};
+        }
+        if ("alreadyDecided" in verdict)
+            return {};
+        const stage = verdict.params;
+        const choiceId = selectApprovalChoiceId(stage.availableChoices, verdict.approved)
+            ?? (verdict.approved ? selectApprovalChoiceId(stage.availableChoices, false) : null);
+        try {
+            if (choiceId !== null) {
+                await this.command("approval/decide", {
+                    commandId: this.client.mintCommandId(),
+                    sessionId: stage.sessionId,
+                    approvalId: stage.approvalId,
+                    requirementId: stage.currentRequirementId,
+                    choiceId,
+                });
+            }
+            else {
+                await this.command("turn/interrupt", {
+                    commandId: this.client.mintCommandId(),
+                    sessionId: stage.sessionId,
+                    turnId: stage.turnId,
+                    retract: true,
+                });
+            }
+        }
+        catch {
+            // The turn may already be gone (cancel raced the verdict). Mark the
+            // stage so a re-sent request does not re-park a dead round trip; the
+            // request plane is still acked.
+        }
+        this.approvals.markDecided(stage.approvalId, stage.currentRequirementId);
+        this.onApprovalUnparked?.(stage.approvalId);
+        return {};
+    }
     close() {
         if (this.closePromise)
             return this.closePromise;

package/dist/provider.d.ts

@@ -7,7 +7,11 @@ export type MuseProviderContext = Pick<Plugin.Context, "provider" | "session" |
 export interface ProviderPluginDependencies {
     fetchCatalog?: (directory: string) => Promise<MuseCatalogSnapshot>;
     createSessionManager?: () => MuseSessionManager;
+    /** Bounds how long setup waits for the live catalog before falling back. Defaults to 15s. */
+    setupRefreshTimeoutMs?: number;
 }
+/** Upper bound on delaying provider readiness for live catalog discovery. */
+export declare const SETUP_REFRESH_TIMEOUT_MS = 15000;
 export interface MuseProviderRuntime {
     catalog: CatalogCache;
     refreshTask: Promise<boolean>;

package/dist/provider.js

@@ -9,6 +9,8 @@ import { MuseBridgeError } from "./errors.js";
 import { makeCompactionDigest, makeLocalTitle } from "./model/meta.js";
 import { fingerprintCompactionOutput } from "./session/fingerprint.js";
 import { extractAllowedAgentContext } from "./model/agent-context.js";
+/** Upper bound on delaying provider readiness for live catalog discovery. */
+export const SETUP_REFRESH_TIMEOUT_MS = 15_000;
 function providerInfo(moduleUrl) {
     return {
         id: MUSE_PROVIDER_ID,
@@ -65,6 +67,9 @@ export async function createProviderPlugin(ctx, moduleUrl, dependencies = {}) {
             input.language = createMuseLanguageModel({
                 selectionIndex: catalog.selectionIndex,
                 resolveSession: (context) => sessions.resolveSession(context),
+                settleApprovalResponses: (sessionID, responses) => sessions.settleApprovalResponses(sessionID, responses),
+                hasParkedApprovals: (sessionID) => sessions.hasParkedApprovals(sessionID),
+                disarmParkedJoin: (sessionID) => sessions.disarmParkedJoin(sessionID),
             }, input.model.modelID);
         }, { providerID: MUSE_PROVIDER_ID });
         localMetaRegistrations.push(await ctx.session.hook("title", async (input) => {
@@ -93,6 +98,23 @@ export async function createProviderPlugin(ctx, moduleUrl, dependencies = {}) {
                 await ctx.provider.reload();
         });
     });
+    // Wait for live discovery (bounded) so consumers never see the pre-refresh
+    // fallback. On timeout or failure the disabled placeholder stays in place
+    // and a late refresh still replaces it via provider.reload().
+    const refreshTimeoutMs = dependencies.setupRefreshTimeoutMs ?? SETUP_REFRESH_TIMEOUT_MS;
+    let refreshTimer;
+    try {
+        await Promise.race([
+            refreshTask.then(() => true, () => false),
+            new Promise((resolve) => {
+                refreshTimer = setTimeout(() => resolve(false), refreshTimeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (refreshTimer !== undefined)
+            clearTimeout(refreshTimer);
+    }
     return {
         catalog,
         refreshTask,

package/dist/session/manager.d.ts

@@ -1,11 +1,12 @@
 import type { MspHandshake } from "@muse-code/sdk";
 import type { RequestContext } from "../types.js";
 import { MspHost } from "../msp/host.js";
+import type { ApprovalResponse } from "../model/prompt.js";
 import type { SessionRegistry } from "./registry.js";
 import type { WorkspaceLock } from "./workspace-lock.js";
 import type { MuseTurnSession } from "../model/language-model.js";
 import type { AgentContextResult } from "../model/agent-context.js";
-export interface MuseSessionHost extends Pick<MspHost, "command" | "request" | "subscribe" | "mintCommandId" | "close"> {
+export interface MuseSessionHost extends Pick<MspHost, "command" | "request" | "subscribe" | "mintCommandId" | "close" | "approvals"> {
     initializeResult: Record<string, unknown>;
 }
 export interface MuseSessionManagerOptions {
@@ -31,6 +32,18 @@ export declare class MuseSessionManager {
     constructor(options: MuseSessionManagerOptions);
     setContextForSession(openCodeSessionId: string, context: AgentContextResult): void;
     resolveSession(context: RequestContext): Promise<MuseTurnSession>;
+    /**
+     * Route OpenCode's answers to previously emitted `tool-approval-request`
+     * chunks into the parked MSP approval round trips. Returns the approval
+     * ids that matched a still-parked approval. When a matched approval
+     * belongs to the binding's active turn, the next `resolveSession` call
+     * attaches to that turn instead of starting a new one.
+     */
+    settleApprovalResponses(openCodeSessionId: string, responses: ApprovalResponse[]): Promise<string[]>;
+    /** True while the binding's active turn is parked awaiting a verdict. */
+    hasParkedApprovals(openCodeSessionId: string): boolean;
+    /** Drop a join that can no longer attach (diverged prompt, failed start). */
+    disarmParkedJoin(openCodeSessionId: string): void;
     close(): Promise<void>;
     recordCompactionCandidate(openCodeSessionId: string, fingerprint: string): Promise<void>;
     private applySelectionIfChanged;

package/dist/session/manager.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync, realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { MspHost } from "../msp/host.js";
-import { MspCommandRejectedError, MuseRecoveryChoiceRequiredError, MuseUnsupportedRequestError, RegistryWorkspaceMismatchError, } from "../errors.js";
+import { MspCommandRejectedError, MuseApprovalPendingError, MuseRecoveryChoiceRequiredError, MuseUnsupportedRequestError, RegistryWorkspaceMismatchError, } from "../errors.js";
 function canonicalWorkspacePath(directory) {
     const absolute = resolve(directory);
     return existsSync(absolute) ? realpathSync(absolute) : absolute;
@@ -70,6 +70,15 @@ export class MuseSessionManager {
         if (existingBinding && existingBinding.workspaceFingerprint !== fingerprint) {
             throw new RegistryWorkspaceMismatchError();
         }
+        if (existingBinding?.joinParkedTurnId !== undefined) {
+            // The settled verdicts matched a parked turn: attach to it instead of
+            // starting a new one. The parked call still holds the lease; the
+            // handoff flag tells it to detach without releasing.
+            return existingBinding;
+        }
+        if (existingBinding && existingBinding.host.approvals.pendingApprovalIds().length > 0) {
+            throw new MuseApprovalPendingError();
+        }
         const lease = await this.options.workspaceLock.acquire(fingerprint, context.sessionID);
         let host;
         try {
@@ -123,6 +132,10 @@ export class MuseSessionManager {
                     workspaceRoot: canonicalDirectory,
                     providerId: selected.providerId,
                     modelId: selected.modelId,
+                    // #22: Muse must ask through approval/request so OpenCode stays in
+                    // the loop; the host default would let side-effectful actions
+                    // through silently.
+                    approvalMode: "onRequest",
                 });
                 const startedSessionId = sessionIdFrom(start);
                 if (!startedSessionId)
@@ -142,6 +155,8 @@ export class MuseSessionManager {
                 workspaceFingerprint: fingerprint,
                 viewCursor,
                 replayAfterCursor,
+                emittedApprovalPrompts: new Set(),
+                streamEpoch: 0,
                 currentSelection: initialSelection,
                 previousTranscriptFingerprints: stored?.transcriptFingerprints ?? [],
                 transcriptFingerprints: stored?.transcriptFingerprints ?? [],
@@ -188,6 +203,9 @@ export class MuseSessionManager {
                     binding.activeTurnId = undefined;
                     binding.replayAfterCursor = undefined;
                     binding.pendingCommands = {};
+                    binding.joinParkedTurnId = undefined;
+                    binding.handoffLeaseToJoiner = false;
+                    binding.emittedApprovalPrompts = new Set();
                     try {
                         await persist();
                     }
@@ -197,6 +215,11 @@ export class MuseSessionManager {
                         throw error;
                     }
                 },
+                async cancelParkedApprovals() {
+                    for (const approvalId of binding.host.approvals.pendingApprovalIds()) {
+                        binding.host.approvals.settle(approvalId, false);
+                    }
+                },
                 async release() {
                     const currentLease = binding.lease;
                     binding.lease = undefined;
@@ -238,6 +261,54 @@ export class MuseSessionManager {
             throw error;
         }
     }
+    /**
+     * Route OpenCode's answers to previously emitted `tool-approval-request`
+     * chunks into the parked MSP approval round trips. Returns the approval
+     * ids that matched a still-parked approval. When a matched approval
+     * belongs to the binding's active turn, the next `resolveSession` call
+     * attaches to that turn instead of starting a new one.
+     */
+    async settleApprovalResponses(openCodeSessionId, responses) {
+        const binding = this.bindings.get(openCodeSessionId);
+        if (!binding)
+            return [];
+        const matched = [];
+        let joinTurnId;
+        for (const response of responses) {
+            // Capture the parked turn before settle clears the pending entry.
+            const parkedTurnId = binding.host.approvals.pendingApprovalTurnId(response.approvalId);
+            if (parkedTurnId === undefined)
+                continue;
+            if (!binding.host.approvals.settle(response.approvalId, response.approved))
+                continue;
+            matched.push(response.approvalId);
+            // Arm the join only for verdicts that belong to the still-active turn;
+            // a verdict for a dead turn is delivered but never joined.
+            if (joinTurnId === undefined && parkedTurnId === binding.activeTurnId)
+                joinTurnId = parkedTurnId;
+        }
+        if (joinTurnId !== undefined) {
+            binding.joinParkedTurnId = joinTurnId;
+            binding.streamEpoch = (binding.streamEpoch ?? 0) + 1;
+            binding.handoffLeaseToJoiner = true;
+        }
+        return matched;
+    }
+    /** True while the binding's active turn is parked awaiting a verdict. */
+    hasParkedApprovals(openCodeSessionId) {
+        const binding = this.bindings.get(openCodeSessionId);
+        return binding !== undefined
+            && binding.activeTurnId !== undefined
+            && binding.host.approvals.pendingApprovalIds().length > 0;
+    }
+    /** Drop a join that can no longer attach (diverged prompt, failed start). */
+    disarmParkedJoin(openCodeSessionId) {
+        const binding = this.bindings.get(openCodeSessionId);
+        if (!binding)
+            return;
+        binding.joinParkedTurnId = undefined;
+        binding.handoffLeaseToJoiner = false;
+    }
     async close() {
         if (this.closed)
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-muse",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "OpenCode plugin backed by the official Muse Code CLI and MSP",
   "license": "MIT",
   "type": "module",