-
-
-
- {index + 1}
-
-
-
-
{label}
-
+
+
+ {index + 1}
+
+
);
}
@@ -288,7 +284,7 @@ function RowBody(props: MessageQueueRowProps & EditCommitProps) {
function RowActions(props: MessageQueueRowProps) {
const { t } = useTranslation();
- const { item, isFirst, showSteerAction, isEditing, onStartEdit, onRemove, onSteer } = props;
+ const { item, showSteerAction, isEditing, onStartEdit, onRemove, onSteer } = props;
// In edit mode the textarea owns the row: it carries its own confirm button, so we
// render no row-level actions that would compete for the click mid-edit.
@@ -298,7 +294,7 @@ function RowActions(props: MessageQueueRowProps) {
return (
- {isFirst && showSteerAction ? (
+ {showSteerAction ? (
Promise;
+ interrupt: () => Promise;
+}): Promise<'steered' | 'missing' | 'reorder_failed'> {
+ const preparation = resolveFallbackQueueSteerPreparation(queueItemCids, selectedCid);
+ if (preparation.type === 'missing') return 'missing';
+ if (preparation.type === 'reorder') {
+ try {
+ await reorder(preparation.activeCid, preparation.overCid);
+ } catch {
+ return 'reorder_failed';
+ }
+ }
+ await interrupt();
+ return 'steered';
+}
+
export function shouldRequestNativeQueueSteer(
authority: AcpCapabilityAuthority,
capability: Pick | undefined
diff --git a/packages/components/src/components/sessions/session-chat-input-area.tsx b/packages/components/src/components/sessions/session-chat-input-area.tsx
index e6727d16a..36c87b01d 100644
--- a/packages/components/src/components/sessions/session-chat-input-area.tsx
+++ b/packages/components/src/components/sessions/session-chat-input-area.tsx
@@ -145,6 +145,7 @@ import { useCodeCollabRequestedRole } from '@/hooks/use-code-collab-requested-ro
import { splitImageAndFileAttachments } from '@/lib/file-drop';
import { SessionUsagePopover } from './session-usage-popover';
import type { MachineRateLimits } from '@/lib/session-usage';
+import { getCommandKeybindings, useCommand } from '@/lib/commands';
const sessionDraftsCache = new Map();
@@ -441,7 +442,8 @@ export interface SessionChatInputAreaProps {
onConfigOptionChange?: (configId: string, value: AcpConfigOptionValue) => void;
onSendMessage: (
inputBlocks: SessionInputBlock[],
- agentRole: SessionTurnAgentRoleSelection
+ agentRole: SessionTurnAgentRoleSelection,
+ options?: SessionChatInputSubmitOptions
) => Promise;
onStop: () => void | Promise;
onRemoveQueueItem: (itemId: string) => Promise;
@@ -471,6 +473,10 @@ export interface SessionChatInputAreaProps {
export type SessionTurnAgentRoleSelection = ComposerTurnAgentRoleSelection;
+export type SessionChatInputSubmitOptions = {
+ invertQueuedBehavior?: boolean;
+};
+
export type SessionChatInputAreaHandle = {
setInputText: (text: string) => void;
focusInput: () => void;
@@ -1756,7 +1762,10 @@ export const SessionChatInputArea = memo(
[pastedTextDrafts, session.id, updatePastedTextDraftsForSession]
);
+ const invertQueuedBehaviorForNextSubmitRef = useRef(false);
const sendMessage = useCallback(async () => {
+ const invertQueuedBehavior = invertQueuedBehaviorForNextSubmitRef.current;
+ invertQueuedBehaviorForNextSubmitRef.current = false;
if (freeTurnLimitNotice && freeTurnLimitNotice.current >= freeTurnLimitNotice.limit) {
capturePostHogEvent(postHog, 'session/input_blocked', {
reason: 'free_session_turn_limit_reached',
@@ -1900,7 +1909,11 @@ export const SessionChatInputArea = memo(
const submission = beginSubmission({ dismissKeyboard: usesMobileKeyboardAction });
if (!submission) return;
try {
- const accepted = await onSendMessage(inputBlocks, agentRoleTurnSelectionRef.current);
+ const accepted = await onSendMessage(
+ inputBlocks,
+ agentRoleTurnSelectionRef.current,
+ invertQueuedBehavior ? { invertQueuedBehavior: true } : undefined
+ );
if (accepted) {
if (submission.isCurrent()) {
clearInput();
@@ -1999,6 +2012,24 @@ export const SessionChatInputArea = memo(
isExternalHistoryRefreshing ||
durableAgentRoleReady === false ||
Boolean(freeTurnLimitNotice && freeTurnLimitNotice.current >= freeTurnLimitNotice.limit);
+ useCommand(
+ {
+ id: 'session.sendWithInverseQueueBehavior',
+ title: t(
+ 'commands.session.sendWithInverseQueueBehavior',
+ 'Send with Opposite Queue/Steer Behavior'
+ ),
+ category: 'Session',
+ keybindings: getCommandKeybindings('session.sendWithInverseQueueBehavior'),
+ allowInTextInput: true,
+ when: () => hasSendableContent && !isSendActionDisabled,
+ run: () => {
+ invertQueuedBehaviorForNextSubmitRef.current = true;
+ void sendMessage();
+ },
+ },
+ commandsEnabled
+ );
const attachmentAddEnabled = !isArchived;
const sessionLocalFileSource = useMemo(
() =>
diff --git a/packages/components/src/components/sessions/session-chat-interface.tsx b/packages/components/src/components/sessions/session-chat-interface.tsx
index b303a575b..de922c51e 100644
--- a/packages/components/src/components/sessions/session-chat-interface.tsx
+++ b/packages/components/src/components/sessions/session-chat-interface.tsx
@@ -66,7 +66,11 @@ import {
type SessionTurnAgentRoleSelection,
} from './session-chat-input-area';
import { useSessionMcpSelection } from '@/hooks/use-session-mcp-selection';
-import { MessageQueueDisplay, shouldRequestNativeQueueSteer } from './message-queue';
+import {
+ MessageQueueDisplay,
+ shouldRequestNativeQueueSteer,
+ steerQueuedMessageWithFallback,
+} from './message-queue';
import { useTranslation } from 'react-i18next';
import { useRouter } from '@tanstack/react-router';
import { toast } from 'sonner';
@@ -1907,6 +1911,7 @@ export type SessionChatInterfaceHandle = {
export type DispatchInputBlocksOptions = {
forceQueue?: boolean;
forceDirect?: boolean;
+ invertQueuedBehavior?: boolean;
modeIdOverride?: string | null;
modelIdOverride?: string | null;
configOptionValuesOverride?: Record;
@@ -3951,6 +3956,7 @@ export const SessionChatInterface = memo(
const submitRoute = resolveSessionMessageSubmitRoute({
forceDirect,
forceQueue: options?.forceQueue === true,
+ invertQueuedBehavior: options?.invertQueuedBehavior === true,
isPromptBusy: isAgentBusy,
hasUnfinishedAssistantTurn: activeAssistantTurnId != null,
queuedMessageBehavior,
@@ -3977,6 +3983,7 @@ export const SessionChatInterface = memo(
...inputSummary,
force_queue: Boolean(options?.forceQueue),
force_direct: forceDirect,
+ invert_queued_behavior: Boolean(options?.invertQueuedBehavior),
submit_route: submitRoute.type,
is_agent_busy: isAgentBusy,
mode_id: turnModeId ?? null,
@@ -4100,9 +4107,10 @@ export const SessionChatInterface = memo(
const handleSendMessage = useCallback(
async (
inputBlocks: SessionInputBlock[],
- agentRole?: SessionTurnAgentRoleSelection
+ agentRole?: SessionTurnAgentRoleSelection,
+ options?: Pick
): Promise => {
- return await dispatchInputBlocks(inputBlocks, { agentRole });
+ return await dispatchInputBlocks(inputBlocks, { agentRole, ...options });
},
[dispatchInputBlocks]
);
@@ -5279,17 +5287,6 @@ export const SessionChatInterface = memo(
capabilityAuthority,
queueSteerCapability
);
- const handleSteerQueuedMessage = useCallback(
- async (item: MessageQueueItem) => {
- if (shouldUseNativeQueueSteer) {
- await handleNativeSteerQueuedMessage(item);
- return;
- }
- await handleInterruptAndSend(item);
- },
- [handleInterruptAndSend, handleNativeSteerQueuedMessage, shouldUseNativeQueueSteer]
- );
-
const handleReorderQueueItem = useCallback(
async (activeCid: string, overCid: string) => {
try {
@@ -5319,6 +5316,32 @@ export const SessionChatInterface = memo(
[captureSessionEvent, reorderMessageQueueItem, t]
);
+ const handleSteerQueuedMessage = useCallback(
+ async (item: MessageQueueItem) => {
+ if (shouldUseNativeQueueSteer) {
+ await handleNativeSteerQueuedMessage(item);
+ return;
+ }
+
+ // The compatibility path cancels the active turn and lets the daemon promote
+ // the queue head. Move an explicitly selected later item to that position first,
+ // preserving the user's choice without creating a second dispatch path.
+ await steerQueuedMessageWithFallback({
+ queueItemCids: messageQueue.map((queuedItem) => queuedItem.$cid),
+ selectedCid: item.$cid,
+ reorder: handleReorderQueueItem,
+ interrupt: () => handleInterruptAndSend(item),
+ });
+ },
+ [
+ handleInterruptAndSend,
+ handleNativeSteerQueuedMessage,
+ handleReorderQueueItem,
+ messageQueue,
+ shouldUseNativeQueueSteer,
+ ]
+ );
+
const handleStartQueueItemEdit = useCallback(
async (item: MessageQueueItem) => {
const isFirstItem = messageQueue[0]?.$cid === item.$cid;
diff --git a/packages/components/src/components/sessions/session-message-submit-route.ts b/packages/components/src/components/sessions/session-message-submit-route.ts
index dee7f6a09..7ce93d2bb 100644
--- a/packages/components/src/components/sessions/session-message-submit-route.ts
+++ b/packages/components/src/components/sessions/session-message-submit-route.ts
@@ -6,6 +6,7 @@ export type SessionMessageSubmitRoute =
export type SessionMessageSubmitRouteInput = {
forceDirect: boolean;
forceQueue: boolean;
+ invertQueuedBehavior: boolean;
isPromptBusy: boolean;
hasUnfinishedAssistantTurn: boolean;
queuedMessageBehavior: 'queue' | 'guide';
@@ -23,6 +24,7 @@ export type SessionMessageSubmitRouteInput = {
export function resolveSessionMessageSubmitRoute({
forceDirect,
forceQueue,
+ invertQueuedBehavior,
isPromptBusy,
hasUnfinishedAssistantTurn,
queuedMessageBehavior,
@@ -30,10 +32,15 @@ export function resolveSessionMessageSubmitRoute({
if (forceDirect) {
return { type: 'direct_dispatch' };
}
+ const effectiveQueuedMessageBehavior = invertQueuedBehavior
+ ? queuedMessageBehavior === 'queue'
+ ? 'guide'
+ : 'queue'
+ : queuedMessageBehavior;
if (
!forceQueue &&
isPromptBusy &&
- queuedMessageBehavior === 'guide' &&
+ effectiveQueuedMessageBehavior === 'guide' &&
hasUnfinishedAssistantTurn
) {
return { type: 'guide' };
diff --git a/packages/components/src/lib/commands/built-ins.ts b/packages/components/src/lib/commands/built-ins.ts
index 1e3edabfa..a0232aa2b 100644
--- a/packages/components/src/lib/commands/built-ins.ts
+++ b/packages/components/src/lib/commands/built-ins.ts
@@ -92,6 +92,12 @@ const UNAVAILABLE_COMMANDS: BuiltInCommandDefinition[] = [
title: 'Focus Current Input',
category: 'Editor',
},
+ {
+ id: 'session.sendWithInverseQueueBehavior',
+ titleKey: 'commands.session.sendWithInverseQueueBehavior',
+ title: 'Send with Opposite Queue/Steer Behavior',
+ category: 'Session',
+ },
{
id: 'session.toggleExplorerSidebar',
titleKey: 'commands.session.toggleExplorerSidebar',
diff --git a/packages/components/src/lib/commands/shortcuts.ts b/packages/components/src/lib/commands/shortcuts.ts
index d16341b5f..0a674f39b 100644
--- a/packages/components/src/lib/commands/shortcuts.ts
+++ b/packages/components/src/lib/commands/shortcuts.ts
@@ -14,6 +14,7 @@ export type ShortcutCommandId =
| 'session.toggleCurrentPinned'
| 'session.searchCurrent'
| 'session.focusInput'
+ | 'session.sendWithInverseQueueBehavior'
| 'session.toggleExplorerSidebar'
| 'session.copyCurrentBranch'
| 'session.copyUrl'
@@ -67,6 +68,7 @@ export const COMMAND_SHORTCUTS: Record =
// Desktop ⌘L focuses the composer. On web the browser owns ⌘L (Open Location),
// so leave it unbound — the hint chip follows the resolved binding.
'session.focusInput': [electron('Mod+l')],
+ 'session.sendWithInverseQueueBehavior': [whileComposerFocused('Mod+Shift+Enter')],
'session.toggleExplorerSidebar': ['Mod+Alt+b'],
'session.copyCurrentBranch': ['Alt+Shift+b'],
'session.copyUrl': ['Alt+Shift+c'],
diff --git a/packages/components/tests/commands-built-ins.test.ts b/packages/components/tests/commands-built-ins.test.ts
index 98e39a13f..06cc93d00 100644
--- a/packages/components/tests/commands-built-ins.test.ts
+++ b/packages/components/tests/commands-built-ins.test.ts
@@ -22,6 +22,9 @@ describe('built-in commands', () => {
expect(commands.getDefaultKeybindingsFor('session.archiveCurrent')).toEqual(['Mod+Alt+a']);
expect(commands.getDefaultKeybindingsFor('session.searchCurrent')).toEqual(['Mod+Alt+f']);
expect(commands.getDefaultKeybindingsFor('session.focusInput')).toEqual([]);
+ expect(commands.getDefaultKeybindingsFor('session.sendWithInverseQueueBehavior')).toEqual([
+ 'Mod+Shift+Enter',
+ ]);
expect(commands.getDefaultKeybindingsFor('session.nextTab')).toEqual([]);
expect(commands.getDefaultKeybindingsFor('session.previousVisible')).toEqual([]);
// ⌥N works on web too (always a new tab there); ⌘[/⌘] back/forward and the terminal
@@ -53,6 +56,9 @@ describe('built-in commands', () => {
expect(commands.getDefaultKeybindingsFor('session.searchCurrent')).toEqual(['Mod+f']);
expect(commands.getDefaultKeybindingsFor('session.focusInput')).toEqual(['Mod+l']);
+ expect(commands.getDefaultKeybindingsFor('session.sendWithInverseQueueBehavior')).toEqual([
+ 'Mod+Shift+Enter',
+ ]);
expect(commands.getDefaultKeybindingsFor('session.nextTab')).toEqual(['Mod+Shift+.']);
expect(commands.getDefaultKeybindingsFor('session.previousTab')).toEqual(['Mod+Shift+,']);
expect(commands.getDefaultKeybindingsFor('session.previousVisible')).toEqual(['Mod+Shift+[']);
diff --git a/packages/components/tests/message-queue-row-editing.test.tsx b/packages/components/tests/message-queue-row-editing.test.tsx
index 0f950e194..4861d9e0c 100644
--- a/packages/components/tests/message-queue-row-editing.test.tsx
+++ b/packages/components/tests/message-queue-row-editing.test.tsx
@@ -14,15 +14,15 @@ import { initI18n } from '../src/i18n';
const ORIGINAL_TASK = 'Refactor the message queue';
-function makeItem(): MessageQueueItem {
+function makeItem(cid = 'cid-0', task = ORIGINAL_TASK): MessageQueueItem {
return {
- $cid: 'cid-0',
- task: ORIGINAL_TASK,
+ $cid: cid,
+ task,
userId: 'user-1',
- userTurnId: 'turn-0',
+ userTurnId: `turn-${cid}`,
timestamp: '2026-01-01T00:00:00.000Z',
acpSessionConfig: {
- prompt: ORIGINAL_TASK,
+ prompt: task,
cliType: 'claude-code',
agentType: 'claude-code',
},
@@ -232,4 +232,44 @@ describe('queued message editing commits', () => {
expect(saved).toEqual([]);
expect(cancelled).toEqual(['cid-0']);
});
+
+ it('offers steer on every queued item and makes each message body draggable', async () => {
+ const items = [makeItem('cid-0', 'First queued task'), makeItem('cid-1', 'Later queued task')];
+ const steered: string[] = [];
+ await act(async () => {
+ root?.render(
+ createElement(MessageQueueDisplay, {
+ sessionId: 'session-test' as SessionId,
+ items,
+ onRemove: () => undefined,
+ onReorder: () => undefined,
+ onEditStart: () => undefined,
+ onEditCancel: () => undefined,
+ onEditSave: () => undefined,
+ onSteer: (item: MessageQueueItem) => {
+ steered.push(item.$cid);
+ },
+ showSteerAction: true,
+ })
+ );
+ });
+
+ const steerButtons = Array.from(
+ container!.querySelectorAll(
+ '[aria-label="Steer the active response with this message"]'
+ )
+ );
+ expect(steerButtons).toHaveLength(2);
+ await act(async () => {
+ steerButtons[1]?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+ });
+ expect(steered).toEqual(['cid-1']);
+
+ const dragTargets = Array.from(
+ container!.querySelectorAll('[aria-label="Drag to reorder"]')
+ );
+ expect(dragTargets).toHaveLength(2);
+ expect(dragTargets[1]?.textContent).toContain('Later queued task');
+ expect(dragTargets[1]?.contains(steerButtons[1] ?? null)).toBe(false);
+ });
});
diff --git a/packages/components/tests/queued-message-steer.test.ts b/packages/components/tests/queued-message-steer.test.ts
index 18c3bcd1b..542bf1d04 100644
--- a/packages/components/tests/queued-message-steer.test.ts
+++ b/packages/components/tests/queued-message-steer.test.ts
@@ -1,5 +1,9 @@
import { describe, expect, it } from 'vitest';
-import { shouldRequestNativeQueueSteer } from '../src/components/sessions/message-queue/queued-message-steer';
+import {
+ resolveFallbackQueueSteerPreparation,
+ shouldRequestNativeQueueSteer,
+ steerQueuedMessageWithFallback,
+} from '../src/components/sessions/message-queue/queued-message-steer';
describe('shouldRequestNativeQueueSteer', () => {
it.each([
@@ -12,3 +16,59 @@ describe('shouldRequestNativeQueueSteer', () => {
expect(shouldRequestNativeQueueSteer(authority, capability)).toBe(expected);
});
});
+
+describe('resolveFallbackQueueSteerPreparation', () => {
+ it('moves a selected later item to the queue head before interrupting', () => {
+ expect(resolveFallbackQueueSteerPreparation(['first', 'second', 'third'], 'third')).toEqual({
+ type: 'reorder',
+ activeCid: 'third',
+ overCid: 'first',
+ });
+ });
+
+ it('leaves the queue head in place and rejects stale selections', () => {
+ expect(resolveFallbackQueueSteerPreparation(['first', 'second'], 'first')).toEqual({
+ type: 'ready',
+ });
+ expect(resolveFallbackQueueSteerPreparation(['first', 'second'], 'missing')).toEqual({
+ type: 'missing',
+ });
+ });
+});
+
+describe('steerQueuedMessageWithFallback', () => {
+ it('reorders a later selection before interrupting', async () => {
+ const events: string[] = [];
+ const result = await steerQueuedMessageWithFallback({
+ queueItemCids: ['first', 'second'],
+ selectedCid: 'second',
+ reorder: async (activeCid, overCid) => {
+ events.push(`reorder:${activeCid}:${overCid}`);
+ },
+ interrupt: async () => {
+ events.push('interrupt');
+ },
+ });
+
+ expect(result).toBe('steered');
+ expect(events).toEqual(['reorder:second:first', 'interrupt']);
+ });
+
+ it('does not interrupt when reordering fails', async () => {
+ const events: string[] = [];
+ const result = await steerQueuedMessageWithFallback({
+ queueItemCids: ['first', 'second'],
+ selectedCid: 'second',
+ reorder: async () => {
+ events.push('reorder');
+ throw new Error('reorder failed');
+ },
+ interrupt: async () => {
+ events.push('interrupt');
+ },
+ });
+
+ expect(result).toBe('reorder_failed');
+ expect(events).toEqual(['reorder']);
+ });
+});
diff --git a/packages/components/tests/session-chat-input-submission.test.tsx b/packages/components/tests/session-chat-input-submission.test.tsx
index cd38a637c..ba4a717c1 100644
--- a/packages/components/tests/session-chat-input-submission.test.tsx
+++ b/packages/components/tests/session-chat-input-submission.test.tsx
@@ -63,8 +63,10 @@ import {
SessionChatInputArea,
setSessionChatInputTextDraft,
type SessionChatInputAreaHandle,
+ type SessionChatInputAreaProps,
} from '../src/components/sessions/session-chat-input-area';
import { initI18n } from '../src/i18n';
+import { commands } from '../src/lib/commands';
(
globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
@@ -342,7 +344,7 @@ describe('SessionChatInputArea submission feedback', () => {
claimNavigationFocus,
}: {
sessionId?: string;
- onSendMessage: (blocks: SessionInputBlock[]) => Promise;
+ onSendMessage: SessionChatInputAreaProps['onSendMessage'];
isArchived?: boolean;
composerRef?: RefObject;
claimNavigationFocus?: () => boolean;
@@ -402,6 +404,19 @@ describe('SessionChatInputArea submission feedback', () => {
});
}
+ it('submits the current draft with one-shot inverse queue behavior', async () => {
+ const onSendMessage = vi.fn(async () => true);
+ await renderComposer({ sessionId: 'inverse-queue-submit', onSendMessage });
+
+ await act(async () => {
+ expect(commands.execute('session.sendWithInverseQueueBehavior')).toBe(true);
+ await Promise.resolve();
+ });
+
+ expect(onSendMessage).toHaveBeenCalledOnce();
+ expect(onSendMessage.mock.calls[0]?.[2]).toEqual({ invertQueuedBehavior: true });
+ });
+
it.each([
['keyboard', true],
['keyboard', false],
diff --git a/packages/components/tests/session-message-submit-route.test.ts b/packages/components/tests/session-message-submit-route.test.ts
index 444d6df9e..fccaba37f 100644
--- a/packages/components/tests/session-message-submit-route.test.ts
+++ b/packages/components/tests/session-message-submit-route.test.ts
@@ -5,6 +5,7 @@ const resolve = (overrides: Partial {
).toEqual({ type: 'guide' });
});
+ it('inverts the configured queue behavior for an explicit submission', () => {
+ expect(
+ resolve({
+ isPromptBusy: true,
+ hasUnfinishedAssistantTurn: true,
+ queuedMessageBehavior: 'queue',
+ invertQueuedBehavior: true,
+ })
+ ).toEqual({ type: 'guide' });
+ expect(
+ resolve({
+ isPromptBusy: true,
+ hasUnfinishedAssistantTurn: true,
+ queuedMessageBehavior: 'guide',
+ invertQueuedBehavior: true,
+ })
+ ).toEqual({ type: 'queue', reason: 'prompt_busy' });
+ });
+
it('honors explicit route overrides with forceDirect taking precedence', () => {
expect(resolve({ forceQueue: true })).toEqual({ type: 'queue', reason: 'forced' });
expect(
diff --git a/specs/message-queue-interactions.md b/specs/message-queue-interactions.md
new file mode 100644
index 000000000..35f1952d3
--- /dev/null
+++ b/specs/message-queue-interactions.md
@@ -0,0 +1,46 @@
+# Message queue interactions
+
+Status: draft
+Translation: current
+
+[中文](message-queue-interactions.zh.md)
+
+## Scenario
+
+A user writes while an agent is working and chooses Queue or Steer as the default
+behavior. They may need the opposite behavior for one message, or may decide that
+any already queued message should steer the active response without first rearranging
+the queue by hand.
+
+## Contract
+
+- `Mod+Shift+Enter` sends the current composer draft with the opposite of the stored
+ Queue/Steer preference. This is a one-shot submission intent: it does not mutate the
+ preference, and it still obeys the ordinary availability, live-activity, and unfinished-
+ transcript safeguards.
+- While steering is available for the active turn, every queued message exposes Steer.
+ Selecting a later item targets that exact item. Native acknowledged steering removes
+ and applies the selected item directly; the compatibility path first moves it to the
+ queue head and interrupts only after the reorder succeeds.
+- The number and non-editing message body form the drag target for queue reordering.
+ Steer, edit, and remove remain separate controls and must not begin a drag.
+- Editing keeps its existing keyboard and focus behavior and disables reordering for
+ that row until editing ends.
+
+## Limits and review questions
+
+The shortcut changes routing only when Queue and Steer are meaningfully distinct. An
+idle session still dispatches normally, and a session without positive live prompt
+activity retains the conservative queue barrier even if the inverse intent would be
+Steer. Touch and pointer interactions share the same drag target; installed-app and
+physical-device coverage remains separate from component tests.
+
+## Implementation evidence
+
+- `packages/components/src/components/sessions/session-message-submit-route.ts`
+- `packages/components/src/components/sessions/session-chat-input-area.tsx`
+- `packages/components/src/components/sessions/message-queue/`
+- `packages/components/tests/{session-message-submit-route,queued-message-steer,message-queue-row-editing}.test.*`
+- [Decision record](../.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md)
+
+This is a draft for human review. Implementation and passing tests do not approve it.
diff --git a/specs/message-queue-interactions.zh.md b/specs/message-queue-interactions.zh.md
new file mode 100644
index 000000000..d9277d56b
--- /dev/null
+++ b/specs/message-queue-interactions.zh.md
@@ -0,0 +1,37 @@
+# 消息队列交互
+
+Status: draft
+Translation: current
+
+[English](message-queue-interactions.md)
+
+## 场景
+
+用户在 Agent 工作时继续输入，并将“排队”或“引导”设为默认行为。他们可能只想让某一条
+消息采用相反行为，也可能希望直接用任意一条已排队消息引导当前回复，而不必先手动调整队列。
+
+## 契约
+
+- `Mod+Shift+Enter` 以已保存“排队／引导”偏好的相反行为发送当前草稿。这是一次性的提交
+ 意图，不修改设置，并继续遵守普通的可用性、实时活动和未完成消息记录保护。
+- 当前 turn 可接受引导时，每条排队消息都提供“引导”操作。选择后续项必须以该项为目标。
+ 原生带确认的 steer 直接移除并应用所选项；兼容路径先把它移到队首，只有重排成功后才中断。
+- 序号和非编辑状态的消息正文共同组成队列重排拖动区域。“引导”、“编辑”和“移除”是独立
+ 控件，不能触发拖动。
+- 编辑状态保留已有键盘与焦点行为，并在编辑结束前禁用该行重排。
+
+## 边界与待审事项
+
+只有“排队”和“引导”具有不同含义时，该快捷键才改变路由。空闲会话仍正常直接发送；没有
+明确实时 prompt 活动时，即使反转意图是“引导”，也继续采用保守的排队屏障。触摸和鼠标共用
+同一拖动区域；已安装应用和物理设备验证不由组件测试替代。
+
+## 实现证据
+
+- `packages/components/src/components/sessions/session-message-submit-route.ts`
+- `packages/components/src/components/sessions/session-chat-input-area.tsx`
+- `packages/components/src/components/sessions/message-queue/`
+- `packages/components/tests/{session-message-submit-route,queued-message-steer,message-queue-row-editing}.test.*`
+- [决策记录](../.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md)
+
+这是供人工审阅的草稿；实现和测试通过不代表 Spec 已获批准。
From 31de8acad286fc20318b2553d7ca4d716ee90373 Mon Sep 17 00:00:00 2001
From: wibus-wee <62133302+wibus-wee@users.noreply.github.com>
Date: Sun, 13 Sep 2026 21:47:22 +0800
Subject: [PATCH 02/15] fix: steer queued messages by identity
Model: gpt-5
---
.agents/docs/rpc-loro-streams-rpc.md | 5 +
.agents/docs/sessions-live-status.md | 8 +-
.../2026-09-13-queue-steer-controls.md | 42 ++--
.../2026-09-13-queue-steer-controls.zh.md | 28 ++-
apps/cli/src/lib/loro/doc-user-turn.test.ts | 48 ++++-
apps/cli/src/lib/loro/doc.ts | 57 +++++
apps/cli/src/lib/message-handler.ts | 24 +++
apps/cli/src/session/AGENTS.md | 2 +-
apps/cli/src/session/README.md | 6 +-
apps/cli/src/session/queued-message-turn.ts | 63 ++++++
.../src/session/session-dispatch-watcher.ts | 61 +-----
.../src/session/session-execution-service.ts | 88 ++++++++
.../tests/session-execution-service.test.ts | 140 ++++++++++++
locales/en.json | 1 +
locales/zh_CN.json | 1 +
packages/components/src/atoms/runtime.ts | 11 +
.../sessions/message-queue/AGENTS.md | 14 +-
.../sessions/message-queue/index.ts | 5 -
.../message-queue/queued-message-steer.ts | 51 -----
.../sessions/session-chat-input-area.tsx | 22 +-
.../sessions/session-chat-interface.tsx | 199 +++++-------------
.../sessions/session-message-submit-route.ts | 6 +-
.../src/hooks/use-session-actions.ts | 41 ++++
.../components/src/lib/commands/shortcuts.ts | 2 +-
.../src/providers/create-workspace-runtime.ts | 2 +
.../providers/workspace-machine-rpc-facade.ts | 51 +++++
.../tests/queued-message-steer.test.ts | 74 -------
.../session-chat-input-submission.test.tsx | 9 +-
.../session-message-submit-route.test.ts | 6 +-
.../tests/use-session-actions.test.ts | 31 +++
.../workspace-machine-rpc-facade.test.ts | 52 +++++
packages/loro-streams-rpc/AGENTS.md | 2 +-
.../src/machine-rpc-server.ts | 26 +++
packages/loro-streams-rpc/src/rpc.ts | 73 +++++++
.../tests/loro-streams-rpc.test.ts | 24 +++
packages/shared/src/local-machine-rpc.ts | 13 ++
packages/shared/src/message-schemas.ts | 22 ++
packages/shared/src/message.ts | 17 ++
.../shared/tests/local-machine-rpc.test.ts | 9 +
packages/shared/tests/message-schemas.test.ts | 16 ++
specs/message-queue-interactions.md | 22 +-
specs/message-queue-interactions.zh.md | 13 +-
42 files changed, 974 insertions(+), 413 deletions(-)
create mode 100644 apps/cli/src/session/queued-message-turn.ts
delete mode 100644 packages/components/src/components/sessions/message-queue/queued-message-steer.ts
delete mode 100644 packages/components/tests/queued-message-steer.test.ts
diff --git a/.agents/docs/rpc-loro-streams-rpc.md b/.agents/docs/rpc-loro-streams-rpc.md
index 54bafb53e..cda7c3eed 100644
--- a/.agents/docs/rpc-loro-streams-rpc.md
+++ b/.agents/docs/rpc-loro-streams-rpc.md
@@ -20,6 +20,11 @@ been removed.
handlers.
- `README.md` — package smoke-test notes.
+`session/queue-steer` is an identity-based control operation, not queue reordering.
+Its request names both the expected active turn and the exact queued item. The CLI
+consumes that item before cancelling the expected turn; a missing item or stale turn
+is rejected without stopping the current agent.
+
## Remote lifecycle acknowledgements
For accepted restart/upgrade responses, `settleMachineLifecycleResponse` attempts
diff --git a/.agents/docs/sessions-live-status.md b/.agents/docs/sessions-live-status.md
index d8bc60f78..bd7389c5f 100644
--- a/.agents/docs/sessions-live-status.md
+++ b/.agents/docs/sessions-live-status.md
@@ -43,9 +43,11 @@ this page is the full text of the rules summarised there.
must queue in that state (even when the preference is guide; steering requires
positive live prompt activity), because queue promotion is safe for both a live
turn and a stale transcript while direct dispatch can create a second accepted
- turn. An explicit inverse submission swaps queue and guide for that submission
- only, then applies the same activity and ordering gates; it never changes the
- stored preference. This barrier affects routing only; it must not relight Working
+ turn. An explicit `queueBehavior: "inverse"` submission swaps queue and guide for
+ that submission only, then applies the same activity and ordering gates; ordinary
+ Enter supplies no override and neither path changes the stored preference. The
+ inverse command owns its composer-focus/content/readiness predicate so rebinding its
+ shortcut cannot bypass those constraints. This barrier affects routing only; it must not relight Working
UI or enable Stop. That pre-start label is additionally suppressed whenever the
status chip has an active connection/machine problem (`statusStripState !=
null`: browser offline, machine removed or offline) — the chip owns that story,
diff --git a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
index 260e331fc..7da6fc93a 100644
--- a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
+++ b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
@@ -10,38 +10,44 @@ Translation: current
Queue and Steer previously required changing a persistent preference, later queued
items hid Steer, and reordering started only from the small leading handle. The adopted
interaction adds a one-shot inverse submission command, exposes Steer on every row, and
-uses the row's message content as its drag target. Providers without acknowledged native
-steering preserve their compatibility path by moving a selected later item to the head
-before cancellation; a failed reorder leaves the active turn untouched.
+uses the row's message content as its drag target. Queue order and immediate Steer remain
+independent: the daemon consumes a selected queue identity directly, and a missing identity
+leaves the active turn untouched.
## Decision
- Register `session.sendWithInverseQueueBehavior` in the command system with
- `Mod+Shift+Enter` as its composer-focused default. The composer sends an explicit
- per-submission option; the routing resolver reverses the effective preference without
- writing settings or bypassing activity guards.
-- Show Steer for every row whenever the session-level action is available. Native steer
- continues to materialize and remove the selected item by identity. The compatibility
- path retains one queue consumer: it reorders the selection to the head, then uses the
- existing cancel-and-promote flow.
+ `Mod+Shift+Enter` as its default. The composer calls
+ `sendMessage({ queueBehavior: "inverse" })`; ordinary submission passes no option. The
+ command-level predicate owns composer focus, content, and send readiness so user binding
+ overrides cannot remove those rules. The routing resolver reverses only this submission.
+- Show Steer for every row whenever the session-level action is available. The renderer sends
+ the queue `$cid` and expected active turn through `session/queue-steer`, then waits for the
+ daemon result without changing queue or history locally. Under its per-session mutation and
+ history-rewrite leases, the daemon revalidates the turn and consumes that exact row into
+ history in one Session Doc mutation before requesting exact-turn cancellation.
- Make the leading number and message body a single pointer and keyboard drag activator.
Keep action buttons outside it, and disable it while the row editor owns interaction.
## Alternatives and trade-offs
-Keeping Steer on the first row would preserve the old fallback assumption but require
-users to perform a separate reorder. Sending a selected compatibility item through a new
-direct-dispatch path was rejected because it would duplicate the daemon's queue promotion
-ownership and create a second ordering boundary. Making the complete row draggable was
-also rejected because Steer, edit, and remove would become accidental drag starters.
+Keeping Steer on the first row would require users to perform an unrelated reorder first.
+Reorder-then-cancel was rejected because reorder can resolve after a concurrent peer deleted
+the selected row, causing Stop to target the current turn without any message to promote.
+Renderer-side history materialization was rejected because the renderer cannot atomically
+validate daemon turn ownership and queue identity. Making the complete row draggable was also
+rejected because Steer, edit, and remove would become accidental drag starters.
## Verification and limits
- Routing tests cover Queue → Steer and Steer → Queue inversion while a prompt is live.
-- Command registry tests cover the default binding in web and Electron environments.
+- Command tests cover the default binding, explicit submission option, and command-level
+ composer-focus rule.
- Queue component tests cover Steer on a later row and verify that message content, but
- not action buttons, belongs to the drag activator. Queue-steer tests cover later-item
- preparation, an already-first item, and a stale selection.
+ not action buttons, belongs to the drag activator.
+- CLI service and Session Doc tests cover consuming C from `[A, B, C]` as `[A, B]`, exact-turn
+ cancellation after consumption, and the missing-C failure path that never calls Stop.
+- Machine RPC schema tests cover both required identities.
- Component tests use synthetic pointer state. Physical touch dragging and a full
provider-backed steer run were not exercised.
diff --git a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
index 91f468068..554636235 100644
--- a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
@@ -9,31 +9,37 @@ Translation: current
此前若要在“排队”和“引导”间切换，必须修改持久设置；后续队列项不显示“引导”，重排也只能
从狭小的左侧把手开始。本次采用一次性反转提交命令、让每行都显示“引导”，并把消息内容区
-作为拖动区域。对于没有原生带确认 steer 的 Provider，兼容路径会在取消前先把所选后续项移到
-队首；如果重排失败，则不触碰当前 turn。
+作为拖动区域。队列顺序与立即“引导”保持独立：daemon 直接消费所选队列 ID；如果该 ID 已
+不存在，则当前 turn 不受影响。
## 决策
- 在命令系统注册 `session.sendWithInverseQueueBehavior`，默认仅在输入框聚焦时由
- `Mod+Shift+Enter` 触发。输入框传递显式的单次提交选项；路由器只反转本次有效偏好，
- 不写入设置，也不绕过活动状态保护。
-- 会话允许引导时，每一行都显示“引导”。原生 steer 继续按身份生成历史并移除所选项；
- 兼容路径仍只有一个队列消费者：先把所选项移到队首，再沿用取消与队列提升流程。
+ `Mod+Shift+Enter` 触发。输入框直接调用 `sendMessage({ queueBehavior: "inverse" })`，普通
+ 提交不传选项。输入框聚焦、有内容且可以发送是命令级条件，因此用户覆盖 binding 后也不会
+ 丢失；路由器只反转本次有效偏好。
+- 会话允许引导时，每一行都显示“引导”。Renderer 通过 `session/queue-steer` 发送队列 `$cid`
+ 和预期活动 turn，等待 daemon 返回，且不在本地修改队列或历史。Daemon 在每会话 mutation
+ 与历史 rewrite lease 下重新确认 turn，并在一次 Session Doc 更新中把该行消费进历史，再请求
+ 精确取消该 turn。
- 左侧序号和消息正文合并为一个支持鼠标及键盘的拖动区域。操作按钮保持在区域外；编辑器
接管交互时禁用该行拖动。
## 备选方案与取舍
-只允许队首“引导”可维持旧兼容路径假设，但用户仍必须额外重排。没有采用新的直接发送路径
-来发送兼容模式下的所选项，因为这会复制 daemon 的队列提升职责并增加第二个顺序边界。
-也没有让整行都可拖动，因为那会使“引导”、“编辑”和“移除”成为意外的拖动起点。
+只允许队首“引导”会迫使用户先做一次无关重排。没有采用“重排后取消”：并发客户端删除所选
+行时，重排仍可能 resolve，进而在没有可提升消息的情况下错误 Stop 当前 turn。也没有让
+Renderer 先写历史，因为它无法原子确认 daemon 的 turn 所有权和队列 ID。没有让整行都可拖动，
+因为那会使“引导”、“编辑”和“移除”成为意外的拖动起点。
## 验证与边界
- 路由测试覆盖 prompt 活动时“排队 → 引导”和“引导 → 排队”的反转。
-- 命令注册测试覆盖 Web 与 Electron 环境中的默认快捷键。
+- 命令测试覆盖默认 binding、显式提交选项和命令级输入框聚焦规则。
- 队列组件测试覆盖对后续项执行“引导”，并验证消息内容属于拖动区域而操作按钮不属于。
- 队列 steer 测试覆盖后续项准备、已在队首的项以及过期选择。
+- CLI service 与 Session Doc 测试覆盖从 `[A, B, C]` 消费 C 后保留 `[A, B]`、消费后精确取消
+ turn，以及 C 已缺失时绝不调用 Stop。
+- Machine RPC schema 测试覆盖两个必需 ID。
- 组件测试使用合成指针状态；未验证物理触摸拖动和完整的 Provider-backed steer 流程。
## 参考
diff --git a/apps/cli/src/lib/loro/doc-user-turn.test.ts b/apps/cli/src/lib/loro/doc-user-turn.test.ts
index d299313bf..805e3301e 100644
--- a/apps/cli/src/lib/loro/doc-user-turn.test.ts
+++ b/apps/cli/src/lib/loro/doc-user-turn.test.ts
@@ -1,5 +1,10 @@
import { describe, expect, it, vi } from 'vitest';
-import { createSessionMirror, type SessionHistoryInput, type SessionId } from '@lody/shared';
+import {
+ createSessionMirror,
+ type MessageQueueItem,
+ type SessionHistoryInput,
+ type SessionId,
+} from '@lody/shared';
import { LoroDoc, LoroList, LoroMap } from 'loro-crdt';
import type { LoroRepo } from 'loro-repo';
@@ -19,7 +24,10 @@ const createLogger = (): Logger =>
* runs; `history` mirrors what the CRDT would hold.
*/
const createSessionDocument = (repo: Partial) => {
- const state: { history: SessionHistoryInput[] } = { history: [] };
+ const state: { history: SessionHistoryInput[]; mq: MessageQueueItem[] } = {
+ history: [],
+ mq: [],
+ };
const doc = new SessionDocument(
repo as LoroRepo,
'session-append-1' as SessionId,
@@ -44,6 +52,42 @@ const createUserTurn = (id: string): SessionHistoryInput => ({
userId: 'user-1',
});
+describe('SessionDocument.consumeMessageQueueItemAsUserTurn', () => {
+ it('atomically consumes the named later row without reordering the survivors', async () => {
+ const upsertDocMeta = vi.fn(async () => {});
+ const { doc, state } = createSessionDocument({ upsertDocMeta });
+ state.mq = ['A', 'B', 'C'].map(
+ (cid): MessageQueueItem => ({
+ $cid: cid,
+ task: `task ${cid}`,
+ timestamp: '2026-09-13T00:00:00.000Z',
+ })
+ );
+
+ const result = await doc.consumeMessageQueueItemAsUserTurn('C', () =>
+ createUserTurn('user:C')
+ );
+
+ expect(result).toMatchObject({ type: 'consumed', entry: { id: 'user:C' } });
+ expect(state.history.map((entry) => entry.id)).toEqual(['user:C']);
+ expect(state.mq.map((item) => item.$cid)).toEqual(['A', 'B']);
+ expect(upsertDocMeta).toHaveBeenCalledWith(doc.roomId, { latestUserMsgId: 'user:C' });
+ });
+
+ it('does not write history or a dispatch pointer when the identity is absent', async () => {
+ const upsertDocMeta = vi.fn(async () => {});
+ const { doc, state } = createSessionDocument({ upsertDocMeta });
+ state.mq = [{ $cid: 'A', task: 'task A', timestamp: '2026-09-13T00:00:00.000Z' }];
+
+ await expect(
+ doc.consumeMessageQueueItemAsUserTurn('C', () => createUserTurn('user:C'))
+ ).resolves.toEqual({ type: 'missing' });
+ expect(state.history).toEqual([]);
+ expect(state.mq.map((item) => item.$cid)).toEqual(['A']);
+ expect(upsertDocMeta).not.toHaveBeenCalled();
+ });
+});
+
describe('SessionDocument.appendUserTurn', () => {
it('opens old malformed notices without sanitizing stored history', () => {
const { doc } = createSessionDocument({});
diff --git a/apps/cli/src/lib/loro/doc.ts b/apps/cli/src/lib/loro/doc.ts
index 68168f5d0..e3aae3632 100644
--- a/apps/cli/src/lib/loro/doc.ts
+++ b/apps/cli/src/lib/loro/doc.ts
@@ -2911,6 +2911,63 @@ export class SessionDocument implements LoroDocument SessionHistoryInput | null
+ ): Promise<
+ | { type: 'consumed'; entry: SessionHistoryInput }
+ | { type: 'missing' }
+ | { type: 'invalid' }
+ > {
+ if (!this.mirror) {
+ throw new Error('SessionDocument not initialized');
+ }
+
+ const outcome: {
+ value:
+ | { type: 'consumed'; entry: SessionHistoryInput }
+ | { type: 'missing' }
+ | { type: 'invalid' };
+ } = { value: { type: 'missing' } };
+ this.mirror.setState((prev) => {
+ const queue = (prev.mq ?? []) as MessageQueueItem[];
+ const item = queue.find((candidate) => candidate.$cid === cid);
+ if (!item) return prev;
+
+ const entry = buildEntry(item);
+ if (!entry) {
+ outcome.value = { type: 'invalid' };
+ return prev;
+ }
+ if (entry.role !== 'user') {
+ throw new Error(
+ `consumeMessageQueueItemAsUserTurn requires a user entry, received role "${entry.role}" for ${entry.id}`
+ );
+ }
+ const history = (prev.history as SessionHistoryInput[]) || [];
+ // @ts-ignore - mirror state is writable inside setState.
+ prev.history = [...history, entry];
+ // @ts-ignore - mirror state is writable inside setState.
+ prev.mq = queue.filter((candidate) => candidate.$cid !== cid);
+ outcome.value = { type: 'consumed', entry };
+ return prev;
+ });
+
+ if (outcome.value.type === 'consumed') {
+ await this.repo.upsertDocMeta(this.roomId, {
+ latestUserMsgId: outcome.value.entry.id,
+ } satisfies Partial);
+ }
+ return outcome.value;
+ }
+
/**
* Replace the fields of the message-queue item identified by `$cid`. The
* caller supplies the fully-resolved next field set (the renderer resolves its
diff --git a/apps/cli/src/lib/message-handler.ts b/apps/cli/src/lib/message-handler.ts
index 21de7835a..7d61314fb 100644
--- a/apps/cli/src/lib/message-handler.ts
+++ b/apps/cli/src/lib/message-handler.ts
@@ -2682,6 +2682,23 @@ export class MessageHandler {
return await this.executionService.steerSession(args);
}
+ private async steerQueuedMessageWithAccessCheck(
+ args: Parameters[0]
+ ): ReturnType {
+ const access = await this.verifySessionMachineAccess(args.sessionId, args.requestedByUserId);
+ if (access.outcome !== 'allowed') {
+ return {
+ type: 'session/queue-steer_response',
+ sessionId: args.sessionId,
+ queueItemId: args.queueItemId,
+ accepted: false,
+ disposition: 'error',
+ error: `Queue steer access verification ${access.outcome}`,
+ };
+ }
+ return await this.executionService.steerQueuedMessage(args);
+ }
+
private async controlSessionGoalWithAccessCheck(args: {
sessionId: SessionId;
action: SessionGoalAction;
@@ -3327,6 +3344,7 @@ export class MessageHandler {
};
},
steerSession: async (args) => await this.steerSessionWithAccessCheck(args),
+ steerQueuedMessage: async (args) => await this.steerQueuedMessageWithAccessCheck(args),
controlSessionGoal: async (args) => await this.controlSessionGoalWithAccessCheck(args),
terminateSession: async ({ sessionId }) => await this.terminateAcpSession(sessionId),
forkSession: async (args) => await this.forkSessionWithAccessCheck(args),
@@ -6357,6 +6375,12 @@ export class MessageHandler {
sessionId: request.params.sessionId as SessionId,
});
}
+ case 'session/queue-steer': {
+ return await this.steerQueuedMessageWithAccessCheck({
+ ...request.params,
+ sessionId: request.params.sessionId as SessionId,
+ });
+ }
case 'session/goal': {
return await this.controlSessionGoalWithAccessCheck({
...request.params,
diff --git a/apps/cli/src/session/AGENTS.md b/apps/cli/src/session/AGENTS.md
index d06019006..527054444 100644
--- a/apps/cli/src/session/AGENTS.md
+++ b/apps/cli/src/session/AGENTS.md
@@ -25,7 +25,7 @@ Contract: specs/session-orchestration.md.
## Dispatch
-- Queue promotion preserves frozen fields; remove its row only after history and activation succeed.
+- Queue promotion preserves frozen fields; Queue Steer consumes exact `$cid`; missing never stops.
- Absent session meta is "unknown", not foreign: hold the TTL-bounded RPC stash until meta lands;
drop it only on a definitive verdict.
- Subscribe to RPC offers BEFORE awaiting Doc Room join/sync and never dispatch from the RPC
diff --git a/apps/cli/src/session/README.md b/apps/cli/src/session/README.md
index fc0add084..e7318f1d0 100644
--- a/apps/cli/src/session/README.md
+++ b/apps/cli/src/session/README.md
@@ -19,10 +19,14 @@ CLI/MCP orchestration contract is specs/session-orchestration.md.
authorized or executed. Its extensive header comment
is the authoritative doc for edge cases (stale pointers, history/meta sync races).
- `session-dispatch-logic.ts` — pure decision functions for the watcher (testable).
+- `queued-message-turn.ts` — the shared queue-item-to-User-turn conversion used by
+ both ordinary queue dispatch and exact-item Steer consumption.
- `turn-history-gate.ts` — ordering barrier for RPC fast-path turns. Created in
message-handler's `beginConversationTurn`, stored/disposed via `SessionTransientStore` turn
state; it creates the assistant entry when it opens.
-- `session-execution-service.ts` — runs one turn end-to-end: ACP prompt, turn ids,
+- `session-execution-service.ts` — runs one turn end-to-end and owns exact-item queue
+ Steer serialization: validate the active turn and queued item, consume that item,
+ then cancel only the expected turn. It also owns ACP prompt, turn ids,
lifecycle/error handling, GitHub/local project setup, and post-turn diffStats.
- `acp-error-classification.ts` — JSON-RPC/transport error string matching for the above.
- `session-manager.ts` / `session.ts` / `session-sandbox.ts` / `terminal-manager.ts` —
diff --git a/apps/cli/src/session/queued-message-turn.ts b/apps/cli/src/session/queued-message-turn.ts
new file mode 100644
index 000000000..37472c0d6
--- /dev/null
+++ b/apps/cli/src/session/queued-message-turn.ts
@@ -0,0 +1,63 @@
+import {
+ buildPendingUserHistoryEntry,
+ buildSessionTurnInputConfig,
+ normalizeMcpServerIdSelection,
+ type AcpConfigOptionValue,
+ type MessageQueueItem,
+ type SessionHistoryInput,
+ type SessionMeta,
+} from '@lody/shared';
+import {
+ extractPromptPreviewFromInputBlocks,
+ normalizeSessionInputBlocks,
+} from './session-execution-helpers';
+import { resolveResumableAcpSessionId } from './session-dispatch-logic';
+
+const isConfigOptionValueRecord = (
+ value: unknown
+): value is Record => {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+ return Object.values(value as Record).every(
+ (item) => typeof item === 'string' || typeof item === 'boolean'
+ );
+};
+
+/** Materialize one durable queue item as the user turn that will execute it. */
+export function buildQueuedMessageUserTurn(
+ queuedItem: MessageQueueItem,
+ meta: SessionMeta
+): SessionHistoryInput | null {
+ const inputBlocks = normalizeSessionInputBlocks(
+ queuedItem.acpSessionConfig?.inputBlocks,
+ queuedItem.acpSessionConfig?.prompt ?? queuedItem.task
+ );
+ const inputConfig = buildSessionTurnInputConfig({
+ inputBlocks,
+ prompt: queuedItem.acpSessionConfig?.prompt ?? extractPromptPreviewFromInputBlocks(inputBlocks),
+ cliType: queuedItem.acpSessionConfig?.cliType ?? meta.cliType,
+ agentType: queuedItem.acpSessionConfig?.agentType ?? meta.agentType,
+ modeId: queuedItem.acpSessionConfig?.modeId,
+ modelId: queuedItem.acpSessionConfig?.modelId,
+ configOptionValues: isConfigOptionValueRecord(queuedItem.acpSessionConfig?.configOptionValues)
+ ? queuedItem.acpSessionConfig.configOptionValues
+ : undefined,
+ mcpServerIds: normalizeMcpServerIdSelection(queuedItem.acpSessionConfig?.mcpServerIds) ?? [],
+ taskToolsEnabled: queuedItem.acpSessionConfig?.taskToolsEnabled === true,
+ agentRoleId: queuedItem.acpSessionConfig?.agentRoleId,
+ agentRoleRevision: queuedItem.acpSessionConfig?.agentRoleRevision,
+ issuePRMentions: queuedItem.acpSessionConfig?.issuePRMentions,
+ resume: resolveResumableAcpSessionId(meta),
+ });
+ const pendingEntry = buildPendingUserHistoryEntry({
+ userId: queuedItem.userId ?? meta.userId,
+ inputBlocks,
+ timestamp: queuedItem.timestamp,
+ inputConfig,
+ });
+ if (!pendingEntry) return null;
+
+ return {
+ ...pendingEntry,
+ id: queuedItem.userTurnId?.trim() || `queued-${queuedItem.$cid}`,
+ };
+}
diff --git a/apps/cli/src/session/session-dispatch-watcher.ts b/apps/cli/src/session/session-dispatch-watcher.ts
index e3a4683a2..299005ca5 100644
--- a/apps/cli/src/session/session-dispatch-watcher.ts
+++ b/apps/cli/src/session/session-dispatch-watcher.ts
@@ -3,13 +3,11 @@ import { Effect, Fiber } from 'effect';
import {
buildMissingEmail,
buildPendingUserHistoryEntry,
- buildSessionTurnInputConfig,
getSessionRoomId,
getLegacyReadForSessionHistoryStatus,
type ChatFailedReason,
isLoroRepoDocDeleted,
isSessionDocRoomId,
- type AcpConfigOptionValue,
type MessageQueueItem,
type MachineId,
SESSION_DOC_PREFIX,
@@ -23,7 +21,6 @@ import {
SessionStatusFactory,
type SessionTurnInputConfig,
type WorkspaceId,
- normalizeMcpServerIdSelection,
getPendingUserTurnActivationId,
hasPendingUserTurnActivation,
} from '@lody/shared';
@@ -32,17 +29,13 @@ import { formatErrorMessage } from '@/utils/format-error';
import { startTraceSpan, traceAsync } from '@/utils/trace-span';
import type { LoroDocumentManager } from '@/lib/loro/doc';
import { SessionExecutionService, type SessionDispatchSource } from './session-execution-service';
-import {
- extractPromptPreviewFromInputBlocks,
- normalizeSessionInputBlocks,
-} from './session-execution-helpers';
+import { normalizeSessionInputBlocks } from './session-execution-helpers';
import type { SessionUserResolver, SessionUserProfile } from './session-user-resolver';
import {
findNextDispatchableUserTurn,
isActivationAwaitingHistory,
resolveDispatchTurnInput,
resolveDispatchAcpSessionId,
- resolveResumableAcpSessionId,
resolveSessionCancelAction,
resolveSessionDispatchAction,
shouldWatchSession,
@@ -57,6 +50,7 @@ import { resolveSessionLaunchConfig } from './session-launch-config-resolver';
import type { SessionAccessPolicyService } from './session-access-policy';
import { mapWithConcurrency } from '@/lib/bounded-concurrency';
import { listAliveRoomIds } from '@/lib/loro/repo-existence';
+import { buildQueuedMessageUserTurn } from './queued-message-turn';
const SESSION_RECONCILE_CONCURRENCY = 4;
@@ -197,17 +191,6 @@ type SessionReconcilePhase =
type SessionDocumentHandle = Awaited>;
-const isConfigOptionValueRecord = (
- value: unknown
-): value is Record => {
- if (!value || typeof value !== 'object' || Array.isArray(value)) {
- return false;
- }
- return Object.values(value as Record).every(
- (item) => typeof item === 'string' || typeof item === 'boolean'
- );
-};
-
/**
* ## Session Dispatch Watcher — Behavioral Design
*
@@ -2126,48 +2109,12 @@ export class SessionDispatchWatcher {
return null;
}
- const inputBlocks = normalizeSessionInputBlocks(
- queuedItem.acpSessionConfig?.inputBlocks,
- queuedItem.acpSessionConfig?.prompt ?? queuedItem.task
- );
- const inputConfig = buildSessionTurnInputConfig({
- inputBlocks,
- prompt:
- queuedItem.acpSessionConfig?.prompt ?? extractPromptPreviewFromInputBlocks(inputBlocks),
- cliType: queuedItem.acpSessionConfig?.cliType ?? meta.cliType,
- agentType: queuedItem.acpSessionConfig?.agentType ?? meta.agentType,
- modeId: queuedItem.acpSessionConfig?.modeId,
- modelId: queuedItem.acpSessionConfig?.modelId,
- configOptionValues: isConfigOptionValueRecord(
- queuedItem.acpSessionConfig?.configOptionValues
- )
- ? queuedItem.acpSessionConfig.configOptionValues
- : undefined,
- mcpServerIds:
- normalizeMcpServerIdSelection(queuedItem.acpSessionConfig?.mcpServerIds) ?? [],
- taskToolsEnabled: queuedItem.acpSessionConfig?.taskToolsEnabled === true,
- agentRoleId: queuedItem.acpSessionConfig?.agentRoleId,
- agentRoleRevision: queuedItem.acpSessionConfig?.agentRoleRevision,
- issuePRMentions: queuedItem.acpSessionConfig?.issuePRMentions,
- resume: resolveResumableAcpSessionId(meta),
- });
- const pendingEntry = buildPendingUserHistoryEntry({
- userId: queuedItem.userId ?? meta.userId,
- inputBlocks,
- timestamp: queuedItem.timestamp,
- inputConfig,
- });
-
- if (!pendingEntry) {
+ const entry = buildQueuedMessageUserTurn(queuedItem, meta);
+ if (!entry) {
this.deps.logger.debug(`[${meta.id}] Retaining invalid queued message ${queuedItem.$cid}`);
return null;
}
- const entry: SessionHistoryInput = {
- ...pendingEntry,
- id: queuedTurnId,
- };
-
// Promotion is a dispatch producer; `appendUserTurn` publishes the pointer.
await sessionDoc.appendUserTurn(entry);
await sessionDoc.removeMessageQueueItem(queuedItem.$cid);
diff --git a/apps/cli/src/session/session-execution-service.ts b/apps/cli/src/session/session-execution-service.ts
index 35ba71652..7316d7659 100644
--- a/apps/cli/src/session/session-execution-service.ts
+++ b/apps/cli/src/session/session-execution-service.ts
@@ -44,6 +44,7 @@ import {
SessionChatRequestValidated,
SessionCancelRequestValidated,
type SessionSteerResponse,
+ type SessionQueueSteerResponse,
type WorkspaceId,
hasRecentResumeNotice,
buildReplayPromptFromHistory,
@@ -111,6 +112,7 @@ import {
resolveResumableAcpSessionId,
} from './session-dispatch-logic';
import { resolveSessionLaunchConfig } from './session-launch-config-resolver';
+import { buildQueuedMessageUserTurn } from './queued-message-turn';
import type { MachineAccessVerification } from './session-access-retry';
import {
GIT_EXECUTABLE_NOT_FOUND_CODE,
@@ -1387,6 +1389,92 @@ export class SessionExecutionService {
});
}
+ async steerQueuedMessage(options: {
+ sessionId: SessionId;
+ expectedTurnId: string;
+ queueItemId: string;
+ requestedByUserId: string;
+ }): Promise {
+ const respond = (
+ disposition: SessionQueueSteerResponse['disposition'],
+ details?: { userTurnId?: string; error?: string }
+ ): SessionQueueSteerResponse => ({
+ type: 'session/queue-steer_response',
+ sessionId: options.sessionId,
+ queueItemId: options.queueItemId,
+ accepted: disposition === 'accepted',
+ disposition,
+ ...(details?.userTurnId ? { userTurnId: details.userTurnId } : {}),
+ ...(details?.error ? { error: details.error } : {}),
+ });
+
+ return await this.steerMutationQueue.enqueue(options.sessionId, async () => {
+ const releaseConflict = this.tryAcquireSessionRewriteConflictLease(options.sessionId);
+ if (!releaseConflict) {
+ return respond('busy', { error: 'The session history is being replaced.' });
+ }
+ try {
+ const runtime = this.turnRuntimeBySession.get(options.sessionId);
+ if (!runtime || !runtime.session || !runtime.promptInFlight || runtime.cancelRequested) {
+ return respond('no-active-turn');
+ }
+ if (runtime.turnId !== options.expectedTurnId) {
+ return respond('stale-turn');
+ }
+
+ const sessionDoc = await this.deps.workspaceDocument.getOrCreateSessionDoc(
+ options.sessionId
+ );
+ const meta = await sessionDoc.getMetaState();
+ if (!meta) {
+ return respond('error', { error: 'Session metadata is unavailable.' });
+ }
+
+ const currentRuntime = this.turnRuntimeBySession.get(options.sessionId);
+ if (
+ currentRuntime !== runtime ||
+ runtime.turnId !== options.expectedTurnId ||
+ !runtime.promptInFlight ||
+ runtime.cancelRequested
+ ) {
+ return respond('stale-turn');
+ }
+
+ // Queue order and immediate steering are separate mutations. Consume the
+ // selected identity directly; A/B keep their relative order when C wins.
+ const consumed = await sessionDoc.consumeMessageQueueItemAsUserTurn(
+ options.queueItemId,
+ (item) => buildQueuedMessageUserTurn(item, meta)
+ );
+ if (consumed.type === 'missing') {
+ return respond('queue-item-missing');
+ }
+ if (consumed.type === 'invalid') {
+ return respond('invalid-queue-item');
+ }
+ const entry = consumed.entry;
+ const cancellation = await this.cancelSession({
+ type: 'session/cancel',
+ sessionId: options.sessionId,
+ machineId: this.deps.machineId,
+ workspaceId: this.deps.workspaceId,
+ turnId: options.expectedTurnId,
+ });
+ if (!cancellation.success) {
+ return respond('error', {
+ userTurnId: entry.id,
+ error: cancellation.error ?? 'The active turn could not be stopped.',
+ });
+ }
+ return respond('accepted', { userTurnId: entry.id });
+ } catch (error) {
+ return respond('error', { error: formatErrorMessage(error) });
+ } finally {
+ releaseConflict();
+ }
+ });
+ }
+
private async steerSessionLocked(options: {
sessionId: SessionId;
expectedTurnId: string;
diff --git a/apps/cli/tests/session-execution-service.test.ts b/apps/cli/tests/session-execution-service.test.ts
index 6db828962..ffde55895 100644
--- a/apps/cli/tests/session-execution-service.test.ts
+++ b/apps/cli/tests/session-execution-service.test.ts
@@ -25,6 +25,7 @@ import {
type ChatFailedReason,
type LocalProjectId,
type MachineId,
+ type MessageQueueItem,
type SessionGoalMessage,
type SessionHistoryInput,
type SessionId,
@@ -274,6 +275,145 @@ describe('SessionExecutionService', () => {
expect([...runningChildren]).toEqual(['child-2']);
expect(deps.getActiveTurnId(request.sessionId)).toBe('parent-1');
});
+
+ it('steers an exact later queue item without reordering the remaining queue', async () => {
+ const sessionId = 'session-queue-steer' as SessionId;
+ const activeTurnId = 'assistant:active';
+ const queue = ['A', 'B', 'C'].map(
+ (id): MessageQueueItem => ({
+ $cid: id,
+ task: `task ${id}`,
+ userId: 'owner-user',
+ userTurnId: `user:${id}`,
+ timestamp: '2026-09-13T00:00:00.000Z',
+ acpSessionConfig: {
+ prompt: `task ${id}`,
+ cliType: 'builtin',
+ agentType: 'codex',
+ },
+ })
+ );
+ const history: SessionHistoryInput[] = [];
+ const sessionDoc = {
+ getMetaState: vi.fn(async () => ({
+ id: sessionId,
+ userId: 'owner-user',
+ machineId: 'machine-1',
+ cliType: 'builtin',
+ agentType: 'codex',
+ })),
+ consumeMessageQueueItemAsUserTurn: vi.fn(
+ async (
+ cid: string,
+ buildEntry: (item: MessageQueueItem) => SessionHistoryInput | null
+ ) => {
+ const index = queue.findIndex((item) => item.$cid === cid);
+ if (index < 0) return { type: 'missing' as const };
+ const entry = buildEntry(queue[index]!);
+ if (!entry) return { type: 'invalid' as const };
+ history.push(entry);
+ queue.splice(index, 1);
+ return { type: 'consumed' as const, entry };
+ }
+ ),
+ };
+ const deps = createBaseDeps({
+ workspaceDocument: {
+ getOrCreateSessionDoc: vi.fn(async () => sessionDoc),
+ } as unknown as LoroDocumentManager,
+ });
+ const service = new SessionExecutionService(deps);
+ const runtime = {
+ sessionId,
+ turnId: activeTurnId,
+ userTurnId: 'active',
+ session: {},
+ promptInFlight: true,
+ cancelRequested: false,
+ };
+ (
+ service as unknown as {
+ turnRuntimeBySession: Map;
+ }
+ ).turnRuntimeBySession.set(sessionId, runtime);
+ const cancel = vi.spyOn(service, 'cancelSession').mockResolvedValue({ success: true });
+
+ await expect(
+ service.steerQueuedMessage({
+ sessionId,
+ expectedTurnId: activeTurnId,
+ queueItemId: 'C',
+ requestedByUserId: 'owner-user',
+ })
+ ).resolves.toMatchObject({
+ accepted: true,
+ disposition: 'accepted',
+ queueItemId: 'C',
+ userTurnId: 'user:C',
+ });
+
+ expect(queue.map((item) => item.$cid)).toEqual(['A', 'B']);
+ expect(history).toHaveLength(1);
+ expect(history[0]).toMatchObject({ id: 'user:C', role: 'user' });
+ expect(cancel).toHaveBeenCalledWith(expect.objectContaining({ turnId: activeTurnId }));
+ expect(sessionDoc.consumeMessageQueueItemAsUserTurn.mock.invocationCallOrder[0]).toBeLessThan(
+ cancel.mock.invocationCallOrder[0]!
+ );
+ });
+
+ it('keeps the active turn running when the selected queue identity is gone', async () => {
+ const sessionId = 'session-queue-steer-missing' as SessionId;
+ const activeTurnId = 'assistant:active';
+ const sessionDoc = {
+ getMetaState: vi.fn(async () => ({
+ id: sessionId,
+ userId: 'owner-user',
+ machineId: 'machine-1',
+ cliType: 'builtin',
+ agentType: 'codex',
+ })),
+ consumeMessageQueueItemAsUserTurn: vi.fn(async () => ({ type: 'missing' as const })),
+ };
+ const deps = createBaseDeps({
+ workspaceDocument: {
+ getOrCreateSessionDoc: vi.fn(async () => sessionDoc),
+ } as unknown as LoroDocumentManager,
+ });
+ const service = new SessionExecutionService(deps);
+ const runtime = {
+ sessionId,
+ turnId: activeTurnId,
+ userTurnId: 'active',
+ session: {},
+ promptInFlight: true,
+ cancelRequested: false,
+ };
+ (
+ service as unknown as {
+ turnRuntimeBySession: Map;
+ }
+ ).turnRuntimeBySession.set(sessionId, runtime);
+ const cancel = vi.spyOn(service, 'cancelSession').mockResolvedValue({ success: true });
+
+ await expect(
+ service.steerQueuedMessage({
+ sessionId,
+ expectedTurnId: activeTurnId,
+ queueItemId: 'C',
+ requestedByUserId: 'owner-user',
+ })
+ ).resolves.toMatchObject({
+ accepted: false,
+ disposition: 'queue-item-missing',
+ queueItemId: 'C',
+ });
+ expect(cancel).not.toHaveBeenCalled();
+ expect(
+ (service as unknown as { turnRuntimeBySession: Map }).turnRuntimeBySession.get(
+ sessionId
+ )
+ ).toBe(runtime);
+ });
it('advances one session owner through consecutive prompt handoffs', async () => {
const steerPrompt = vi.fn(() => ({
completion: new Promise(() => {}),
diff --git a/locales/en.json b/locales/en.json
index d4b547342..3e45dd222 100644
--- a/locales/en.json
+++ b/locales/en.json
@@ -1981,6 +1981,7 @@
"sessions.proposedPlanDecision.executing": "Implementing plan...",
"sessions.queueEditError": "Failed to edit message",
"sessions.queueError": "Failed to queue message",
+ "sessions.queueItemMissing": "This queued message is no longer available",
"sessions.queueRemoveError": "Failed to remove message from queue",
"sessions.queueReorderError": "Failed to reorder messages",
"sessions.removeImage": "Remove image",
diff --git a/locales/zh_CN.json b/locales/zh_CN.json
index 0e7646135..ec4dbc36d 100644
--- a/locales/zh_CN.json
+++ b/locales/zh_CN.json
@@ -1981,6 +1981,7 @@
"sessions.proposedPlanDecision.executing": "正在实施计划...",
"sessions.queueEditError": "编辑消息失败",
"sessions.queueError": "消息入队失败",
+ "sessions.queueItemMissing": "这条排队消息已不存在",
"sessions.queueRemoveError": "移除消息失败",
"sessions.queueReorderError": "调整消息顺序失败",
"sessions.removeImage": "移除图片",
diff --git a/packages/components/src/atoms/runtime.ts b/packages/components/src/atoms/runtime.ts
index b292518d1..6addaec46 100644
--- a/packages/components/src/atoms/runtime.ts
+++ b/packages/components/src/atoms/runtime.ts
@@ -16,6 +16,7 @@ import type {
SessionPreparationSpec,
SessionPrepareCancelResponse,
SessionPrepareResponse,
+ SessionQueueSteerResponse,
SessionSteerResponse,
SessionGoalAction,
SessionGoalResponse,
@@ -302,6 +303,16 @@ export type WorkspaceRuntime = {
},
options?: { timeoutMs?: number }
) => Promise;
+ requestSessionQueueSteer: (
+ machineId: MachineId,
+ args: {
+ sessionId: SessionId;
+ expectedTurnId: string;
+ queueItemId: string;
+ requestedByUserId: string;
+ },
+ options?: { timeoutMs?: number }
+ ) => Promise;
requestSessionGoal: (
machineId: MachineId,
args: {
diff --git a/packages/components/src/components/sessions/message-queue/AGENTS.md b/packages/components/src/components/sessions/message-queue/AGENTS.md
index e9d1cd7a5..d70efcb8f 100644
--- a/packages/components/src/components/sessions/message-queue/AGENTS.md
+++ b/packages/components/src/components/sessions/message-queue/AGENTS.md
@@ -9,15 +9,11 @@ queued-turn list (`message-queue-display.tsx`, `message-queue-row.tsx`,
`../session-message-submit-route.ts` and is described in
[.agents/docs/sessions-live-status.md](../../../../../../.agents/docs/sessions-live-status.md).
-A queued item's Steer action uses native acknowledged steering only when the
-authoritative ACP capability cache advertises it. Never infer steering support
-from built-in/custom config type or agent identity; unsupported and stale cache
-entries retain the interrupt-and-send fallback.
-
-Every queued row offers Steer while an active turn can accept it. The compatibility
-fallback must move a selected later row to the queue head before interrupting, and
-must not interrupt if that reorder fails. A row's number and message body are one
-drag activator; its Steer, edit, and remove controls stay outside that activator.
+Every queued row offers Steer while an active turn can accept it. Steer sends the
+selected `$cid` and expected active turn to the owning daemon; it never reorders,
+removes, or materializes a queue row in the renderer. A rejected or missing identity
+must leave the active turn running. A row's number and message body are one drag
+activator; its Steer, edit, and remove controls stay outside that activator.
The queue intentionally stays OUT of the composer info bar
([.agents/docs/sessions-info-bar.md](../../../../../../.agents/docs/sessions-info-bar.md)).
diff --git a/packages/components/src/components/sessions/message-queue/index.ts b/packages/components/src/components/sessions/message-queue/index.ts
index 4f924c2df..078978312 100644
--- a/packages/components/src/components/sessions/message-queue/index.ts
+++ b/packages/components/src/components/sessions/message-queue/index.ts
@@ -2,11 +2,6 @@ export { MessageQueueDisplay } from './message-queue-display';
export type { MessageQueueDisplayProps } from './message-queue-display';
export { MessageQueueRow } from './message-queue-row';
export type { MessageQueueRowProps } from './message-queue-row';
-export {
- resolveFallbackQueueSteerPreparation,
- steerQueuedMessageWithFallback,
- shouldRequestNativeQueueSteer,
-} from './queued-message-steer';
export { QueuedImagePreview } from './queued-image-preview';
export type { QueuedImageBlock } from './queued-image-preview';
export {
diff --git a/packages/components/src/components/sessions/message-queue/queued-message-steer.ts b/packages/components/src/components/sessions/message-queue/queued-message-steer.ts
deleted file mode 100644
index 589adc20f..000000000
--- a/packages/components/src/components/sessions/message-queue/queued-message-steer.ts
+++ /dev/null
@@ -1,51 +0,0 @@
-import type { AcpCapabilityAuthority, AcpCapabilityCacheEntry } from '@lody/shared';
-
-export type FallbackQueueSteerPreparation =
- | { type: 'ready' }
- | { type: 'reorder'; activeCid: string; overCid: string }
- | { type: 'missing' };
-
-export function resolveFallbackQueueSteerPreparation(
- queueItemCids: readonly string[],
- selectedCid: string
-): FallbackQueueSteerPreparation {
- const selectedIndex = queueItemCids.indexOf(selectedCid);
- if (selectedIndex < 0) return { type: 'missing' };
- if (selectedIndex === 0) return { type: 'ready' };
- return {
- type: 'reorder',
- activeCid: selectedCid,
- overCid: queueItemCids[0]!,
- };
-}
-
-export async function steerQueuedMessageWithFallback({
- queueItemCids,
- selectedCid,
- reorder,
- interrupt,
-}: {
- queueItemCids: readonly string[];
- selectedCid: string;
- reorder: (activeCid: string, overCid: string) => Promise;
- interrupt: () => Promise;
-}): Promise<'steered' | 'missing' | 'reorder_failed'> {
- const preparation = resolveFallbackQueueSteerPreparation(queueItemCids, selectedCid);
- if (preparation.type === 'missing') return 'missing';
- if (preparation.type === 'reorder') {
- try {
- await reorder(preparation.activeCid, preparation.overCid);
- } catch {
- return 'reorder_failed';
- }
- }
- await interrupt();
- return 'steered';
-}
-
-export function shouldRequestNativeQueueSteer(
- authority: AcpCapabilityAuthority,
- capability: Pick | undefined
-): boolean {
- return authority === 'authoritative' && capability?.acknowledgedSteer === true;
-}
diff --git a/packages/components/src/components/sessions/session-chat-input-area.tsx b/packages/components/src/components/sessions/session-chat-input-area.tsx
index 36c87b01d..972c3ccca 100644
--- a/packages/components/src/components/sessions/session-chat-input-area.tsx
+++ b/packages/components/src/components/sessions/session-chat-input-area.tsx
@@ -474,7 +474,7 @@ export interface SessionChatInputAreaProps {
export type SessionTurnAgentRoleSelection = ComposerTurnAgentRoleSelection;
export type SessionChatInputSubmitOptions = {
- invertQueuedBehavior?: boolean;
+ queueBehavior?: 'inverse';
};
export type SessionChatInputAreaHandle = {
@@ -1762,10 +1762,7 @@ export const SessionChatInputArea = memo(
[pastedTextDrafts, session.id, updatePastedTextDraftsForSession]
);
- const invertQueuedBehaviorForNextSubmitRef = useRef(false);
- const sendMessage = useCallback(async () => {
- const invertQueuedBehavior = invertQueuedBehaviorForNextSubmitRef.current;
- invertQueuedBehaviorForNextSubmitRef.current = false;
+ const sendMessage = useCallback(async (options?: SessionChatInputSubmitOptions) => {
if (freeTurnLimitNotice && freeTurnLimitNotice.current >= freeTurnLimitNotice.limit) {
capturePostHogEvent(postHog, 'session/input_blocked', {
reason: 'free_session_turn_limit_reached',
@@ -1912,7 +1909,7 @@ export const SessionChatInputArea = memo(
const accepted = await onSendMessage(
inputBlocks,
agentRoleTurnSelectionRef.current,
- invertQueuedBehavior ? { invertQueuedBehavior: true } : undefined
+ options
);
if (accepted) {
if (submission.isCurrent()) {
@@ -2022,10 +2019,17 @@ export const SessionChatInputArea = memo(
category: 'Session',
keybindings: getCommandKeybindings('session.sendWithInverseQueueBehavior'),
allowInTextInput: true,
- when: () => hasSendableContent && !isSendActionDisabled,
+ when: () => {
+ const activeElement = document.activeElement;
+ return (
+ activeElement instanceof Element &&
+ activeElement.closest('[data-lody-composer-input]') !== null &&
+ hasSendableContent &&
+ !isSendActionDisabled
+ );
+ },
run: () => {
- invertQueuedBehaviorForNextSubmitRef.current = true;
- void sendMessage();
+ void sendMessage({ queueBehavior: 'inverse' });
},
},
commandsEnabled
diff --git a/packages/components/src/components/sessions/session-chat-interface.tsx b/packages/components/src/components/sessions/session-chat-interface.tsx
index de922c51e..21aa67e52 100644
--- a/packages/components/src/components/sessions/session-chat-interface.tsx
+++ b/packages/components/src/components/sessions/session-chat-interface.tsx
@@ -66,11 +66,7 @@ import {
type SessionTurnAgentRoleSelection,
} from './session-chat-input-area';
import { useSessionMcpSelection } from '@/hooks/use-session-mcp-selection';
-import {
- MessageQueueDisplay,
- shouldRequestNativeQueueSteer,
- steerQueuedMessageWithFallback,
-} from './message-queue';
+import { MessageQueueDisplay } from './message-queue';
import { useTranslation } from 'react-i18next';
import { useRouter } from '@tanstack/react-router';
import { toast } from 'sonner';
@@ -1911,7 +1907,7 @@ export type SessionChatInterfaceHandle = {
export type DispatchInputBlocksOptions = {
forceQueue?: boolean;
forceDirect?: boolean;
- invertQueuedBehavior?: boolean;
+ queueBehavior?: 'inverse';
modeIdOverride?: string | null;
modelIdOverride?: string | null;
configOptionValuesOverride?: Record;
@@ -2410,6 +2406,7 @@ export const SessionChatInterface = memo(
requestSessionCancel,
requestSessionDispatch,
requestSessionGoal,
+ requestSessionQueueSteer,
requestSessionSteer,
touchSessionActivity,
transferSessionOwner,
@@ -3956,7 +3953,7 @@ export const SessionChatInterface = memo(
const submitRoute = resolveSessionMessageSubmitRoute({
forceDirect,
forceQueue: options?.forceQueue === true,
- invertQueuedBehavior: options?.invertQueuedBehavior === true,
+ queueBehavior: options?.queueBehavior,
isPromptBusy: isAgentBusy,
hasUnfinishedAssistantTurn: activeAssistantTurnId != null,
queuedMessageBehavior,
@@ -3983,7 +3980,7 @@ export const SessionChatInterface = memo(
...inputSummary,
force_queue: Boolean(options?.forceQueue),
force_direct: forceDirect,
- invert_queued_behavior: Boolean(options?.invertQueuedBehavior),
+ queue_behavior_override: options?.queueBehavior ?? 'default',
submit_route: submitRoute.type,
is_agent_busy: isAgentBusy,
mode_id: turnModeId ?? null,
@@ -4108,7 +4105,7 @@ export const SessionChatInterface = memo(
async (
inputBlocks: SessionInputBlock[],
agentRole?: SessionTurnAgentRoleSelection,
- options?: Pick
+ options?: Pick
): Promise => {
return await dispatchInputBlocks(inputBlocks, { agentRole, ...options });
},
@@ -5157,109 +5154,71 @@ export const SessionChatInterface = memo(
workspaceId,
]);
- const handleInterruptAndSend = useCallback(
- async (item: MessageQueueItem) => {
- if (isExternalHistoryRefreshing) {
- captureSessionEvent('session/queue_interrupt_blocked', {
- reason: 'external_history_syncing',
- queue_item_id: item.$cid,
- });
- return;
- }
- if (!workspaceId || !activeAssistantTurnId) {
- captureSessionEvent('session/queue_interrupt_blocked', {
- reason: !workspaceId ? 'missing_workspace' : 'missing_active_turn',
- queue_item_id: item.$cid,
- });
- toast.error(t('sessions.interruptFailed', 'Failed to interrupt current task'));
- return;
- }
- setInputActionState('ready');
- pendingUserInterruptRef.current = true;
+ const handleReorderQueueItem = useCallback(
+ async (activeCid: string, overCid: string) => {
try {
- await requestSessionCancel(session.id, activeAssistantTurnId);
- captureSessionEvent('session/queue_interrupt_succeeded', {
- queue_item_id: item.$cid,
- active_assistant_turn_id: activeAssistantTurnId,
+ captureSessionEvent('session/queue_item_reorder_requested', {
+ queue_item_id: activeCid,
+ over_queue_item_id: overCid,
+ });
+ await reorderMessageQueueItem(activeCid, overCid);
+ captureSessionEvent('session/queue_item_reordered', {
+ queue_item_id: activeCid,
+ over_queue_item_id: overCid,
});
} catch (error) {
- console.error('Failed to interrupt for queued message', error);
- pendingUserInterruptRef.current = false;
- captureSessionEvent('session/queue_interrupt_failed', {
- queue_item_id: item.$cid,
- active_assistant_turn_id: activeAssistantTurnId,
+ console.error('Failed to reorder queued message', error);
+ captureSessionEvent('session/queue_item_reorder_failed', {
+ queue_item_id: activeCid,
+ over_queue_item_id: overCid,
error_name: error instanceof Error ? error.name : typeof error,
error_message: getErrorMessage(error),
});
- toast.error(t('sessions.interruptFailed', 'Failed to interrupt current task'), {
+ toast.error(t('sessions.queueReorderError', 'Failed to reorder messages'), {
description: getErrorMessage(error),
});
}
},
- [
- activeAssistantTurnId,
- captureSessionEvent,
- isExternalHistoryRefreshing,
- requestSessionCancel,
- session.id,
- t,
- workspaceId,
- ]
+ [captureSessionEvent, reorderMessageQueueItem, t]
);
- const handleNativeSteerQueuedMessage = useCallback(
+ const handleSteerQueuedMessage = useCallback(
async (item: MessageQueueItem) => {
- if (isExternalHistoryRefreshing || !activeAssistantTurnId) {
- return;
- }
- if (steeringQueueItemIdsRef.current.has(item.$cid)) {
+ if (isExternalHistoryRefreshing || !activeAssistantTurnId || !currentUser?.id) {
return;
}
+ if (steeringQueueItemIdsRef.current.has(item.$cid)) return;
steeringQueueItemIdsRef.current.add(item.$cid);
try {
- const inputConfig = normalizeSessionTurnInputConfig(item.acpSessionConfig);
- if (!inputConfig) {
- throw new Error('Queued message input config is invalid');
- }
- const inputBlocks = normalizeSessionInputBlocks(
- inputConfig.inputBlocks,
- inputConfig.prompt ?? item.task
+ const response = await requestSessionQueueSteer(
+ session.id,
+ activeAssistantTurnId,
+ item.$cid,
+ { machineId: session.machineId, requestedByUserId: currentUser.id }
);
- const pendingHistoryEntry = buildPendingUserHistoryEntry({
- userId: item.userId,
- inputBlocks,
- timestamp: item.timestamp,
- inputConfig,
- status: 'pending_apply',
- });
- if (!pendingHistoryEntry) {
- throw new Error('Queued message is empty');
- }
- const queuedUserTurnId = item.userTurnId?.trim() || `queued-${item.$cid}`;
- const { entry: historyEntry } = await addSessionHistory({
- ...pendingHistoryEntry,
- id: queuedUserTurnId,
- });
- await removeMessageQueueItem(item.$cid);
- trackMessageSend(historyEntry.id);
- touchSessionActivity(session.id).catch((error: unknown) => {
- console.warn('Failed to update session activity for steer', error);
- });
- const applied = await guideHistoryEntry(historyEntry.id, activeAssistantTurnId);
- captureSessionEvent('session/queue_guide_result', {
+ captureSessionEvent('session/queue_steer_result', {
queue_item_id: item.$cid,
active_assistant_turn_id: activeAssistantTurnId,
- applied,
+ accepted: response?.accepted === true,
+ disposition: response?.disposition ?? 'no_response',
});
+ if (!response?.accepted) {
+ toast.error(t('sessions.interruptFailed', 'Failed to interrupt current task'), {
+ description:
+ response?.disposition === 'queue-item-missing'
+ ? t('sessions.queueItemMissing', 'That queued message is no longer available')
+ : response?.error,
+ });
+ }
} catch (error) {
- console.error('Failed to guide with queued message', error);
- captureSessionEvent('session/queue_guide_failed', {
+ console.error('Failed to steer queued message', error);
+ captureSessionEvent('session/queue_steer_failed', {
queue_item_id: item.$cid,
active_assistant_turn_id: activeAssistantTurnId,
error_name: error instanceof Error ? error.name : typeof error,
error_message: getErrorMessage(error),
});
- toast.error(t('sessions.sendError'), {
+ toast.error(t('sessions.interruptFailed', 'Failed to interrupt current task'), {
description: getErrorMessage(error),
});
} finally {
@@ -5268,77 +5227,13 @@ export const SessionChatInterface = memo(
},
[
activeAssistantTurnId,
- addSessionHistory,
captureSessionEvent,
- guideHistoryEntry,
+ currentUser?.id,
isExternalHistoryRefreshing,
- removeMessageQueueItem,
+ requestSessionQueueSteer,
session.id,
+ session.machineId,
t,
- touchSessionActivity,
- trackMessageSend,
- ]
- );
-
- const queueSteerCapability = session.agentConfigId
- ? sessionMachine?.acpCapabilities?.[getAcpCapabilityCacheKey(session.agentConfigId)]
- : undefined;
- const shouldUseNativeQueueSteer = shouldRequestNativeQueueSteer(
- capabilityAuthority,
- queueSteerCapability
- );
- const handleReorderQueueItem = useCallback(
- async (activeCid: string, overCid: string) => {
- try {
- captureSessionEvent('session/queue_item_reorder_requested', {
- queue_item_id: activeCid,
- over_queue_item_id: overCid,
- });
- await reorderMessageQueueItem(activeCid, overCid);
- captureSessionEvent('session/queue_item_reordered', {
- queue_item_id: activeCid,
- over_queue_item_id: overCid,
- });
- } catch (error) {
- console.error('Failed to reorder queued message', error);
- captureSessionEvent('session/queue_item_reorder_failed', {
- queue_item_id: activeCid,
- over_queue_item_id: overCid,
- error_name: error instanceof Error ? error.name : typeof error,
- error_message: getErrorMessage(error),
- });
- toast.error(t('sessions.queueReorderError', 'Failed to reorder messages'), {
- description: getErrorMessage(error),
- });
- throw error;
- }
- },
- [captureSessionEvent, reorderMessageQueueItem, t]
- );
-
- const handleSteerQueuedMessage = useCallback(
- async (item: MessageQueueItem) => {
- if (shouldUseNativeQueueSteer) {
- await handleNativeSteerQueuedMessage(item);
- return;
- }
-
- // The compatibility path cancels the active turn and lets the daemon promote
- // the queue head. Move an explicitly selected later item to that position first,
- // preserving the user's choice without creating a second dispatch path.
- await steerQueuedMessageWithFallback({
- queueItemCids: messageQueue.map((queuedItem) => queuedItem.$cid),
- selectedCid: item.$cid,
- reorder: handleReorderQueueItem,
- interrupt: () => handleInterruptAndSend(item),
- });
- },
- [
- handleInterruptAndSend,
- handleNativeSteerQueuedMessage,
- handleReorderQueueItem,
- messageQueue,
- shouldUseNativeQueueSteer,
]
);
diff --git a/packages/components/src/components/sessions/session-message-submit-route.ts b/packages/components/src/components/sessions/session-message-submit-route.ts
index 7ce93d2bb..f86361ef0 100644
--- a/packages/components/src/components/sessions/session-message-submit-route.ts
+++ b/packages/components/src/components/sessions/session-message-submit-route.ts
@@ -6,7 +6,7 @@ export type SessionMessageSubmitRoute =
export type SessionMessageSubmitRouteInput = {
forceDirect: boolean;
forceQueue: boolean;
- invertQueuedBehavior: boolean;
+ queueBehavior?: 'inverse';
isPromptBusy: boolean;
hasUnfinishedAssistantTurn: boolean;
queuedMessageBehavior: 'queue' | 'guide';
@@ -24,7 +24,7 @@ export type SessionMessageSubmitRouteInput = {
export function resolveSessionMessageSubmitRoute({
forceDirect,
forceQueue,
- invertQueuedBehavior,
+ queueBehavior,
isPromptBusy,
hasUnfinishedAssistantTurn,
queuedMessageBehavior,
@@ -32,7 +32,7 @@ export function resolveSessionMessageSubmitRoute({
if (forceDirect) {
return { type: 'direct_dispatch' };
}
- const effectiveQueuedMessageBehavior = invertQueuedBehavior
+ const effectiveQueuedMessageBehavior = queueBehavior === 'inverse'
? queuedMessageBehavior === 'queue'
? 'guide'
: 'queue'
diff --git a/packages/components/src/hooks/use-session-actions.ts b/packages/components/src/hooks/use-session-actions.ts
index eb5b49347..073d70260 100644
--- a/packages/components/src/hooks/use-session-actions.ts
+++ b/packages/components/src/hooks/use-session-actions.ts
@@ -17,6 +17,7 @@ import type {
MachineFlockKey,
SessionGoalAction,
SessionGoalResponse,
+ SessionQueueSteerResponse,
} from '@lody/shared';
import {
getMachineRoomId,
@@ -301,6 +302,12 @@ export type SessionActions = {
userTurnId: string,
options?: { machineId?: MachineId | null }
) => Promise;
+ requestSessionQueueSteer: (
+ sessionId: SessionId,
+ expectedTurnId: string,
+ queueItemId: string,
+ options: { requestedByUserId: string; machineId?: MachineId | null }
+ ) => Promise;
/**
* Run a goal action through the agent's control extension.
*
@@ -957,6 +964,39 @@ export function useSessionActions(): SessionActions {
[requestSessionDispatch, runtime, store]
);
+ const requestSessionQueueSteer = useCallback(
+ async (
+ sessionId: SessionId,
+ expectedTurnId: string,
+ queueItemId: string,
+ options: { requestedByUserId: string; machineId?: MachineId | null }
+ ): Promise => {
+ if (!runtime) {
+ throw new Error('Runtime not ready');
+ }
+ const roomId = getSessionRoomId(sessionId);
+ let machineId = options.machineId ?? null;
+ if (!machineId) {
+ const existing = await runtime.repo.getDocMeta(roomId);
+ const meta = isLoroRepoDocDeleted(existing)
+ ? undefined
+ : (existing?.meta as SessionMeta | undefined);
+ machineId = meta?.machineId ?? null;
+ }
+ const requestedByUserId = options.requestedByUserId.trim();
+ if (!machineId || !requestedByUserId) {
+ return null;
+ }
+ return await runtime.requestSessionQueueSteer(machineId, {
+ sessionId,
+ expectedTurnId,
+ queueItemId,
+ requestedByUserId,
+ });
+ },
+ [runtime]
+ );
+
const touchSessionActivity = useCallback(
async (sessionId: SessionId) => {
if (!runtime) {
@@ -1291,6 +1331,7 @@ export function useSessionActions(): SessionActions {
addSessionHistory,
requestSessionDispatch,
requestSessionCancel,
+ requestSessionQueueSteer,
requestSessionSteer,
requestSessionGoal,
touchSessionActivity,
diff --git a/packages/components/src/lib/commands/shortcuts.ts b/packages/components/src/lib/commands/shortcuts.ts
index 0a674f39b..461bc373f 100644
--- a/packages/components/src/lib/commands/shortcuts.ts
+++ b/packages/components/src/lib/commands/shortcuts.ts
@@ -68,7 +68,7 @@ export const COMMAND_SHORTCUTS: Record =
// Desktop ⌘L focuses the composer. On web the browser owns ⌘L (Open Location),
// so leave it unbound — the hint chip follows the resolved binding.
'session.focusInput': [electron('Mod+l')],
- 'session.sendWithInverseQueueBehavior': [whileComposerFocused('Mod+Shift+Enter')],
+ 'session.sendWithInverseQueueBehavior': ['Mod+Shift+Enter'],
'session.toggleExplorerSidebar': ['Mod+Alt+b'],
'session.copyCurrentBranch': ['Alt+Shift+b'],
'session.copyUrl': ['Alt+Shift+c'],
diff --git a/packages/components/src/providers/create-workspace-runtime.ts b/packages/components/src/providers/create-workspace-runtime.ts
index 9a9d448de..ac4e7acc9 100644
--- a/packages/components/src/providers/create-workspace-runtime.ts
+++ b/packages/components/src/providers/create-workspace-runtime.ts
@@ -1679,6 +1679,7 @@ export async function createWorkspaceRuntime(deps: RuntimeDeps): Promise => {
+ try {
+ if (await canUseLocalMachineRpc(machineId)) {
+ const response = await getLocalMachineRpcSender()?.({
+ machineId,
+ workspaceId,
+ method: 'session/queue-steer',
+ params: args,
+ timeoutMs: options?.timeoutMs ?? 5_000,
+ });
+ if (response && !response.ok) {
+ return {
+ type: 'session/queue-steer_response',
+ sessionId: args.sessionId,
+ queueItemId: args.queueItemId,
+ accepted: false,
+ disposition: 'error',
+ error: response.error,
+ };
+ }
+ if (response?.ok) return response.result as SessionQueueSteerResponse;
+ }
+ return await (
+ await getMachineRpcClient(machineId)
+ ).requestSessionQueueSteer({
+ ...args,
+ timeoutMs: options?.timeoutMs ?? 5_000,
+ });
+ } catch (error) {
+ return {
+ type: 'session/queue-steer_response',
+ sessionId: args.sessionId,
+ queueItemId: args.queueItemId,
+ accepted: false,
+ disposition: 'error',
+ error: error instanceof Error ? error.message : String(error),
+ };
+ }
+ };
+
const requestSessionGoal = async (
machineId: MachineId,
args: {
@@ -1173,6 +1223,7 @@ export function createWorkspaceMachineRpcFacade(deps: WorkspaceMachineRpcFacadeD
return {
requestSessionCancel,
+ requestSessionQueueSteer,
requestSessionSteer,
requestSessionGoal,
requestSessionTerminate,
diff --git a/packages/components/tests/queued-message-steer.test.ts b/packages/components/tests/queued-message-steer.test.ts
deleted file mode 100644
index 542bf1d04..000000000
--- a/packages/components/tests/queued-message-steer.test.ts
+++ /dev/null
@@ -1,74 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
- resolveFallbackQueueSteerPreparation,
- shouldRequestNativeQueueSteer,
- steerQueuedMessageWithFallback,
-} from '../src/components/sessions/message-queue/queued-message-steer';
-
-describe('shouldRequestNativeQueueSteer', () => {
- it.each([
- ['authoritative', { acknowledgedSteer: true }, true],
- ['authoritative', { acknowledgedSteer: false }, false],
- ['authoritative', undefined, false],
- ['provisional', { acknowledgedSteer: true }, false],
- ['unavailable', { acknowledgedSteer: true }, false],
- ] as const)('routes %s capability %o to native steer: %s', (authority, capability, expected) => {
- expect(shouldRequestNativeQueueSteer(authority, capability)).toBe(expected);
- });
-});
-
-describe('resolveFallbackQueueSteerPreparation', () => {
- it('moves a selected later item to the queue head before interrupting', () => {
- expect(resolveFallbackQueueSteerPreparation(['first', 'second', 'third'], 'third')).toEqual({
- type: 'reorder',
- activeCid: 'third',
- overCid: 'first',
- });
- });
-
- it('leaves the queue head in place and rejects stale selections', () => {
- expect(resolveFallbackQueueSteerPreparation(['first', 'second'], 'first')).toEqual({
- type: 'ready',
- });
- expect(resolveFallbackQueueSteerPreparation(['first', 'second'], 'missing')).toEqual({
- type: 'missing',
- });
- });
-});
-
-describe('steerQueuedMessageWithFallback', () => {
- it('reorders a later selection before interrupting', async () => {
- const events: string[] = [];
- const result = await steerQueuedMessageWithFallback({
- queueItemCids: ['first', 'second'],
- selectedCid: 'second',
- reorder: async (activeCid, overCid) => {
- events.push(`reorder:${activeCid}:${overCid}`);
- },
- interrupt: async () => {
- events.push('interrupt');
- },
- });
-
- expect(result).toBe('steered');
- expect(events).toEqual(['reorder:second:first', 'interrupt']);
- });
-
- it('does not interrupt when reordering fails', async () => {
- const events: string[] = [];
- const result = await steerQueuedMessageWithFallback({
- queueItemCids: ['first', 'second'],
- selectedCid: 'second',
- reorder: async () => {
- events.push('reorder');
- throw new Error('reorder failed');
- },
- interrupt: async () => {
- events.push('interrupt');
- },
- });
-
- expect(result).toBe('reorder_failed');
- expect(events).toEqual(['reorder']);
- });
-});
diff --git a/packages/components/tests/session-chat-input-submission.test.tsx b/packages/components/tests/session-chat-input-submission.test.tsx
index ba4a717c1..edc421553 100644
--- a/packages/components/tests/session-chat-input-submission.test.tsx
+++ b/packages/components/tests/session-chat-input-submission.test.tsx
@@ -406,7 +406,12 @@ describe('SessionChatInputArea submission feedback', () => {
it('submits the current draft with one-shot inverse queue behavior', async () => {
const onSendMessage = vi.fn(async () => true);
- await renderComposer({ sessionId: 'inverse-queue-submit', onSendMessage });
+ const textarea = await renderComposer({ sessionId: 'inverse-queue-submit', onSendMessage });
+
+ document.body.tabIndex = -1;
+ document.body.focus();
+ expect(commands.execute('session.sendWithInverseQueueBehavior')).toBe(false);
+ textarea.focus();
await act(async () => {
expect(commands.execute('session.sendWithInverseQueueBehavior')).toBe(true);
@@ -414,7 +419,7 @@ describe('SessionChatInputArea submission feedback', () => {
});
expect(onSendMessage).toHaveBeenCalledOnce();
- expect(onSendMessage.mock.calls[0]?.[2]).toEqual({ invertQueuedBehavior: true });
+ expect(onSendMessage.mock.calls[0]?.[2]).toEqual({ queueBehavior: 'inverse' });
});
it.each([
diff --git a/packages/components/tests/session-message-submit-route.test.ts b/packages/components/tests/session-message-submit-route.test.ts
index fccaba37f..dfec90f01 100644
--- a/packages/components/tests/session-message-submit-route.test.ts
+++ b/packages/components/tests/session-message-submit-route.test.ts
@@ -5,7 +5,7 @@ const resolve = (overrides: Partial {
isPromptBusy: true,
hasUnfinishedAssistantTurn: true,
queuedMessageBehavior: 'queue',
- invertQueuedBehavior: true,
+ queueBehavior: 'inverse',
})
).toEqual({ type: 'guide' });
expect(
@@ -57,7 +57,7 @@ describe('resolveSessionMessageSubmitRoute', () => {
isPromptBusy: true,
hasUnfinishedAssistantTurn: true,
queuedMessageBehavior: 'guide',
- invertQueuedBehavior: true,
+ queueBehavior: 'inverse',
})
).toEqual({ type: 'queue', reason: 'prompt_busy' });
});
diff --git a/packages/components/tests/use-session-actions.test.ts b/packages/components/tests/use-session-actions.test.ts
index 6bb045c42..ec62002b5 100644
--- a/packages/components/tests/use-session-actions.test.ts
+++ b/packages/components/tests/use-session-actions.test.ts
@@ -351,6 +351,37 @@ describe('useSessionActions', () => {
return actions;
};
+ it('forwards both queue and active-turn identities for queued Steer', async () => {
+ const sessionId = 'session-queue-steer' as SessionId;
+ const machineId = 'machine-1' as MachineId;
+ const requestSessionQueueSteer = vi.fn(async () => ({
+ type: 'session/queue-steer_response' as const,
+ sessionId,
+ queueItemId: 'queue-C',
+ userTurnId: 'user-C',
+ accepted: true,
+ disposition: 'accepted' as const,
+ }));
+ const runtime = createRuntime({}) as WorkspaceRuntime & {
+ requestSessionQueueSteer: WorkspaceRuntime['requestSessionQueueSteer'];
+ };
+ runtime.requestSessionQueueSteer = requestSessionQueueSteer;
+ const actions = await renderActions(runtime);
+
+ await expect(
+ actions.requestSessionQueueSteer(sessionId, 'assistant-active', 'queue-C', {
+ machineId,
+ requestedByUserId: 'user-1',
+ })
+ ).resolves.toMatchObject({ accepted: true, queueItemId: 'queue-C' });
+ expect(requestSessionQueueSteer).toHaveBeenCalledWith(machineId, {
+ sessionId,
+ expectedTurnId: 'assistant-active',
+ queueItemId: 'queue-C',
+ requestedByUserId: 'user-1',
+ });
+ });
+
it('does not block session creation on remote stream pre-creation', async () => {
const sessionId = 'session-create-stream-pending' as SessionId;
const streamCreate = createDeferred();
diff --git a/packages/components/tests/workspace-machine-rpc-facade.test.ts b/packages/components/tests/workspace-machine-rpc-facade.test.ts
index 8b544963f..c8fb21957 100644
--- a/packages/components/tests/workspace-machine-rpc-facade.test.ts
+++ b/packages/components/tests/workspace-machine-rpc-facade.test.ts
@@ -17,6 +17,58 @@ afterEach(() => {
});
describe('createWorkspaceMachineRpcFacade', () => {
+ it('sends queued Steer as one exact local daemon operation', async () => {
+ const invoke = vi.fn(async () => ({
+ ok: true as const,
+ result: {
+ type: 'session/queue-steer_response' as const,
+ sessionId,
+ queueItemId: 'queue-C',
+ userTurnId: 'user-C',
+ accepted: true,
+ disposition: 'accepted' as const,
+ },
+ }));
+ vi.stubGlobal('window', {
+ __LODY_ELECTRON__: true,
+ ipc: { invoke },
+ });
+ const getMachineRpcClient = vi.fn();
+ const facade = createWorkspaceMachineRpcFacade({
+ workspaceId,
+ getMachineProtocolCapabilities: async () => CURRENT_MACHINE_PROTOCOL_CAPABILITIES,
+ targetRouter: {
+ getPlaneForMachine: () => 'local',
+ resolvePlaneForMachine: vi.fn(async () => 'local'),
+ },
+ getMachineRpcClient,
+ });
+
+ await expect(
+ facade.requestSessionQueueSteer(localMachineId, {
+ sessionId,
+ expectedTurnId: 'assistant-active',
+ queueItemId: 'queue-C',
+ requestedByUserId: 'user-1',
+ })
+ ).resolves.toMatchObject({ accepted: true, queueItemId: 'queue-C' });
+ expect(invoke).toHaveBeenCalledWith(
+ 'machineRpc.send',
+ expect.objectContaining({
+ machineId: localMachineId,
+ workspaceId,
+ method: 'session/queue-steer',
+ params: {
+ sessionId,
+ expectedTurnId: 'assistant-active',
+ queueItemId: 'queue-C',
+ requestedByUserId: 'user-1',
+ },
+ })
+ );
+ expect(getMachineRpcClient).not.toHaveBeenCalled();
+ });
+
it('never sends a scoped cancel to a daemon without the scoped-cancel protocol', async () => {
const facade = createWorkspaceMachineRpcFacade({
workspaceId,
diff --git a/packages/loro-streams-rpc/AGENTS.md b/packages/loro-streams-rpc/AGENTS.md
index c64b4508a..d3d961d8e 100644
--- a/packages/loro-streams-rpc/AGENTS.md
+++ b/packages/loro-streams-rpc/AGENTS.md
@@ -46,7 +46,7 @@ and the `file/preview` namespace are in
needs read-check-write atomicity serializes in its own service layer (Code Collab
`save-text` per absolute path in `code-collab-v2-service.ts`), not in the request loop.
- Control-plane methods (`machine/status`, `machine/ping`, `session/cancel`,
- `session/live-status`, `session/steer`, `session/terminate`, `machine/restart`,
+ `session/live-status`, `session/queue-steer`, `session/steer`, `session/terminate`, `machine/restart`,
`machine/upgrade`, `session/dispatch-turn`)
bypass the shared semaphore and run on a small dedicated lane
(`CONTROL_METHODS` in `machine-rpc-server.ts`) so saturated code-collab
diff --git a/packages/loro-streams-rpc/src/machine-rpc-server.ts b/packages/loro-streams-rpc/src/machine-rpc-server.ts
index f45ae91cd..a06a46adb 100644
--- a/packages/loro-streams-rpc/src/machine-rpc-server.ts
+++ b/packages/loro-streams-rpc/src/machine-rpc-server.ts
@@ -34,6 +34,7 @@ import type {
PreviewTarget,
PreviewTargetApproval,
SessionCancelResponse,
+ SessionQueueSteerResponse,
SessionPreparationCancelSpec,
SessionPreparationSpec,
SessionPrepareCancelResponse,
@@ -118,6 +119,7 @@ const CONTROL_METHODS: ReadonlySet = new Set([
'machine/acp-capabilities-refresh-cancel',
'session/cancel',
'session/live-status',
+ 'session/queue-steer',
'session/steer',
'session/goal',
'session/terminate',
@@ -350,6 +352,12 @@ type RpcServerDeps = {
getSessionLiveStatus?: (args: {
sessionId: SessionId;
}) => Promise;
+ steerQueuedMessage?: (args: {
+ sessionId: SessionId;
+ expectedTurnId: string;
+ queueItemId: string;
+ requestedByUserId: string;
+ }) => Promise;
steerSession?: (args: {
sessionId: SessionId;
expectedTurnId: string;
@@ -1107,6 +1115,23 @@ export class LoroStreamsMachineRpcServer {
await this.appendResultResponse(request.replyTo, request.id, request.method, response);
return;
}
+ case 'session/queue-steer': {
+ if (!this.deps.steerQueuedMessage) {
+ await this.appendErrorResponse(request.replyTo, request.id, request.method, {
+ code: LORO_STREAMS_RPC_ERROR_CODES.methodUnavailable,
+ message: 'Queued message steer is not available on this machine.',
+ });
+ return;
+ }
+ const response = await this.deps.steerQueuedMessage({
+ sessionId: request.params.sessionId as SessionId,
+ expectedTurnId: request.params.expectedTurnId,
+ queueItemId: request.params.queueItemId,
+ requestedByUserId: request.params.requestedByUserId,
+ });
+ await this.appendResultResponse(request.replyTo, request.id, request.method, response);
+ return;
+ }
case 'session/goal': {
if (!this.deps.controlSessionGoal) {
await this.appendErrorResponse(request.replyTo, request.id, request.method, {
@@ -1615,6 +1640,7 @@ export class LoroStreamsMachineRpcServer {
| MachineBugReportResponse
| SessionCancelResponse
| LoroSessionLiveStatusRpcResponse
+ | SessionQueueSteerResponse
| SessionSteerResponse
| SessionGoalResponse
| SessionTerminateResponse
diff --git a/packages/loro-streams-rpc/src/rpc.ts b/packages/loro-streams-rpc/src/rpc.ts
index 9d93870cd..cdd7e6d68 100644
--- a/packages/loro-streams-rpc/src/rpc.ts
+++ b/packages/loro-streams-rpc/src/rpc.ts
@@ -45,6 +45,7 @@ import type {
MachineStatusResponse,
MachineUpgradeResponse,
SessionCancelResponse,
+ SessionQueueSteerResponse,
SessionGoalAction,
SessionGoalResponse,
SessionPreparationCancelSpec,
@@ -94,6 +95,7 @@ import {
MachineStatusResponseSchema,
MachineUpgradeResponseSchema,
SessionCancelResponseSchema,
+ SessionQueueSteerResponseSchema,
SessionPreparationCancelSpecSchema,
SessionPreparationSpecSchema,
SessionPrepareCancelResponseSchema,
@@ -192,6 +194,7 @@ export const LoroStreamsRpcMethodSchema = z.enum([
'file/preview',
'session/cancel',
'session/live-status',
+ 'session/queue-steer',
'session/steer',
'session/goal',
'session/terminate',
@@ -472,6 +475,18 @@ export const LoroSessionSteerRpcRequestSchema = BaseRpcRequestSchema.extend({
.strict(),
}).strict();
+export const LoroSessionQueueSteerRpcRequestSchema = BaseRpcRequestSchema.extend({
+ method: z.literal('session/queue-steer'),
+ params: z
+ .object({
+ sessionId: SessionIdSchema,
+ expectedTurnId: z.string().trim().min(1),
+ queueItemId: z.string().trim().min(1),
+ requestedByUserId: z.string().trim().min(1),
+ })
+ .strict(),
+}).strict();
+
export const LoroSessionTerminateRpcRequestSchema = BaseRpcRequestSchema.extend({
method: z.literal('session/terminate'),
params: z
@@ -599,6 +614,7 @@ export const LoroStreamsRpcRequestSchema = z.discriminatedUnion('method', [
LoroFilePreviewRpcRequestSchema,
LoroSessionCancelRpcRequestSchema,
LoroSessionLiveStatusRpcRequestSchema,
+ LoroSessionQueueSteerRpcRequestSchema,
LoroSessionSteerRpcRequestSchema,
LoroSessionGoalRpcRequestSchema,
LoroSessionTerminateRpcRequestSchema,
@@ -1442,6 +1458,7 @@ export type LoroMachineRpcResult =
| MachineBugReportResponse
| SessionCancelResponse
| LoroSessionLiveStatusRpcResponse
+ | SessionQueueSteerResponse
| SessionSteerResponse
| SessionGoalResponse
| SessionTerminateResponse
@@ -1470,6 +1487,7 @@ const toLegacyRpcErrorResponse = (
cancelContext?: { sessionId: string },
forkContext?: { sourceSessionId: string; targetSessionId: string },
editAndResendContext?: { sessionId: string; replacementUserTurnId: string },
+ queueSteerContext?: { sessionId: string; queueItemId: string },
steerContext?: { sessionId: string; userTurnId: string },
goalContext?: { sessionId: string; action: SessionGoalAction },
previewContext?: { sessionId: string },
@@ -1646,6 +1664,17 @@ const toLegacyRpcErrorResponse = (
};
}
+ if (method === 'session/queue-steer') {
+ return {
+ type: 'session/queue-steer_response',
+ sessionId: (queueSteerContext?.sessionId ?? '') as SessionQueueSteerResponse['sessionId'],
+ queueItemId: queueSteerContext?.queueItemId ?? '',
+ accepted: false,
+ disposition: 'error',
+ error: `${error.code}: ${error.message}`,
+ };
+ }
+
if (method === 'session/dispatch-turn') {
return {
type: 'session/dispatch-turn_response',
@@ -1820,6 +1849,10 @@ const parseRpcSuccessResult = async (
const parsed = SessionSteerResponseSchema.safeParse(response.result);
return parsed.success ? (parsed.data as SessionSteerResponse) : null;
}
+ if (response.method === 'session/queue-steer') {
+ const parsed = SessionQueueSteerResponseSchema.safeParse(response.result);
+ return parsed.success ? (parsed.data as SessionQueueSteerResponse) : null;
+ }
if (response.method === 'session/goal') {
const parsed = SessionGoalResponseSchema.safeParse(response.result);
return parsed.success ? (parsed.data as SessionGoalResponse) : null;
@@ -1896,6 +1929,7 @@ export type LoroStreamsRpcPendingRegistration = {
cancelContext?: { sessionId: string };
forkContext?: { sourceSessionId: string; targetSessionId: string };
editAndResendContext?: { sessionId: string; replacementUserTurnId: string };
+ queueSteerContext?: { sessionId: string; queueItemId: string };
steerContext?: { sessionId: string; userTurnId: string };
goalContext?: { sessionId: string; action: SessionGoalAction };
previewContext?: { sessionId: string };
@@ -2280,6 +2314,7 @@ export class LoroStreamsRpcResponseDispatcher {
finalPending.cancelContext,
finalPending.forkContext,
finalPending.editAndResendContext,
+ finalPending.queueSteerContext,
finalPending.steerContext,
finalPending.goalContext,
finalPending.previewContext,
@@ -2313,6 +2348,7 @@ export class LoroStreamsRpcResponseDispatcher {
finalPending.cancelContext,
finalPending.forkContext,
finalPending.editAndResendContext,
+ finalPending.queueSteerContext,
finalPending.steerContext,
finalPending.goalContext,
finalPending.previewContext,
@@ -2692,6 +2728,25 @@ export class LoroStreamsMachineRpcClient {
})) as SessionSteerResponse | null;
}
+ async requestSessionQueueSteer(options: {
+ sessionId: SessionId;
+ expectedTurnId: string;
+ queueItemId: string;
+ requestedByUserId: string;
+ timeoutMs?: number;
+ }): Promise {
+ return (await this.sendRequest({
+ method: 'session/queue-steer',
+ timeoutMs: options.timeoutMs ?? 5_000,
+ params: {
+ sessionId: options.sessionId,
+ expectedTurnId: options.expectedTurnId,
+ queueItemId: options.queueItemId,
+ requestedByUserId: options.requestedByUserId,
+ },
+ })) as SessionQueueSteerResponse | null;
+ }
+
async requestSessionGoal(options: {
sessionId: string;
action: SessionGoalAction;
@@ -3169,6 +3224,16 @@ export class LoroStreamsMachineRpcClient {
sessionId: string;
};
}
+ | {
+ method: 'session/queue-steer';
+ timeoutMs: number;
+ params: {
+ sessionId: SessionId;
+ expectedTurnId: string;
+ queueItemId: string;
+ requestedByUserId: string;
+ };
+ }
| {
method: 'session/steer';
timeoutMs: number;
@@ -3403,6 +3468,10 @@ export class LoroStreamsMachineRpcClient {
args.method === 'session/steer'
? { sessionId: args.params.sessionId, userTurnId: args.params.userTurnId }
: undefined,
+ queueSteerContext:
+ args.method === 'session/queue-steer'
+ ? { sessionId: args.params.sessionId, queueItemId: args.params.queueItemId }
+ : undefined,
goalContext:
args.method === 'session/goal'
? { sessionId: args.params.sessionId, action: args.params.action }
@@ -3512,6 +3581,9 @@ export class LoroStreamsMachineRpcClient {
case 'session/live-status':
request = { ...envelope, method: args.method, params: args.params };
break;
+ case 'session/queue-steer':
+ request = { ...envelope, method: args.method, params: args.params };
+ break;
case 'session/steer':
request = { ...envelope, method: args.method, params: args.params };
break;
@@ -3705,6 +3777,7 @@ export class LoroStreamsMachineRpcClient {
pending.cancelContext,
pending.forkContext,
pending.editAndResendContext,
+ pending.queueSteerContext,
pending.steerContext,
pending.goalContext,
pending.previewContext,
diff --git a/packages/loro-streams-rpc/tests/loro-streams-rpc.test.ts b/packages/loro-streams-rpc/tests/loro-streams-rpc.test.ts
index 204a39ad1..ab49ede0c 100644
--- a/packages/loro-streams-rpc/tests/loro-streams-rpc.test.ts
+++ b/packages/loro-streams-rpc/tests/loro-streams-rpc.test.ts
@@ -99,6 +99,30 @@ describe('session steer RPC schema', () => {
});
});
+describe('queued message steer RPC schema', () => {
+ it('carries the exact queue and active-turn identities', () => {
+ const result = LoroStreamsRpcRequestSchema.safeParse({
+ jsonrpc: '2.0',
+ id: 'request-queue-steer-1',
+ method: 'session/queue-steer',
+ rpcVersion: '1',
+ workspaceId: 'workspace-1',
+ machineId: 'machine-1',
+ replyTo: 'workspace-1:rpc:res',
+ sentAt: 1,
+ expiresAt: 2,
+ params: {
+ sessionId: 'session-1',
+ expectedTurnId: 'assistant:user-1',
+ queueItemId: 'queue-C',
+ requestedByUserId: 'user-1',
+ },
+ });
+
+ expect(result.success).toBe(true);
+ });
+});
+
describe('session preparation RPC schema', () => {
const baseRequest = {
jsonrpc: '2.0',
diff --git a/packages/shared/src/local-machine-rpc.ts b/packages/shared/src/local-machine-rpc.ts
index ef5dcbbf1..fbdab4918 100644
--- a/packages/shared/src/local-machine-rpc.ts
+++ b/packages/shared/src/local-machine-rpc.ts
@@ -37,6 +37,7 @@ import {
SessionPreviewEndpointAcquireResponseSchema,
SessionPreviewEndpointReleaseResponseSchema,
PreviewTargetSchema,
+ SessionQueueSteerResponseSchema,
SessionSteerResponseSchema,
SessionGoalResponseSchema,
SessionTerminateResponseSchema,
@@ -193,6 +194,17 @@ export const LocalMachineRpcRequestSchema = z.discriminatedUnion('method', [
method: z.literal('session/prepare-cancel'),
params: SessionPreparationCancelSpecSchema,
}).strict(),
+ BaseLocalMachineRpcRequestSchema.extend({
+ method: z.literal('session/queue-steer'),
+ params: z
+ .object({
+ sessionId: SessionIdSchema,
+ expectedTurnId: z.string().trim().min(1),
+ queueItemId: z.string().trim().min(1),
+ requestedByUserId: z.string().trim().min(1),
+ })
+ .strict(),
+ }).strict(),
BaseLocalMachineRpcRequestSchema.extend({
method: z.literal('session/steer'),
params: z
@@ -271,6 +283,7 @@ export const LocalMachineRpcResultSchema = z.union([
SessionPrepareCancelResponseSchema,
SessionPreviewEndpointAcquireResponseSchema,
SessionPreviewEndpointReleaseResponseSchema,
+ SessionQueueSteerResponseSchema,
SessionSteerResponseSchema,
SessionGoalResponseSchema,
SessionTerminateResponseSchema,
diff --git a/packages/shared/src/message-schemas.ts b/packages/shared/src/message-schemas.ts
index 8c3cd04b2..f5c0998e9 100644
--- a/packages/shared/src/message-schemas.ts
+++ b/packages/shared/src/message-schemas.ts
@@ -681,6 +681,26 @@ export const SessionSteerResponseSchema = z
})
.strict();
+export const SessionQueueSteerResponseSchema = z
+ .object({
+ type: z.literal('session/queue-steer_response'),
+ sessionId: SessionIdSchema,
+ queueItemId: z.string().trim().min(1),
+ userTurnId: z.string().trim().min(1).optional(),
+ accepted: z.boolean(),
+ disposition: z.enum([
+ 'accepted',
+ 'queue-item-missing',
+ 'invalid-queue-item',
+ 'no-active-turn',
+ 'stale-turn',
+ 'busy',
+ 'error',
+ ]),
+ error: z.string().optional(),
+ })
+ .strict();
+
export const SessionGoalResponseSchema = z
.object({
type: z.literal('session/goal_response'),
@@ -3398,6 +3418,7 @@ import type {
ServerToMachine,
SessionCancelRequest,
SessionCancelResponse,
+ SessionQueueSteerResponse,
SessionSteerRequest,
SessionSteerResponse,
SessionChatAck,
@@ -3466,6 +3487,7 @@ export type {
SessionChatAck as SessionChatAckValidated,
SessionCancelRequest as SessionCancelRequestValidated,
SessionCancelResponse as SessionCancelResponseValidated,
+ SessionQueueSteerResponse as SessionQueueSteerResponseValidated,
SessionSteerRequest as SessionSteerRequestValidated,
SessionSteerResponse as SessionSteerResponseValidated,
PermissionRequestMessage as PermissionRequestMessageValidated,
diff --git a/packages/shared/src/message.ts b/packages/shared/src/message.ts
index 46d5dc6ce..6dacc28c6 100644
--- a/packages/shared/src/message.ts
+++ b/packages/shared/src/message.ts
@@ -166,6 +166,23 @@ export interface SessionSteerResponse {
error?: string;
}
+export interface SessionQueueSteerResponse {
+ type: 'session/queue-steer_response';
+ sessionId: SessionId;
+ queueItemId: string;
+ userTurnId?: string;
+ accepted: boolean;
+ disposition:
+ | 'accepted'
+ | 'queue-item-missing'
+ | 'invalid-queue-item'
+ | 'no-active-turn'
+ | 'stale-turn'
+ | 'busy'
+ | 'error';
+ error?: string;
+}
+
/**
* Answer to a goal control request.
*
diff --git a/packages/shared/tests/local-machine-rpc.test.ts b/packages/shared/tests/local-machine-rpc.test.ts
index c3c8b7f93..56dd08fc9 100644
--- a/packages/shared/tests/local-machine-rpc.test.ts
+++ b/packages/shared/tests/local-machine-rpc.test.ts
@@ -41,6 +41,15 @@ describe('local Machine RPC', () => {
inputConfig: { prompt: 'guide' },
},
},
+ {
+ method: 'session/queue-steer',
+ params: {
+ sessionId: 'session-1',
+ expectedTurnId: 'assistant:turn-0',
+ queueItemId: 'queue-C',
+ requestedByUserId: 'user-1',
+ },
+ },
{
method: 'session/prepare',
params: {
diff --git a/packages/shared/tests/message-schemas.test.ts b/packages/shared/tests/message-schemas.test.ts
index 3d695f0a8..d91af6f6e 100644
--- a/packages/shared/tests/message-schemas.test.ts
+++ b/packages/shared/tests/message-schemas.test.ts
@@ -23,6 +23,7 @@ import {
SessionCreateRequestSchema,
SessionSteerRequestSchema,
SessionSteerResponseSchema,
+ SessionQueueSteerResponseSchema,
SessionImageUploadResponseSchema,
SessionIdSchema,
SessionImagePayloadSchema,
@@ -211,6 +212,21 @@ describe('message-schemas session steer', () => {
});
});
+describe('message-schemas queued message steer', () => {
+ it('accepts an exact queue identity acknowledgement', () => {
+ expect(
+ SessionQueueSteerResponseSchema.safeParse({
+ type: 'session/queue-steer_response',
+ sessionId: 'session-1',
+ queueItemId: 'queue-C',
+ userTurnId: 'user-C',
+ accepted: true,
+ disposition: 'accepted',
+ }).success
+ ).toBe(true);
+ });
+});
+
describe('message-schemas image upload response', () => {
it('rejects empty uploaded image lists', () => {
const result = SessionImageUploadResponseSchema.safeParse({
diff --git a/specs/message-queue-interactions.md b/specs/message-queue-interactions.md
index 35f1952d3..d4cb6181f 100644
--- a/specs/message-queue-interactions.md
+++ b/specs/message-queue-interactions.md
@@ -15,13 +15,20 @@ the queue by hand.
## Contract
- `Mod+Shift+Enter` sends the current composer draft with the opposite of the stored
- Queue/Steer preference. This is a one-shot submission intent: it does not mutate the
- preference, and it still obeys the ordinary availability, live-activity, and unfinished-
- transcript safeguards.
+ Queue/Steer preference. The command passes `queueBehavior: "inverse"` directly to that
+ submission; ordinary Enter passes no override. This one-shot intent does not mutate the
+ preference and still obeys the ordinary availability, live-activity, and unfinished-
+ transcript safeguards. Composer focus, content, and send readiness are command-level
+ availability rules so user-rebound shortcuts retain them.
- While steering is available for the active turn, every queued message exposes Steer.
- Selecting a later item targets that exact item. Native acknowledged steering removes
- and applies the selected item directly; the compatibility path first moves it to the
- queue head and interrupts only after the reorder succeeds.
+ Selecting an item sends its durable queue identity and the expected active turn to the
+ owning daemon. The daemon revalidates both identities, atomically consumes only that row
+ into the next durable user turn, and then stops the expected turn. Queue order is never
+ rewritten as part of Steer: selecting C from `[A, B, C]` produces the active turn C and
+ leaves `[A, B]`.
+- A stale Steer selection is a failed no-op. If the selected queue identity is missing, or
+ the expected turn no longer owns execution, the daemon must not stop any turn. The
+ renderer waits for this acknowledgement and never removes or materializes the row itself.
- The number and non-editing message body form the drag target for queue reordering.
Steer, edit, and remove remain separate controls and must not begin a drag.
- Editing keeps its existing keyboard and focus behavior and disables reordering for
@@ -40,7 +47,8 @@ physical-device coverage remains separate from component tests.
- `packages/components/src/components/sessions/session-message-submit-route.ts`
- `packages/components/src/components/sessions/session-chat-input-area.tsx`
- `packages/components/src/components/sessions/message-queue/`
-- `packages/components/tests/{session-message-submit-route,queued-message-steer,message-queue-row-editing}.test.*`
+- `packages/components/tests/{session-message-submit-route,session-chat-input-submission,message-queue-row-editing}.test.*`
+- `apps/cli/{tests/session-execution-service.test.ts,src/lib/loro/doc-user-turn.test.ts}`
- [Decision record](../.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md)
This is a draft for human review. Implementation and passing tests do not approve it.
diff --git a/specs/message-queue-interactions.zh.md b/specs/message-queue-interactions.zh.md
index d9277d56b..74f03e1e2 100644
--- a/specs/message-queue-interactions.zh.md
+++ b/specs/message-queue-interactions.zh.md
@@ -13,9 +13,15 @@ Translation: current
## 契约
- `Mod+Shift+Enter` 以已保存“排队／引导”偏好的相反行为发送当前草稿。这是一次性的提交
- 意图，不修改设置，并继续遵守普通的可用性、实时活动和未完成消息记录保护。
+ 意图：命令直接为本次提交传入 `queueBehavior: "inverse"`，普通 Enter 不传覆盖项。它不
+ 修改设置，并继续遵守普通的可用性、实时活动和未完成消息记录保护。输入框聚焦、有内容且
+ 可以发送属于命令本身的可用条件，因此用户重绑快捷键后仍受同一限制。
- 当前 turn 可接受引导时，每条排队消息都提供“引导”操作。选择后续项必须以该项为目标。
- 原生带确认的 steer 直接移除并应用所选项；兼容路径先把它移到队首，只有重排成功后才中断。
+ 客户端把该项的持久 ID 和预期活动 turn 一并发给所属 daemon；daemon 重新确认两者，在一次
+ Session Doc 更新中只消费该项为下一个用户 turn，再停止预期 turn。“引导”绝不修改队列顺序：
+ 从 `[A, B, C]` 选择 C 后，正在执行的是 C，队列剩下 `[A, B]`。
+- 过期的“引导”选择必须是失败且无副作用的操作。所选 ID 已不存在，或预期 turn 已不再拥有
+ 执行权时，daemon 不得停止任何 turn。Renderer 等待 daemon 确认，不自行移除队列项或写历史。
- 序号和非编辑状态的消息正文共同组成队列重排拖动区域。“引导”、“编辑”和“移除”是独立
控件，不能触发拖动。
- 编辑状态保留已有键盘与焦点行为，并在编辑结束前禁用该行重排。
@@ -31,7 +37,8 @@ Translation: current
- `packages/components/src/components/sessions/session-message-submit-route.ts`
- `packages/components/src/components/sessions/session-chat-input-area.tsx`
- `packages/components/src/components/sessions/message-queue/`
-- `packages/components/tests/{session-message-submit-route,queued-message-steer,message-queue-row-editing}.test.*`
+- `packages/components/tests/{session-message-submit-route,session-chat-input-submission,message-queue-row-editing}.test.*`
+- `apps/cli/{tests/session-execution-service.test.ts,src/lib/loro/doc-user-turn.test.ts}`
- [决策记录](../.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md)
这是供人工审阅的草稿；实现和测试通过不代表 Spec 已获批准。
From 10bc5cd6f0d85352a8245cacbb718f64c1cfc00c Mon Sep 17 00:00:00 2001
From: wibus-wee <62133302+wibus-wee@users.noreply.github.com>
Date: Mon, 14 Sep 2026 11:32:16 +0800
Subject: [PATCH 03/15] fix: negotiate queued message steering
Model: gpt-5
---
.agents/docs/rpc-loro-streams-rpc.md | 9 +-
.../2026-09-13-queue-steer-controls.md | 49 +++--
.../2026-09-13-queue-steer-controls.zh.md | 35 ++--
apps/cli/src/lib/loro/doc-user-turn.test.ts | 37 ++++
apps/cli/src/lib/loro/doc.ts | 28 ++-
apps/cli/src/session/AGENTS.md | 3 +-
apps/cli/src/session/README.md | 4 +-
apps/cli/src/session/queued-message-turn.ts | 4 +-
.../src/session/session-execution-service.ts | 95 +++++++++-
...ssage-handler-machine-registration.test.ts | 1 +
.../tests/session-execution-service.test.ts | 175 ++++++++++++++++--
locales/en.json | 2 +
locales/zh_CN.json | 2 +
.../sessions/message-queue/AGENTS.md | 11 +-
.../sessions/message-queue/index.ts | 5 +
.../message-queue/message-queue-display.tsx | 6 +
.../message-queue/message-queue-row.tsx | 24 ++-
.../queued-message-steer-compat.ts | 26 +++
.../sessions/session-chat-interface.tsx | 156 +++++++++++++++-
.../providers/workspace-machine-rpc-facade.ts | 12 ++
.../tests/message-queue-row-editing.test.tsx | 37 ++++
.../tests/queued-message-steer.test.ts | 49 +++++
.../workspace-machine-rpc-facade.test.ts | 25 +++
.../src/machine-protocol-capabilities.ts | 14 ++
packages/shared/src/message-schemas.ts | 2 +
packages/shared/src/message.ts | 2 +
.../machine-protocol-capabilities.test.ts | 15 ++
specs/message-queue-interactions.md | 34 +++-
specs/message-queue-interactions.zh.md | 27 ++-
29 files changed, 795 insertions(+), 94 deletions(-)
create mode 100644 packages/components/src/components/sessions/message-queue/queued-message-steer-compat.ts
create mode 100644 packages/components/tests/queued-message-steer.test.ts
diff --git a/.agents/docs/rpc-loro-streams-rpc.md b/.agents/docs/rpc-loro-streams-rpc.md
index cda7c3eed..e4ee0e8ea 100644
--- a/.agents/docs/rpc-loro-streams-rpc.md
+++ b/.agents/docs/rpc-loro-streams-rpc.md
@@ -20,10 +20,11 @@ been removed.
handlers.
- `README.md` — package smoke-test notes.
-`session/queue-steer` is an identity-based control operation, not queue reordering.
-Its request names both the expected active turn and the exact queued item. The CLI
-consumes that item before cancelling the expected turn; a missing item or stale turn
-is rejected without stopping the current agent.
+`session/queue-steer` is an identity-based control operation, not queue reordering. Its
+request names both the expected active turn and exact queued item, and callers require the
+negotiated `queueItemSteer` protocol capability. The CLI consumes the item only when its
+editing lease is inactive, then preserves native ACP Steer when acknowledged or cancels the
+expected turn for ordinary follow-up dispatch. Missing, editing, and stale targets do neither.
## Remote lifecycle acknowledgements
diff --git a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
index 7da6fc93a..2853ef728 100644
--- a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
+++ b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
@@ -9,10 +9,11 @@ Translation: current
Queue and Steer previously required changing a persistent preference, later queued
items hid Steer, and reordering started only from the small leading handle. The adopted
-interaction adds a one-shot inverse submission command, exposes Steer on every row, and
-uses the row's message content as its drag target. Queue order and immediate Steer remain
-independent: the daemon consumes a selected queue identity directly, and a missing identity
-leaves the active turn untouched.
+interaction adds a one-shot inverse submission command, exposes Steer on every row when the
+daemon can identify that row safely, and uses the row's message content as its drag target.
+Queue order and immediate Steer remain independent. Exact-item steering is version-negotiated,
+preserves native ACP steering, respects editing leases, and never stops the active turn when
+the selected identity is missing.
## Decision
@@ -21,11 +22,21 @@ leaves the active turn untouched.
`sendMessage({ queueBehavior: "inverse" })`; ordinary submission passes no option. The
command-level predicate owns composer focus, content, and send readiness so user binding
overrides cannot remove those rules. The routing resolver reverses only this submission.
-- Show Steer for every row whenever the session-level action is available. The renderer sends
- the queue `$cid` and expected active turn through `session/queue-steer`, then waits for the
- daemon result without changing queue or history locally. Under its per-session mutation and
- history-rewrite leases, the daemon revalidates the turn and consumes that exact row into
- history in one Session Doc mutation before requesting exact-turn cancellation.
+- Advertise `queueItemSteer` in `MachineMeta.protocolCapabilities`. The renderer calls
+ `session/queue-steer` only when that version is present; missing means unsupported. The
+ request names the queue `$cid` and expected active turn, and the renderer waits for the
+ result without changing queue or history locally.
+- Let the daemon choose the execution mechanism after validating both identities and the
+ target's editing lease. With acknowledged native ACP Steer, it atomically consumes the row
+ as `pending_apply` and enters the existing `steerPrompt` handoff. Without native Steer, it
+ consumes the row as an ordinary pending turn and cancels only the expected active turn.
+- Retain mixed-version behavior without reintroducing reorder-then-cancel. An older daemon
+ with an authoritative acknowledged-Steer capability uses the legacy native path. Other
+ older daemons retain only the established queue-head interrupt; later-row Steer controls
+ are disabled with an upgrade explanation.
+- Keep a bounded daemon receipt for each completed exact operation key. A response-loss retry
+ returns the same result instead of consuming or cancelling twice. A cancellation failure
+ after consumption leaves one durable follow-up and is also returned idempotently.
- Make the leading number and message body a single pointer and keyboard drag activator.
Keep action buttons outside it, and disable it while the row editor owns interaction.
@@ -34,20 +45,24 @@ leaves the active turn untouched.
Keeping Steer on the first row would require users to perform an unrelated reorder first.
Reorder-then-cancel was rejected because reorder can resolve after a concurrent peer deleted
the selected row, causing Stop to target the current turn without any message to promote.
-Renderer-side history materialization was rejected because the renderer cannot atomically
-validate daemon turn ownership and queue identity. Making the complete row draggable was also
-rejected because Steer, edit, and remove would become accidental drag starters.
+Renderer-side history materialization remains only for old-daemon native compatibility; it
+cannot provide exact-item atomicity. Removing native steering was rejected because
+`steerPrompt` injects into the current prompt, while cancel-and-dispatch starts a new turn.
+Making the complete row draggable was also rejected because Steer, edit, and remove would
+become accidental drag starters.
## Verification and limits
- Routing tests cover Queue → Steer and Steer → Queue inversion while a prompt is live.
- Command tests cover the default binding, explicit submission option, and command-level
composer-focus rule.
-- Queue component tests cover Steer on a later row and verify that message content, but
- not action buttons, belongs to the drag activator.
-- CLI service and Session Doc tests cover consuming C from `[A, B, C]` as `[A, B]`, exact-turn
- cancellation after consumption, and the missing-C failure path that never calls Stop.
-- Machine RPC schema tests cover both required identities.
+- Queue component tests cover later-row Steer, old-daemon head-only disabling, authoritative
+ legacy native selection, and the drag activator boundary.
+- CLI service and Session Doc tests cover exact C consumption, native `steerPrompt`, exact
+ cancellation, missing and active-edit rejection, cancellation failure, and response-loss
+ retries.
+- Machine RPC and protocol-capability tests cover both required identities and mixed-version
+ negotiation.
- Component tests use synthetic pointer state. Physical touch dragging and a full
provider-backed steer run were not exercised.
diff --git a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
index 554636235..a86aff399 100644
--- a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
@@ -8,9 +8,9 @@ Translation: current
## 摘要
此前若要在“排队”和“引导”间切换，必须修改持久设置；后续队列项不显示“引导”，重排也只能
-从狭小的左侧把手开始。本次采用一次性反转提交命令、让每行都显示“引导”，并把消息内容区
-作为拖动区域。队列顺序与立即“引导”保持独立：daemon 直接消费所选队列 ID；如果该 ID 已
-不存在，则当前 turn 不受影响。
+从狭小的左侧把手开始。本次采用一次性反转提交命令、在 daemon 能安全识别目标行时让每行
+显示“引导”，并把消息内容区作为拖动区域。队列顺序与立即“引导”保持独立。精确队列项引导
+必须版本协商、保留 native ACP Steer、遵守 editing lease，并在目标 ID 缺失时保持当前 turn 不变。
## 决策
@@ -18,10 +18,17 @@ Translation: current
`Mod+Shift+Enter` 触发。输入框直接调用 `sendMessage({ queueBehavior: "inverse" })`，普通
提交不传选项。输入框聚焦、有内容且可以发送是命令级条件，因此用户覆盖 binding 后也不会
丢失；路由器只反转本次有效偏好。
-- 会话允许引导时，每一行都显示“引导”。Renderer 通过 `session/queue-steer` 发送队列 `$cid`
- 和预期活动 turn，等待 daemon 返回，且不在本地修改队列或历史。Daemon 在每会话 mutation
- 与历史 rewrite lease 下重新确认 turn，并在一次 Session Doc 更新中把该行消费进历史，再请求
- 精确取消该 turn。
+- 在 `MachineMeta.protocolCapabilities` 声明 `queueItemSteer`。只有该版本存在时，Renderer
+ 才调用 `session/queue-steer`；缺失即表示不支持。请求携带队列 `$cid` 与预期活动 turn，
+ Renderer 等待结果，不在本地修改队列或历史。
+- Daemon 确认两个 ID 及目标 editing lease 后决定执行机制。支持 acknowledged native ACP
+ Steer 时，原子消费目标行为 `pending_apply`，并进入既有 `steerPrompt` handoff；否则消费为
+ 普通 pending turn，再只取消预期活动 turn。
+- 混合版本兼容不得恢复“先重排后取消”。旧 daemon 若 authoritative capability 声明支持
+ acknowledged Steer，则使用旧 native 路径；其他旧 daemon 只保留既有队首 interrupt，后续行
+ “引导”禁用并提示升级。
+- Daemon 为已完成的精确操作 key 保留有界 receipt。响应丢失后的重试返回相同结果，不再次
+ 消费或取消。消费后取消失败也只留下一个持久 follow-up，并以幂等方式返回。
- 左侧序号和消息正文合并为一个支持鼠标及键盘的拖动区域。操作按钮保持在区域外；编辑器
接管交互时禁用该行拖动。
@@ -29,17 +36,19 @@ Translation: current
只允许队首“引导”会迫使用户先做一次无关重排。没有采用“重排后取消”：并发客户端删除所选
行时，重排仍可能 resolve，进而在没有可提升消息的情况下错误 Stop 当前 turn。也没有让
-Renderer 先写历史，因为它无法原子确认 daemon 的 turn 所有权和队列 ID。没有让整行都可拖动，
-因为那会使“引导”、“编辑”和“移除”成为意外的拖动起点。
+Renderer 写历史仅保留给旧 daemon 的 native 兼容路径；它无法提供精确队列项原子性。没有删除
+native steer，因为 `steerPrompt` 注入当前 prompt，而 cancel-and-dispatch 会开启新 turn，两者
+语义不同。没有让整行都可拖动，因为那会使“引导”、“编辑”和“移除”成为意外拖动起点。
## 验证与边界
- 路由测试覆盖 prompt 活动时“排队 → 引导”和“引导 → 排队”的反转。
- 命令测试覆盖默认 binding、显式提交选项和命令级输入框聚焦规则。
-- 队列组件测试覆盖对后续项执行“引导”，并验证消息内容属于拖动区域而操作按钮不属于。
-- CLI service 与 Session Doc 测试覆盖从 `[A, B, C]` 消费 C 后保留 `[A, B]`、消费后精确取消
- turn，以及 C 已缺失时绝不调用 Stop。
-- Machine RPC schema 测试覆盖两个必需 ID。
+- 队列组件测试覆盖后续行引导、旧 daemon 仅启用队首、authoritative legacy native 选择，以及
+ 拖动区域边界。
+- CLI service 与 Session Doc 测试覆盖精确消费 C、native `steerPrompt`、精确取消、目标缺失、
+ editing lease、取消失败及响应丢失重试。
+- Machine RPC 与 protocol capability 测试覆盖两个必需 ID 和混合版本协商。
- 组件测试使用合成指针状态；未验证物理触摸拖动和完整的 Provider-backed steer 流程。
## 参考
diff --git a/apps/cli/src/lib/loro/doc-user-turn.test.ts b/apps/cli/src/lib/loro/doc-user-turn.test.ts
index 805e3301e..5cd4bd288 100644
--- a/apps/cli/src/lib/loro/doc-user-turn.test.ts
+++ b/apps/cli/src/lib/loro/doc-user-turn.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it, vi } from 'vitest';
import {
createSessionMirror,
+ getServerNow,
type MessageQueueItem,
type SessionHistoryInput,
type SessionId,
@@ -86,6 +87,42 @@ describe('SessionDocument.consumeMessageQueueItemAsUserTurn', () => {
expect(state.mq.map((item) => item.$cid)).toEqual(['A']);
expect(upsertDocMeta).not.toHaveBeenCalled();
});
+
+ it('does not consume an item while another client holds its editing lease', async () => {
+ const upsertDocMeta = vi.fn(async () => {});
+ const { doc, state } = createSessionDocument({ upsertDocMeta });
+ state.mq = [
+ {
+ $cid: 'C',
+ task: 'task C',
+ timestamp: '2026-09-13T00:00:00.000Z',
+ isEditing: true,
+ editingStartedAt: getServerNow(),
+ },
+ ];
+
+ await expect(
+ doc.consumeMessageQueueItemAsUserTurn('C', () => createUserTurn('user:C'))
+ ).resolves.toEqual({ type: 'editing' });
+ expect(state.history).toEqual([]);
+ expect(state.mq.map((item) => item.$cid)).toEqual(['C']);
+ expect(upsertDocMeta).not.toHaveBeenCalled();
+ });
+
+ it('can reserve an exact item for native steer without publishing ordinary dispatch', async () => {
+ const upsertDocMeta = vi.fn(async () => {});
+ const { doc, state } = createSessionDocument({ upsertDocMeta });
+ state.mq = [{ $cid: 'C', task: 'task C', timestamp: '2026-09-13T00:00:00.000Z' }];
+
+ await expect(
+ doc.consumeMessageQueueItemAsUserTurn('C', () => createUserTurn('user:C'), {
+ publishDispatch: false,
+ })
+ ).resolves.toMatchObject({ type: 'consumed', entry: { id: 'user:C' } });
+ expect(state.history.map((entry) => entry.id)).toEqual(['user:C']);
+ expect(state.mq).toEqual([]);
+ expect(upsertDocMeta).not.toHaveBeenCalled();
+ });
});
describe('SessionDocument.appendUserTurn', () => {
diff --git a/apps/cli/src/lib/loro/doc.ts b/apps/cli/src/lib/loro/doc.ts
index e3aae3632..805183caa 100644
--- a/apps/cli/src/lib/loro/doc.ts
+++ b/apps/cli/src/lib/loro/doc.ts
@@ -1742,6 +1742,12 @@ const acpRuntimeConfigEqual = (
*/
const EDITING_LEASE_MS = 5 * 60 * 1000;
+const hasActiveMessageQueueEditingLease = (item: MessageQueueItem): boolean => {
+ if (!item.isEditing) return false;
+ const startedAt = item.editingStartedAt ?? 0;
+ return getServerNow() - startedAt < EDITING_LEASE_MS;
+};
+
export class SessionDocument implements LoroDocument {
mirror: import('@lody/shared').SessionMirror | null = null;
handle: RepoDocHandle | null = null;
@@ -2868,9 +2874,7 @@ export class SessionDocument implements LoroDocument SessionHistoryInput | null
+ buildEntry: (item: MessageQueueItem) => SessionHistoryInput | null,
+ options: { publishDispatch?: boolean } = {}
): Promise<
| { type: 'consumed'; entry: SessionHistoryInput }
| { type: 'missing' }
+ | { type: 'editing' }
| { type: 'invalid' }
> {
if (!this.mirror) {
@@ -2934,12 +2941,17 @@ export class SessionDocument implements LoroDocument {
const queue = (prev.mq ?? []) as MessageQueueItem[];
const item = queue.find((candidate) => candidate.$cid === cid);
if (!item) return prev;
+ if (hasActiveMessageQueueEditingLease(item)) {
+ outcome.value = { type: 'editing' };
+ return prev;
+ }
const entry = buildEntry(item);
if (!entry) {
@@ -2960,7 +2972,7 @@ export class SessionDocument implements LoroDocument);
diff --git a/apps/cli/src/session/AGENTS.md b/apps/cli/src/session/AGENTS.md
index 527054444..f5be54a59 100644
--- a/apps/cli/src/session/AGENTS.md
+++ b/apps/cli/src/session/AGENTS.md
@@ -25,7 +25,8 @@ Contract: specs/session-orchestration.md.
## Dispatch
-- Queue promotion preserves frozen fields; Queue Steer consumes exact `$cid`; missing never stops.
+- Queue promotion keeps frozen fields. Exact Steer respects edit leases/native support;
+ missing/stale targets never stop.
- Absent session meta is "unknown", not foreign: hold the TTL-bounded RPC stash until meta lands;
drop it only on a definitive verdict.
- Subscribe to RPC offers BEFORE awaiting Doc Room join/sync and never dispatch from the RPC
diff --git a/apps/cli/src/session/README.md b/apps/cli/src/session/README.md
index e7318f1d0..0a65a7bd8 100644
--- a/apps/cli/src/session/README.md
+++ b/apps/cli/src/session/README.md
@@ -25,8 +25,8 @@ CLI/MCP orchestration contract is specs/session-orchestration.md.
message-handler's `beginConversationTurn`, stored/disposed via `SessionTransientStore` turn
state; it creates the assistant entry when it opens.
- `session-execution-service.ts` — runs one turn end-to-end and owns exact-item queue
- Steer serialization: validate the active turn and queued item, consume that item,
- then cancel only the expected turn. It also owns ACP prompt, turn ids,
+ Steer serialization: validate the active turn, queued item, and editing lease, then
+ choose native `steerPrompt` or exact cancel-and-dispatch. It also owns ACP prompt, turn ids,
lifecycle/error handling, GitHub/local project setup, and post-turn diffStats.
- `acp-error-classification.ts` — JSON-RPC/transport error string matching for the above.
- `session-manager.ts` / `session.ts` / `session-sandbox.ts` / `terminal-manager.ts` —
diff --git a/apps/cli/src/session/queued-message-turn.ts b/apps/cli/src/session/queued-message-turn.ts
index 37472c0d6..9e68ae7cf 100644
--- a/apps/cli/src/session/queued-message-turn.ts
+++ b/apps/cli/src/session/queued-message-turn.ts
@@ -25,7 +25,8 @@ const isConfigOptionValueRecord = (
/** Materialize one durable queue item as the user turn that will execute it. */
export function buildQueuedMessageUserTurn(
queuedItem: MessageQueueItem,
- meta: SessionMeta
+ meta: SessionMeta,
+ options: { status?: 'pending' | 'pending_apply' } = {}
): SessionHistoryInput | null {
const inputBlocks = normalizeSessionInputBlocks(
queuedItem.acpSessionConfig?.inputBlocks,
@@ -53,6 +54,7 @@ export function buildQueuedMessageUserTurn(
inputBlocks,
timestamp: queuedItem.timestamp,
inputConfig,
+ ...(options.status ? { status: options.status } : {}),
});
if (!pendingEntry) return null;
diff --git a/apps/cli/src/session/session-execution-service.ts b/apps/cli/src/session/session-execution-service.ts
index 7316d7659..a0e57a7e7 100644
--- a/apps/cli/src/session/session-execution-service.ts
+++ b/apps/cli/src/session/session-execution-service.ts
@@ -58,6 +58,7 @@ import {
hasBuiltinRuntimeOverrideValues,
getManagedBuiltinRuntimeByAgentType,
getManagedBuiltinRuntimeByRuntimeName,
+ normalizeSessionTurnInputConfig,
serializeCustomAcpLaunchSpec,
} from '@lody/shared';
import type { ContentBlock } from '@agentclientprotocol/sdk';
@@ -724,6 +725,8 @@ type TurnAnalyticsState = {
hasReplayPrompt: boolean;
};
+const QUEUE_STEER_RECEIPT_LIMIT = 512;
+
export class SessionExecutionService {
private readonly canceledTurnBySession = new Map();
private readonly currentTurnBySession = new Map();
@@ -738,6 +741,8 @@ export class SessionExecutionService {
// application never race the boundary. No global concurrency cap (Infinity):
// this is pure per-session serialization, matching the old hand-rolled lock.
private readonly steerMutationQueue = new ConcurrentQueue(Number.POSITIVE_INFINITY);
+ /** Bounded receipts make a response-loss retry observationally idempotent. */
+ private readonly queueSteerReceipts = new Map();
// Analytics-only state (spec §5b). Tracks per-turn timing + the last status
// we reported so status_changed can carry from→to + dwell time. Never read by
// product logic; kept here so capture stays side-effect-only.
@@ -761,6 +766,20 @@ export class SessionExecutionService {
this.acpAuthenticationManager = new AcpAuthenticationManager(deps.logger);
}
+ private rememberQueueSteerReceipt(
+ operationKey: string,
+ response: SessionQueueSteerResponse
+ ): SessionQueueSteerResponse {
+ this.queueSteerReceipts.delete(operationKey);
+ this.queueSteerReceipts.set(operationKey, response);
+ while (this.queueSteerReceipts.size > QUEUE_STEER_RECEIPT_LIMIT) {
+ const oldest = this.queueSteerReceipts.keys().next().value;
+ if (oldest === undefined) break;
+ this.queueSteerReceipts.delete(oldest);
+ }
+ return response;
+ }
+
private createPromptHandoffRun(options: {
turnId: string;
promptPromise: Promise;
@@ -1395,6 +1414,11 @@ export class SessionExecutionService {
queueItemId: string;
requestedByUserId: string;
}): Promise {
+ const operationKey = JSON.stringify([
+ options.sessionId,
+ options.expectedTurnId,
+ options.queueItemId,
+ ]);
const respond = (
disposition: SessionQueueSteerResponse['disposition'],
details?: { userTurnId?: string; error?: string }
@@ -1409,10 +1433,16 @@ export class SessionExecutionService {
});
return await this.steerMutationQueue.enqueue(options.sessionId, async () => {
+ const previousReceipt = this.queueSteerReceipts.get(operationKey);
+ if (previousReceipt) return previousReceipt;
+
const releaseConflict = this.tryAcquireSessionRewriteConflictLease(options.sessionId);
if (!releaseConflict) {
return respond('busy', { error: 'The session history is being replaced.' });
}
+ let queueItemConsumed = false;
+ const finishConsumed = (response: SessionQueueSteerResponse): SessionQueueSteerResponse =>
+ queueItemConsumed ? this.rememberQueueSteerReceipt(operationKey, response) : response;
try {
const runtime = this.turnRuntimeBySession.get(options.sessionId);
if (!runtime || !runtime.session || !runtime.promptInFlight || runtime.cancelRequested) {
@@ -1440,19 +1470,68 @@ export class SessionExecutionService {
return respond('stale-turn');
}
+ const agentClient = runtime.session.agentClient;
+ const useNativeSteer = Boolean(
+ agentClient &&
+ runtime.session.acpSessionId &&
+ agentClient.getAcknowledgedSteerCapability()
+ );
+
// Queue order and immediate steering are separate mutations. Consume the
// selected identity directly; A/B keep their relative order when C wins.
+ // Native steer owns dispatch publication through its handoff path.
const consumed = await sessionDoc.consumeMessageQueueItemAsUserTurn(
options.queueItemId,
- (item) => buildQueuedMessageUserTurn(item, meta)
+ (item) =>
+ buildQueuedMessageUserTurn(item, meta, {
+ status: useNativeSteer ? 'pending_apply' : 'pending',
+ }),
+ { publishDispatch: !useNativeSteer }
);
if (consumed.type === 'missing') {
return respond('queue-item-missing');
}
+ if (consumed.type === 'editing') {
+ return respond('queue-item-editing');
+ }
if (consumed.type === 'invalid') {
return respond('invalid-queue-item');
}
+ queueItemConsumed = true;
const entry = consumed.entry;
+
+ if (useNativeSteer) {
+ const inputConfig = normalizeSessionTurnInputConfig(entry.inputConfig);
+ const userId = entry.userId?.trim();
+ const timestamp = entry.timestamp?.trim();
+ if (!inputConfig || !userId || !timestamp) {
+ return finishConsumed(
+ respond('invalid-queue-item', {
+ userTurnId: entry.id,
+ error: 'The queued message cannot be converted to a steer turn.',
+ })
+ );
+ }
+ const nativeResult = await this.steerSessionLocked({
+ sessionId: options.sessionId,
+ expectedTurnId: options.expectedTurnId,
+ userTurnId: entry.id,
+ userId,
+ timestamp,
+ inputConfig,
+ });
+ const rejectedDisposition =
+ nativeResult.disposition === 'applied' ? 'error' : nativeResult.disposition;
+ return finishConsumed(
+ nativeResult.applied
+ ? respond('accepted', { userTurnId: entry.id })
+ : respond(rejectedDisposition, {
+ userTurnId: entry.id,
+ error: nativeResult.error,
+ })
+ );
+ }
+
const cancellation = await this.cancelSession({
type: 'session/cancel',
sessionId: options.sessionId,
@@ -1461,14 +1540,16 @@ export class SessionExecutionService {
turnId: options.expectedTurnId,
});
if (!cancellation.success) {
- return respond('error', {
- userTurnId: entry.id,
- error: cancellation.error ?? 'The active turn could not be stopped.',
- });
+ return finishConsumed(
+ respond('error', {
+ userTurnId: entry.id,
+ error: cancellation.error ?? 'The active turn could not be stopped.',
+ })
+ );
}
- return respond('accepted', { userTurnId: entry.id });
+ return finishConsumed(respond('accepted', { userTurnId: entry.id }));
} catch (error) {
- return respond('error', { error: formatErrorMessage(error) });
+ return finishConsumed(respond('error', { error: formatErrorMessage(error) }));
} finally {
releaseConflict();
}
diff --git a/apps/cli/tests/message-handler-machine-registration.test.ts b/apps/cli/tests/message-handler-machine-registration.test.ts
index 2933d59e6..90c428cfe 100644
--- a/apps/cli/tests/message-handler-machine-registration.test.ts
+++ b/apps/cli/tests/message-handler-machine-registration.test.ts
@@ -187,6 +187,7 @@ describe('MessageHandler machine registration', () => {
localFileResources: 1,
providerSetup: 1,
acpProtocolAuthentication: 2,
+ queueItemSteer: 1,
subagentCancellation: 1,
});
diff --git a/apps/cli/tests/session-execution-service.test.ts b/apps/cli/tests/session-execution-service.test.ts
index ffde55895..a0696d035 100644
--- a/apps/cli/tests/session-execution-service.test.ts
+++ b/apps/cli/tests/session-execution-service.test.ts
@@ -338,20 +338,27 @@ describe('SessionExecutionService', () => {
).turnRuntimeBySession.set(sessionId, runtime);
const cancel = vi.spyOn(service, 'cancelSession').mockResolvedValue({ success: true });
- await expect(
- service.steerQueuedMessage({
- sessionId,
- expectedTurnId: activeTurnId,
- queueItemId: 'C',
- requestedByUserId: 'owner-user',
- })
- ).resolves.toMatchObject({
+ const request = {
+ sessionId,
+ expectedTurnId: activeTurnId,
+ queueItemId: 'C',
+ requestedByUserId: 'owner-user',
+ };
+ await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
accepted: true,
disposition: 'accepted',
queueItemId: 'C',
userTurnId: 'user:C',
});
+ // A response-loss retry returns the receipt instead of consuming or
+ // cancelling a second time after the active turn has moved on.
+ await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
+ accepted: true,
+ disposition: 'accepted',
+ userTurnId: 'user:C',
+ });
+
expect(queue.map((item) => item.$cid)).toEqual(['A', 'B']);
expect(history).toHaveLength(1);
expect(history[0]).toMatchObject({ id: 'user:C', role: 'user' });
@@ -359,6 +366,8 @@ describe('SessionExecutionService', () => {
expect(sessionDoc.consumeMessageQueueItemAsUserTurn.mock.invocationCallOrder[0]).toBeLessThan(
cancel.mock.invocationCallOrder[0]!
);
+ expect(sessionDoc.consumeMessageQueueItemAsUserTurn).toHaveBeenCalledOnce();
+ expect(cancel).toHaveBeenCalledOnce();
});
it('keeps the active turn running when the selected queue identity is gone', async () => {
@@ -414,6 +423,114 @@ describe('SessionExecutionService', () => {
)
).toBe(runtime);
});
+
+ it('keeps the active turn and queue row while the target editing lease is active', async () => {
+ const sessionId = 'session-queue-steer-editing' as SessionId;
+ const activeTurnId = 'assistant:active';
+ const sessionDoc = {
+ getMetaState: vi.fn(async () => ({
+ id: sessionId,
+ userId: 'owner-user',
+ machineId: 'machine-1',
+ cliType: 'builtin',
+ agentType: 'codex',
+ })),
+ consumeMessageQueueItemAsUserTurn: vi.fn(async () => ({ type: 'editing' as const })),
+ };
+ const service = new SessionExecutionService(
+ createBaseDeps({
+ workspaceDocument: {
+ getOrCreateSessionDoc: vi.fn(async () => sessionDoc),
+ } as unknown as LoroDocumentManager,
+ })
+ );
+ const runtime = {
+ sessionId,
+ turnId: activeTurnId,
+ userTurnId: 'active',
+ session: {},
+ promptInFlight: true,
+ cancelRequested: false,
+ };
+ (
+ service as unknown as { turnRuntimeBySession: Map }
+ ).turnRuntimeBySession.set(sessionId, runtime);
+ const cancel = vi.spyOn(service, 'cancelSession');
+
+ await expect(
+ service.steerQueuedMessage({
+ sessionId,
+ expectedTurnId: activeTurnId,
+ queueItemId: 'C',
+ requestedByUserId: 'owner-user',
+ })
+ ).resolves.toMatchObject({ accepted: false, disposition: 'queue-item-editing' });
+ expect(cancel).not.toHaveBeenCalled();
+ });
+
+ it('does not consume or cancel again after consumption succeeded but cancellation failed', async () => {
+ const sessionId = 'session-queue-steer-cancel-failed' as SessionId;
+ const activeTurnId = 'assistant:active';
+ const entry = {
+ id: 'user:C',
+ role: 'user' as const,
+ userId: 'owner-user',
+ timestamp: '2026-09-13T00:00:00.000Z',
+ items: [{ type: 'text' as const, text: 'task C' }],
+ status: 'pending' as const,
+ read: false,
+ inputConfig: { prompt: 'task C' },
+ };
+ const sessionDoc = {
+ getMetaState: vi.fn(async () => ({ id: sessionId })),
+ consumeMessageQueueItemAsUserTurn: vi.fn(async () => ({
+ type: 'consumed' as const,
+ entry,
+ })),
+ };
+ const service = new SessionExecutionService(
+ createBaseDeps({
+ workspaceDocument: {
+ getOrCreateSessionDoc: vi.fn(async () => sessionDoc),
+ } as unknown as LoroDocumentManager,
+ })
+ );
+ const runtime = {
+ sessionId,
+ turnId: activeTurnId,
+ userTurnId: 'active',
+ session: {},
+ promptInFlight: true,
+ cancelRequested: false,
+ };
+ (
+ service as unknown as { turnRuntimeBySession: Map }
+ ).turnRuntimeBySession.set(sessionId, runtime);
+ const cancel = vi
+ .spyOn(service, 'cancelSession')
+ .mockResolvedValue({ success: false, error: 'cancel failed' });
+ const request = {
+ sessionId,
+ expectedTurnId: activeTurnId,
+ queueItemId: 'C',
+ requestedByUserId: 'owner-user',
+ };
+
+ await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
+ accepted: false,
+ disposition: 'error',
+ userTurnId: 'user:C',
+ error: 'cancel failed',
+ });
+ await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
+ accepted: false,
+ disposition: 'error',
+ userTurnId: 'user:C',
+ });
+ expect(sessionDoc.consumeMessageQueueItemAsUserTurn).toHaveBeenCalledOnce();
+ expect(cancel).toHaveBeenCalledOnce();
+ });
+
it('advances one session owner through consecutive prompt handoffs', async () => {
const steerPrompt = vi.fn(() => ({
completion: new Promise(() => {}),
@@ -432,7 +549,30 @@ describe('SessionExecutionService', () => {
steerPrompt,
currentModel: undefined,
};
+ const queuedItem: MessageQueueItem = {
+ $cid: 'queue-user-2',
+ task: 'change direction',
+ userId: 'user-1',
+ userTurnId: 'user-2',
+ timestamp: '2026-07-11T00:00:00.000Z',
+ acpSessionConfig: { prompt: 'change direction' },
+ };
const sessionDoc = {
+ getMetaState: vi.fn(async () => ({
+ id: 'session-steer',
+ userId: 'user-1',
+ machineId: 'machine-1',
+ cliType: 'builtin',
+ agentType: 'codex',
+ })),
+ consumeMessageQueueItemAsUserTurn: vi.fn(
+ async (cid: string, buildEntry: (item: MessageQueueItem) => SessionHistoryInput | null) => {
+ expect(cid).toBe(queuedItem.$cid);
+ const entry = buildEntry(queuedItem);
+ if (!entry) return { type: 'invalid' as const };
+ return { type: 'consumed' as const, entry };
+ }
+ ),
updateHistory: vi.fn(async () => {}),
};
const upsertDocMeta = vi.fn(async () => {});
@@ -491,15 +631,13 @@ describe('SessionExecutionService', () => {
).turnRuntimeBySession.set(sessionId, runtime);
await expect(
- service.steerSession({
+ service.steerQueuedMessage({
sessionId,
expectedTurnId: 'assistant:user-1',
- userTurnId: 'user-2',
- userId: 'user-1',
- timestamp: '2026-07-11T00:00:00.000Z',
- inputConfig: { prompt: 'change direction' },
+ queueItemId: queuedItem.$cid,
+ requestedByUserId: 'user-1',
})
- ).resolves.toMatchObject({ applied: true, disposition: 'applied' });
+ ).resolves.toMatchObject({ accepted: true, disposition: 'accepted', userTurnId: 'user-2' });
expect(onTurnSettled).toHaveBeenCalledOnce();
expect(onTurnSettled).toHaveBeenCalledWith('handled');
@@ -518,16 +656,21 @@ describe('SessionExecutionService', () => {
);
expect(runtime.turnId).toBe('assistant:user-2');
expect(runtime.userTurnId).toBe('user-2');
- expect(runtime.invocation).toEqual({
+ expect(runtime.invocation).toMatchObject({
requesterUserId: 'user-1',
sourceTurnId: 'user-2',
inputConfig: { prompt: 'change direction' },
});
- expect(service.getActiveInvocationContext(sessionId)).toEqual({
+ expect(service.getActiveInvocationContext(sessionId)).toMatchObject({
requesterUserId: 'user-1',
sourceTurnId: 'user-2',
inputConfig: { prompt: 'change direction' },
});
+ expect(sessionDoc.consumeMessageQueueItemAsUserTurn).toHaveBeenCalledWith(
+ queuedItem.$cid,
+ expect.any(Function),
+ { publishDispatch: false }
+ );
expect(initialPromptRun.successor?.turnId).toBe('assistant:user-2');
expect(runtime.activePromptRun.turnId).toBe('assistant:user-2');
diff --git a/locales/en.json b/locales/en.json
index 3e45dd222..9e598c74b 100644
--- a/locales/en.json
+++ b/locales/en.json
@@ -1750,6 +1750,7 @@
"sessions.messageQueue.saveEdit": "Save changes (Enter)",
"sessions.messageQueue.title": "Queued messages",
"sessions.messageQueue.upNext": "Up next",
+ "sessions.messageQueue.updateAgentForLaterSteer": "Update the local agent to steer a later queued message",
"sessions.messageStatus.deliverNow": "Deliver now",
"sessions.messageStatus.deliverNowFailed": "Failed to deliver the message - please try again",
"sessions.messageStatus.notDelivered": "Not delivered",
@@ -1981,6 +1982,7 @@
"sessions.proposedPlanDecision.executing": "Implementing plan...",
"sessions.queueEditError": "Failed to edit message",
"sessions.queueError": "Failed to queue message",
+ "sessions.queueItemEditing": "Finish editing this queued message before steering it",
"sessions.queueItemMissing": "This queued message is no longer available",
"sessions.queueRemoveError": "Failed to remove message from queue",
"sessions.queueReorderError": "Failed to reorder messages",
diff --git a/locales/zh_CN.json b/locales/zh_CN.json
index ec4dbc36d..d2d3906bf 100644
--- a/locales/zh_CN.json
+++ b/locales/zh_CN.json
@@ -1750,6 +1750,7 @@
"sessions.messageQueue.saveEdit": "保存修改（回车）",
"sessions.messageQueue.title": "排队中的消息",
"sessions.messageQueue.upNext": "接下来",
+ "sessions.messageQueue.updateAgentForLaterSteer": "更新本地 Agent 后才能引导后续排队消息",
"sessions.messageStatus.deliverNow": "重新发送",
"sessions.messageStatus.deliverNowFailed": "送达失败，请重试",
"sessions.messageStatus.notDelivered": "未送达",
@@ -1981,6 +1982,7 @@
"sessions.proposedPlanDecision.executing": "正在实施计划...",
"sessions.queueEditError": "编辑消息失败",
"sessions.queueError": "消息入队失败",
+ "sessions.queueItemEditing": "请先完成这条排队消息的编辑，再进行引导",
"sessions.queueItemMissing": "这条排队消息已不存在",
"sessions.queueRemoveError": "移除消息失败",
"sessions.queueReorderError": "调整消息顺序失败",
diff --git a/packages/components/src/components/sessions/message-queue/AGENTS.md b/packages/components/src/components/sessions/message-queue/AGENTS.md
index d70efcb8f..2428e91f1 100644
--- a/packages/components/src/components/sessions/message-queue/AGENTS.md
+++ b/packages/components/src/components/sessions/message-queue/AGENTS.md
@@ -9,11 +9,12 @@ queued-turn list (`message-queue-display.tsx`, `message-queue-row.tsx`,
`../session-message-submit-route.ts` and is described in
[.agents/docs/sessions-live-status.md](../../../../../../.agents/docs/sessions-live-status.md).
-Every queued row offers Steer while an active turn can accept it. Steer sends the
-selected `$cid` and expected active turn to the owning daemon; it never reorders,
-removes, or materializes a queue row in the renderer. A rejected or missing identity
-must leave the active turn running. A row's number and message body are one drag
-activator; its Steer, edit, and remove controls stay outside that activator.
+Exact-item Steer requires the negotiated `queueItemSteer` daemon protocol; missing means
+unsupported. The daemon chooses acknowledged native Steer or exact cancel-and-dispatch.
+For older daemons, an authoritative `acknowledgedSteer` capability must retain the legacy
+native path; otherwise only queue-head interrupt stays enabled. Never reorder a later row
+to emulate Steer. A missing, stale, or actively edited exact target must leave the current
+turn running. A row's number and message body are one drag activator; its actions stay out.
The queue intentionally stays OUT of the composer info bar
([.agents/docs/sessions-info-bar.md](../../../../../../.agents/docs/sessions-info-bar.md)).
diff --git a/packages/components/src/components/sessions/message-queue/index.ts b/packages/components/src/components/sessions/message-queue/index.ts
index 078978312..bc994ea31 100644
--- a/packages/components/src/components/sessions/message-queue/index.ts
+++ b/packages/components/src/components/sessions/message-queue/index.ts
@@ -4,6 +4,11 @@ export { MessageQueueRow } from './message-queue-row';
export type { MessageQueueRowProps } from './message-queue-row';
export { QueuedImagePreview } from './queued-image-preview';
export type { QueuedImageBlock } from './queued-image-preview';
+export {
+ resolveQueuedMessageSteerRoute,
+ shouldUseLegacyNativeQueueSteer,
+ type QueuedMessageSteerRoute,
+} from './queued-message-steer-compat';
export {
useMessageQueueEditing,
getEditableTaskText,
diff --git a/packages/components/src/components/sessions/message-queue/message-queue-display.tsx b/packages/components/src/components/sessions/message-queue/message-queue-display.tsx
index 00bffbe28..2e1255060 100644
--- a/packages/components/src/components/sessions/message-queue/message-queue-display.tsx
+++ b/packages/components/src/components/sessions/message-queue/message-queue-display.tsx
@@ -37,6 +37,8 @@ export type MessageQueueDisplayProps = {
onEditSave: (item: MessageQueueItem, task: string) => void | Promise;
onSteer: (item: MessageQueueItem) => void | Promise;
showSteerAction?: boolean;
+ steerActionScope?: 'all' | 'head';
+ steerDisabledReason?: string;
className?: string;
};
@@ -52,6 +54,8 @@ export function MessageQueueDisplay({
onEditSave,
onSteer,
showSteerAction = false,
+ steerActionScope = 'all',
+ steerDisabledReason,
className,
}: MessageQueueDisplayProps) {
const { t } = useTranslation();
@@ -157,6 +161,8 @@ export function MessageQueueDisplay({
item={item}
index={index}
showSteerAction={showSteerAction}
+ steerDisabled={steerActionScope === 'head' && index > 0}
+ steerDisabledReason={steerDisabledReason}
canReorder={canReorder}
isEditing={isEditing}
editValue={isEditing ? editing.editValue : ''}
diff --git a/packages/components/src/components/sessions/message-queue/message-queue-row.tsx b/packages/components/src/components/sessions/message-queue/message-queue-row.tsx
index 5bee9d6d8..7dc1b5fcf 100644
--- a/packages/components/src/components/sessions/message-queue/message-queue-row.tsx
+++ b/packages/components/src/components/sessions/message-queue/message-queue-row.tsx
@@ -18,6 +18,8 @@ export type MessageQueueRowProps = {
item: MessageQueueItem;
index: number;
showSteerAction: boolean;
+ steerDisabled?: boolean;
+ steerDisabledReason?: string;
canReorder: boolean;
isEditing: boolean;
editValue: string;
@@ -284,7 +286,16 @@ function RowBody(props: MessageQueueRowProps & EditCommitProps) {
function RowActions(props: MessageQueueRowProps) {
const { t } = useTranslation();
- const { item, showSteerAction, isEditing, onStartEdit, onRemove, onSteer } = props;
+ const {
+ item,
+ showSteerAction,
+ steerDisabled,
+ steerDisabledReason,
+ isEditing,
+ onStartEdit,
+ onRemove,
+ onSteer,
+ } = props;
// In edit mode the textarea owns the row: it carries its own confirm button, so we
// render no row-level actions that would compete for the click mid-edit.
@@ -301,6 +312,8 @@ function RowActions(props: MessageQueueRowProps) {
'sessions.messageQueue.guide',
'Steer the active response with this message'
)}
+ disabled={steerDisabled}
+ disabledReason={steerDisabledReason}
onClick={() => {
void onSteer(item);
}}
@@ -326,21 +339,28 @@ function RowActions(props: MessageQueueRowProps) {
function TextAction({
text,
ariaLabel,
+ disabled,
+ disabledReason,
onClick,
}: {
text: string;
ariaLabel: string;
+ disabled?: boolean;
+ disabledReason?: string;
onClick: () => void;
}) {
return (
diff --git a/packages/components/src/components/sessions/message-queue/queued-message-steer-compat.ts b/packages/components/src/components/sessions/message-queue/queued-message-steer-compat.ts
new file mode 100644
index 000000000..a926a0136
--- /dev/null
+++ b/packages/components/src/components/sessions/message-queue/queued-message-steer-compat.ts
@@ -0,0 +1,26 @@
+import type { AcpCapabilityAuthority, AcpCapabilityCacheEntry } from '@lody/shared';
+
+/**
+ * Older daemons have no exact-item queue RPC. Only their acknowledged ACP
+ * capability can preserve true in-prompt steering; an absent or provisional
+ * cache entry must not be guessed into support.
+ */
+export function shouldUseLegacyNativeQueueSteer(
+ authority: AcpCapabilityAuthority,
+ capability: Pick | undefined
+): boolean {
+ return authority === 'authoritative' && capability?.acknowledgedSteer === true;
+}
+
+export type QueuedMessageSteerRoute = 'exact-daemon' | 'legacy-native' | 'legacy-head';
+
+export function resolveQueuedMessageSteerRoute(options: {
+ supportsExactDaemonProtocol: boolean;
+ authority: AcpCapabilityAuthority;
+ capability: Pick | undefined;
+}): QueuedMessageSteerRoute {
+ if (options.supportsExactDaemonProtocol) return 'exact-daemon';
+ return shouldUseLegacyNativeQueueSteer(options.authority, options.capability)
+ ? 'legacy-native'
+ : 'legacy-head';
+}
diff --git a/packages/components/src/components/sessions/session-chat-interface.tsx b/packages/components/src/components/sessions/session-chat-interface.tsx
index 21aa67e52..9324e34b5 100644
--- a/packages/components/src/components/sessions/session-chat-interface.tsx
+++ b/packages/components/src/components/sessions/session-chat-interface.tsx
@@ -66,7 +66,7 @@ import {
type SessionTurnAgentRoleSelection,
} from './session-chat-input-area';
import { useSessionMcpSelection } from '@/hooks/use-session-mcp-selection';
-import { MessageQueueDisplay } from './message-queue';
+import { MessageQueueDisplay, resolveQueuedMessageSteerRoute } from './message-queue';
import { useTranslation } from 'react-i18next';
import { useRouter } from '@tanstack/react-router';
import { toast } from 'sonner';
@@ -114,6 +114,7 @@ import {
hasReportedPreviewTarget,
isSessionGoalCleared,
isSessionGoalActive,
+ machineSupportsQueueItemSteerProtocol,
normalizeSessionInputBlocks,
normalizeSessionTurnInputConfig,
resolveSessionAcpRuntimeConfig,
@@ -5182,7 +5183,17 @@ export const SessionChatInterface = memo(
[captureSessionEvent, reorderMessageQueueItem, t]
);
- const handleSteerQueuedMessage = useCallback(
+ const queueSteerCapability = session.agentConfigId
+ ? sessionMachine?.acpCapabilities?.[getAcpCapabilityCacheKey(session.agentConfigId)]
+ : undefined;
+ const queuedMessageSteerRoute = resolveQueuedMessageSteerRoute({
+ supportsExactDaemonProtocol: machineSupportsQueueItemSteerProtocol(sessionMachine),
+ authority: capabilityAuthority,
+ capability: queueSteerCapability,
+ });
+ const legacyQueueSteerRequiresHead = queuedMessageSteerRoute === 'legacy-head';
+
+ const handleExactQueueItemSteer = useCallback(
async (item: MessageQueueItem) => {
if (isExternalHistoryRefreshing || !activeAssistantTurnId || !currentUser?.id) {
return;
@@ -5207,7 +5218,12 @@ export const SessionChatInterface = memo(
description:
response?.disposition === 'queue-item-missing'
? t('sessions.queueItemMissing', 'That queued message is no longer available')
- : response?.error,
+ : response?.disposition === 'queue-item-editing'
+ ? t(
+ 'sessions.queueItemEditing',
+ 'Finish editing this queued message before steering it'
+ )
+ : response?.error,
});
}
} catch (error) {
@@ -5237,6 +5253,135 @@ export const SessionChatInterface = memo(
]
);
+ const handleLegacyNativeQueueSteer = useCallback(
+ async (item: MessageQueueItem) => {
+ if (isExternalHistoryRefreshing || !activeAssistantTurnId) return;
+ if (steeringQueueItemIdsRef.current.has(item.$cid)) return;
+ steeringQueueItemIdsRef.current.add(item.$cid);
+ try {
+ const inputConfig = normalizeSessionTurnInputConfig(item.acpSessionConfig);
+ const userId = item.userId?.trim() || currentUser?.id;
+ if (!inputConfig || !userId) {
+ throw new Error('Queued message input is invalid');
+ }
+ const inputBlocks = normalizeSessionInputBlocks(
+ inputConfig.inputBlocks,
+ inputConfig.prompt ?? item.task
+ );
+ const pendingHistoryEntry = buildPendingUserHistoryEntry({
+ userId,
+ inputBlocks,
+ timestamp: item.timestamp,
+ inputConfig,
+ status: 'pending_apply',
+ });
+ if (!pendingHistoryEntry) throw new Error('Queued message is empty');
+
+ const queuedUserTurnId = item.userTurnId?.trim() || `queued-${item.$cid}`;
+ const { entry } = await addSessionHistory({
+ ...pendingHistoryEntry,
+ id: queuedUserTurnId,
+ });
+ await removeMessageQueueItem(item.$cid);
+ trackMessageSend(entry.id);
+ void touchSessionActivity(session.id).catch((error: unknown) => {
+ console.warn('Failed to update session activity for steer', error);
+ });
+ const applied = await guideHistoryEntry(entry.id, activeAssistantTurnId);
+ captureSessionEvent('session/queue_legacy_native_steer_result', {
+ queue_item_id: item.$cid,
+ active_assistant_turn_id: activeAssistantTurnId,
+ applied,
+ });
+ } catch (error) {
+ console.error('Failed to steer queued message through legacy native path', error);
+ captureSessionEvent('session/queue_legacy_native_steer_failed', {
+ queue_item_id: item.$cid,
+ active_assistant_turn_id: activeAssistantTurnId,
+ error_name: error instanceof Error ? error.name : typeof error,
+ error_message: getErrorMessage(error),
+ });
+ toast.error(t('sessions.sendError'), { description: getErrorMessage(error) });
+ } finally {
+ steeringQueueItemIdsRef.current.delete(item.$cid);
+ }
+ },
+ [
+ activeAssistantTurnId,
+ addSessionHistory,
+ captureSessionEvent,
+ currentUser?.id,
+ guideHistoryEntry,
+ isExternalHistoryRefreshing,
+ removeMessageQueueItem,
+ session.id,
+ t,
+ touchSessionActivity,
+ trackMessageSend,
+ ]
+ );
+
+ const handleLegacyHeadQueueSteer = useCallback(
+ async (item: MessageQueueItem) => {
+ if (
+ isExternalHistoryRefreshing ||
+ !activeAssistantTurnId ||
+ messageQueue[0]?.$cid !== item.$cid
+ ) {
+ return;
+ }
+ setInputActionState('ready');
+ pendingUserInterruptRef.current = true;
+ try {
+ await requestSessionCancel(session.id, activeAssistantTurnId);
+ captureSessionEvent('session/queue_legacy_head_steer_succeeded', {
+ queue_item_id: item.$cid,
+ active_assistant_turn_id: activeAssistantTurnId,
+ });
+ } catch (error) {
+ pendingUserInterruptRef.current = false;
+ captureSessionEvent('session/queue_legacy_head_steer_failed', {
+ queue_item_id: item.$cid,
+ active_assistant_turn_id: activeAssistantTurnId,
+ error_name: error instanceof Error ? error.name : typeof error,
+ error_message: getErrorMessage(error),
+ });
+ toast.error(t('sessions.interruptFailed', 'Failed to interrupt current task'), {
+ description: getErrorMessage(error),
+ });
+ }
+ },
+ [
+ activeAssistantTurnId,
+ captureSessionEvent,
+ isExternalHistoryRefreshing,
+ messageQueue,
+ requestSessionCancel,
+ session.id,
+ t,
+ ]
+ );
+
+ const handleSteerQueuedMessage = useCallback(
+ async (item: MessageQueueItem) => {
+ if (queuedMessageSteerRoute === 'exact-daemon') {
+ await handleExactQueueItemSteer(item);
+ return;
+ }
+ if (queuedMessageSteerRoute === 'legacy-native') {
+ await handleLegacyNativeQueueSteer(item);
+ return;
+ }
+ await handleLegacyHeadQueueSteer(item);
+ },
+ [
+ handleExactQueueItemSteer,
+ handleLegacyHeadQueueSteer,
+ handleLegacyNativeQueueSteer,
+ queuedMessageSteerRoute,
+ ]
+ );
+
const handleStartQueueItemEdit = useCallback(
async (item: MessageQueueItem) => {
const isFirstItem = messageQueue[0]?.$cid === item.$cid;
@@ -6162,6 +6307,11 @@ export const SessionChatInterface = memo(
!!activeAssistantTurnId &&
!isExternalHistoryRefreshing
}
+ steerActionScope={legacyQueueSteerRequiresHead ? 'head' : 'all'}
+ steerDisabledReason={t(
+ 'sessions.messageQueue.updateAgentForLaterSteer',
+ 'Update the local agent to steer a later queued message'
+ )}
/>
) : null
}
diff --git a/packages/components/src/providers/workspace-machine-rpc-facade.ts b/packages/components/src/providers/workspace-machine-rpc-facade.ts
index 689db2621..729e814d4 100644
--- a/packages/components/src/providers/workspace-machine-rpc-facade.ts
+++ b/packages/components/src/providers/workspace-machine-rpc-facade.ts
@@ -6,6 +6,7 @@ import type {
import {
getServerNow,
machineSupportsLocalFileResourcesProtocol,
+ machineSupportsQueueItemSteerProtocol,
machineSupportsSubagentCancellation,
type MachineProtocolCapabilities,
type CodeCollabV2Error,
@@ -778,6 +779,17 @@ export function createWorkspaceMachineRpcFacade(deps: WorkspaceMachineRpcFacadeD
options?: { timeoutMs?: number }
): Promise => {
try {
+ const protocolCapabilities = await deps.getMachineProtocolCapabilities(machineId);
+ if (!machineSupportsQueueItemSteerProtocol({ protocolCapabilities })) {
+ return {
+ type: 'session/queue-steer_response',
+ sessionId: args.sessionId,
+ queueItemId: args.queueItemId,
+ accepted: false,
+ disposition: 'unsupported',
+ error: 'This machine does not support exact queued-message steering.',
+ };
+ }
if (await canUseLocalMachineRpc(machineId)) {
const response = await getLocalMachineRpcSender()?.({
machineId,
diff --git a/packages/components/tests/message-queue-row-editing.test.tsx b/packages/components/tests/message-queue-row-editing.test.tsx
index 4861d9e0c..d9d19d2c8 100644
--- a/packages/components/tests/message-queue-row-editing.test.tsx
+++ b/packages/components/tests/message-queue-row-editing.test.tsx
@@ -272,4 +272,41 @@ describe('queued message editing commits', () => {
expect(dragTargets[1]?.textContent).toContain('Later queued task');
expect(dragTargets[1]?.contains(steerButtons[1] ?? null)).toBe(false);
});
+
+ it('keeps only the head Steer enabled for a legacy non-native daemon', async () => {
+ const items = [makeItem('cid-0', 'First queued task'), makeItem('cid-1', 'Later queued task')];
+ const steered: string[] = [];
+ await act(async () => {
+ root?.render(
+ createElement(MessageQueueDisplay, {
+ sessionId: 'session-test' as SessionId,
+ items,
+ onRemove: () => undefined,
+ onReorder: () => undefined,
+ onEditStart: () => undefined,
+ onEditCancel: () => undefined,
+ onEditSave: () => undefined,
+ onSteer: (item: MessageQueueItem) => steered.push(item.$cid),
+ showSteerAction: true,
+ steerActionScope: 'head',
+ steerDisabledReason: 'Update the local agent',
+ })
+ );
+ });
+
+ const steerButtons = Array.from(
+ container!.querySelectorAll(
+ '[aria-label="Steer the active response with this message"]'
+ )
+ );
+ expect(steerButtons).toHaveLength(2);
+ expect(steerButtons[0]?.disabled).toBe(false);
+ expect(steerButtons[1]?.disabled).toBe(true);
+ expect(steerButtons[1]?.title).toBe('Update the local agent');
+ await act(async () => {
+ steerButtons[1]?.click();
+ steerButtons[0]?.click();
+ });
+ expect(steered).toEqual(['cid-0']);
+ });
});
diff --git a/packages/components/tests/queued-message-steer.test.ts b/packages/components/tests/queued-message-steer.test.ts
new file mode 100644
index 000000000..48ededdae
--- /dev/null
+++ b/packages/components/tests/queued-message-steer.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import {
+ resolveQueuedMessageSteerRoute,
+ shouldUseLegacyNativeQueueSteer,
+} from '../src/components/sessions/message-queue';
+
+describe('legacy queued-message steering', () => {
+ it('uses true native steering only for an authoritative acknowledged capability', () => {
+ expect(shouldUseLegacyNativeQueueSteer('authoritative', { acknowledgedSteer: true })).toBe(
+ true
+ );
+ expect(shouldUseLegacyNativeQueueSteer('authoritative', { acknowledgedSteer: false })).toBe(
+ false
+ );
+ expect(shouldUseLegacyNativeQueueSteer('provisional', { acknowledgedSteer: true })).toBe(false);
+ expect(shouldUseLegacyNativeQueueSteer('unavailable', undefined)).toBe(false);
+ });
+
+ it('routes new renderers across new and old daemon capability combinations', () => {
+ expect(
+ resolveQueuedMessageSteerRoute({
+ supportsExactDaemonProtocol: true,
+ authority: 'authoritative',
+ capability: { acknowledgedSteer: true },
+ })
+ ).toBe('exact-daemon');
+ expect(
+ resolveQueuedMessageSteerRoute({
+ supportsExactDaemonProtocol: false,
+ authority: 'authoritative',
+ capability: { acknowledgedSteer: true },
+ })
+ ).toBe('legacy-native');
+ expect(
+ resolveQueuedMessageSteerRoute({
+ supportsExactDaemonProtocol: false,
+ authority: 'authoritative',
+ capability: { acknowledgedSteer: false },
+ })
+ ).toBe('legacy-head');
+ expect(
+ resolveQueuedMessageSteerRoute({
+ supportsExactDaemonProtocol: false,
+ authority: 'provisional',
+ capability: { acknowledgedSteer: true },
+ })
+ ).toBe('legacy-head');
+ });
+});
diff --git a/packages/components/tests/workspace-machine-rpc-facade.test.ts b/packages/components/tests/workspace-machine-rpc-facade.test.ts
index c8fb21957..be576d390 100644
--- a/packages/components/tests/workspace-machine-rpc-facade.test.ts
+++ b/packages/components/tests/workspace-machine-rpc-facade.test.ts
@@ -69,6 +69,31 @@ describe('createWorkspaceMachineRpcFacade', () => {
expect(getMachineRpcClient).not.toHaveBeenCalled();
});
+ it('does not send the exact queue RPC when an older daemon omits its capability', async () => {
+ const getMachineRpcClient = vi.fn(async () => {
+ throw new Error('Unexpected RPC');
+ });
+ const facade = createWorkspaceMachineRpcFacade({
+ workspaceId,
+ getMachineProtocolCapabilities: async () => undefined,
+ targetRouter: {
+ getPlaneForMachine: () => 'remote',
+ resolvePlaneForMachine: async () => 'remote',
+ },
+ getMachineRpcClient,
+ });
+
+ await expect(
+ facade.requestSessionQueueSteer(remoteMachineId, {
+ sessionId,
+ expectedTurnId: 'assistant-active',
+ queueItemId: 'queue-C',
+ requestedByUserId: 'user-1',
+ })
+ ).resolves.toMatchObject({ accepted: false, disposition: 'unsupported' });
+ expect(getMachineRpcClient).not.toHaveBeenCalled();
+ });
+
it('never sends a scoped cancel to a daemon without the scoped-cancel protocol', async () => {
const facade = createWorkspaceMachineRpcFacade({
workspaceId,
diff --git a/packages/shared/src/machine-protocol-capabilities.ts b/packages/shared/src/machine-protocol-capabilities.ts
index 15fdc5958..2a6c51d60 100644
--- a/packages/shared/src/machine-protocol-capabilities.ts
+++ b/packages/shared/src/machine-protocol-capabilities.ts
@@ -14,6 +14,7 @@ export const MACHINE_PROTOCOL_CAPABILITIES = {
providerSetup: 'providerSetup',
localFileResources: 'localFileResources',
acpProtocolAuthentication: 'acpProtocolAuthentication',
+ queueItemSteer: 'queueItemSteer',
} as const;
export const ACP_AUTHENTICATION_INTERACTIONS_PROTOCOL_VERSION = 2;
@@ -22,6 +23,7 @@ export const LOCAL_PROJECT_REMOVAL_PROTOCOL_VERSION = 1;
export const PROVIDER_SETUP_PROTOCOL_VERSION = 1;
export const LOCAL_FILE_RESOURCES_PROTOCOL_VERSION = 1;
export const ACP_PROTOCOL_AUTHENTICATION_VERSION = 2;
+export const QUEUE_ITEM_STEER_PROTOCOL_VERSION = 1;
type MachineProtocolCapabilityCarrier = {
protocolCapabilities?: MachineProtocolCapabilities;
@@ -68,6 +70,7 @@ export const CURRENT_MACHINE_PROTOCOL_CAPABILITIES: MachineProtocolCapabilities
[MACHINE_PROTOCOL_CAPABILITIES.providerSetup]: PROVIDER_SETUP_PROTOCOL_VERSION,
[MACHINE_PROTOCOL_CAPABILITIES.localFileResources]: LOCAL_FILE_RESOURCES_PROTOCOL_VERSION,
[MACHINE_PROTOCOL_CAPABILITIES.acpProtocolAuthentication]: ACP_PROTOCOL_AUTHENTICATION_VERSION,
+ [MACHINE_PROTOCOL_CAPABILITIES.queueItemSteer]: QUEUE_ITEM_STEER_PROTOCOL_VERSION,
};
/** Whether the target daemon supports interactive Custom/Registry ACP authentication. */
@@ -128,3 +131,14 @@ export function machineSupportsLocalFileResourcesProtocol(
LOCAL_FILE_RESOURCES_PROTOCOL_VERSION
);
}
+
+/** Whether the daemon can atomically steer one exact queued item. */
+export function machineSupportsQueueItemSteerProtocol(
+ machine: MachineProtocolCapabilityCarrier | null | undefined
+): boolean {
+ return machineSupportsProtocolCapability(
+ machine,
+ MACHINE_PROTOCOL_CAPABILITIES.queueItemSteer,
+ QUEUE_ITEM_STEER_PROTOCOL_VERSION
+ );
+}
diff --git a/packages/shared/src/message-schemas.ts b/packages/shared/src/message-schemas.ts
index f5c0998e9..a2773d5fe 100644
--- a/packages/shared/src/message-schemas.ts
+++ b/packages/shared/src/message-schemas.ts
@@ -691,9 +691,11 @@ export const SessionQueueSteerResponseSchema = z
disposition: z.enum([
'accepted',
'queue-item-missing',
+ 'queue-item-editing',
'invalid-queue-item',
'no-active-turn',
'stale-turn',
+ 'unsupported',
'busy',
'error',
]),
diff --git a/packages/shared/src/message.ts b/packages/shared/src/message.ts
index 6dacc28c6..25ce50952 100644
--- a/packages/shared/src/message.ts
+++ b/packages/shared/src/message.ts
@@ -175,9 +175,11 @@ export interface SessionQueueSteerResponse {
disposition:
| 'accepted'
| 'queue-item-missing'
+ | 'queue-item-editing'
| 'invalid-queue-item'
| 'no-active-turn'
| 'stale-turn'
+ | 'unsupported'
| 'busy'
| 'error';
error?: string;
diff --git a/packages/shared/tests/machine-protocol-capabilities.test.ts b/packages/shared/tests/machine-protocol-capabilities.test.ts
index 83f64112b..b6235ab4c 100644
--- a/packages/shared/tests/machine-protocol-capabilities.test.ts
+++ b/packages/shared/tests/machine-protocol-capabilities.test.ts
@@ -6,6 +6,7 @@ import {
MACHINE_PROTOCOL_CAPABILITIES,
machineSupportsAcpAuthenticationInteractionsProtocol,
machineSupportsLocalFileResourcesProtocol,
+ machineSupportsQueueItemSteerProtocol,
} from '../src/machine-protocol-capabilities';
describe('ACP authentication interaction protocol capability', () => {
@@ -46,3 +47,17 @@ it('requires an advertised local file resource protocol, independent of release
})
).toBe(true);
});
+
+it('requires an advertised exact queue-item steer protocol', () => {
+ expect(machineSupportsQueueItemSteerProtocol(undefined)).toBe(false);
+ expect(
+ machineSupportsQueueItemSteerProtocol({
+ protocolCapabilities: { [MACHINE_PROTOCOL_CAPABILITIES.queueItemSteer]: 0 },
+ })
+ ).toBe(false);
+ expect(
+ machineSupportsQueueItemSteerProtocol({
+ protocolCapabilities: CURRENT_MACHINE_PROTOCOL_CAPABILITIES,
+ })
+ ).toBe(true);
+});
diff --git a/specs/message-queue-interactions.md b/specs/message-queue-interactions.md
index d4cb6181f..dd27fcfa2 100644
--- a/specs/message-queue-interactions.md
+++ b/specs/message-queue-interactions.md
@@ -20,15 +20,31 @@ the queue by hand.
preference and still obeys the ordinary availability, live-activity, and unfinished-
transcript safeguards. Composer focus, content, and send readiness are command-level
availability rules so user-rebound shortcuts retain them.
-- While steering is available for the active turn, every queued message exposes Steer.
- Selecting an item sends its durable queue identity and the expected active turn to the
- owning daemon. The daemon revalidates both identities, atomically consumes only that row
- into the next durable user turn, and then stops the expected turn. Queue order is never
- rewritten as part of Steer: selecting C from `[A, B, C]` produces the active turn C and
- leaves `[A, B]`.
-- A stale Steer selection is a failed no-op. If the selected queue identity is missing, or
- the expected turn no longer owns execution, the daemon must not stop any turn. The
- renderer waits for this acknowledgement and never removes or materializes the row itself.
+- Exact-item steering is a versioned daemon workflow. A renderer may call
+ `session/queue-steer` only when `MachineMeta.protocolCapabilities.queueItemSteer` advertises
+ a supported version; a missing capability means unsupported. The request carries the
+ durable queue identity and expected active turn. The daemon, not the renderer, chooses the
+ execution mechanism:
+
+ | Active daemon/runtime | Steer behavior |
+ | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+ | Exact-item protocol and acknowledged native ACP Steer | Atomically consume the selected row as `pending_apply`, then inject it into the current prompt through `steerPrompt`. |
+ | Exact-item protocol without native ACP Steer | Atomically consume the selected row as the next user turn, then stop only the expected turn. |
+ | Older daemon with authoritative acknowledged native ACP Steer | Preserve the legacy native Steer path. |
+ | Older daemon without acknowledged native ACP Steer | Keep the established queue-head interrupt behavior; disable Steer on later rows and require a daemon update for exact selection. |
+
+ No compatibility path may reorder a later item and then cancel. Selecting C from
+ `[A, B, C]` through the exact protocol consumes C and leaves `[A, B]` in that order.
+
+- A stale or conflicting exact Steer selection is a failed no-op. If the selected queue
+ identity is missing, its editing lease is active, or the expected turn no longer owns
+ execution, the daemon must not submit native Steer or stop any turn. The renderer waits for
+ this acknowledgement and never removes or materializes an exact-protocol row itself.
+- The daemon retains a bounded receipt for each recently consumed exact-item request, keyed by
+ session, expected turn, and queue identity. A same-process retry after a lost response returns
+ the recorded result without consuming or cancelling again. If consumption succeeded but
+ cancellation failed, the message remains a durable follow-up and a retained-receipt retry must
+ not duplicate it.
- The number and non-editing message body form the drag target for queue reordering.
Steer, edit, and remove remain separate controls and must not begin a drag.
- Editing keeps its existing keyboard and focus behavior and disables reordering for
diff --git a/specs/message-queue-interactions.zh.md b/specs/message-queue-interactions.zh.md
index 74f03e1e2..e3692d3c7 100644
--- a/specs/message-queue-interactions.zh.md
+++ b/specs/message-queue-interactions.zh.md
@@ -16,12 +16,27 @@ Translation: current
意图：命令直接为本次提交传入 `queueBehavior: "inverse"`，普通 Enter 不传覆盖项。它不
修改设置，并继续遵守普通的可用性、实时活动和未完成消息记录保护。输入框聚焦、有内容且
可以发送属于命令本身的可用条件，因此用户重绑快捷键后仍受同一限制。
-- 当前 turn 可接受引导时，每条排队消息都提供“引导”操作。选择后续项必须以该项为目标。
- 客户端把该项的持久 ID 和预期活动 turn 一并发给所属 daemon；daemon 重新确认两者，在一次
- Session Doc 更新中只消费该项为下一个用户 turn，再停止预期 turn。“引导”绝不修改队列顺序：
- 从 `[A, B, C]` 选择 C 后，正在执行的是 C，队列剩下 `[A, B]`。
-- 过期的“引导”选择必须是失败且无副作用的操作。所选 ID 已不存在，或预期 turn 已不再拥有
- 执行权时，daemon 不得停止任何 turn。Renderer 等待 daemon 确认，不自行移除队列项或写历史。
+- 精确队列项引导是版本化 daemon workflow。只有
+ `MachineMeta.protocolCapabilities.queueItemSteer` 声明受支持版本时，Renderer 才能调用
+ `session/queue-steer`；缺少 capability 即表示不支持。请求携带持久队列 ID 和预期活动 turn，
+ 具体执行方式由 daemon 而非 Renderer 决定：
+
+ | 当前 daemon/runtime | 引导行为 |
+ | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+ | 支持精确队列项协议，且支持 acknowledged native ACP Steer | 原子消费目标行为 `pending_apply`，再通过 `steerPrompt` 注入当前 prompt。 |
+ | 支持精确队列项协议，但不支持 native ACP Steer | 原子消费目标行为下一个用户 turn，再只停止预期 turn。 |
+ | 旧 daemon，但 authoritative capability 声明支持 acknowledged native ACP Steer | 保留旧版真正 native Steer 路径。 |
+ | 旧 daemon，且不支持 acknowledged native ACP Steer | 仅保留既有队首 interrupt 行为；禁用后续行“引导”，并要求升级 daemon 才能精确选择。 |
+
+ 任何兼容路径都不得先重排后续项再取消。从 `[A, B, C]` 通过精确协议选择 C 时，只消费 C，
+ 剩余队列保持 `[A, B]`。
+
+- 过期或冲突的精确“引导”选择必须失败且无副作用。所选 ID 已不存在、编辑 lease 仍有效，或
+ 预期 turn 已不再拥有执行权时，daemon 不得提交 native Steer，也不得停止任何 turn。Renderer
+ 等待确认，不自行移除队列项或为精确协议写历史。
+- daemon 会按 session、预期 turn 和队列 ID，为最近已消费的精确请求保留有界 receipt。
+ 同一 daemon 进程内因响应丢失而重试时，应返回已记录结果，不得再次消费或取消。若消费
+ 成功但取消失败，消息仍是持久 follow-up；receipt 仍保留时的重试不得复制它。
- 序号和非编辑状态的消息正文共同组成队列重排拖动区域。“引导”、“编辑”和“移除”是独立
控件，不能触发拖动。
- 编辑状态保留已有键盘与焦点行为，并在编辑结束前禁用该行重排。
From 31582d5354d2af2865c617585765bf4862fe5bf9 Mon Sep 17 00:00:00 2001
From: wibus-wee <62133302+wibus-wee@users.noreply.github.com>
Date: Mon, 14 Sep 2026 12:24:07 +0800
Subject: [PATCH 04/15] fix: authenticate queued steer at source
Model: gpt-5
---
.agents/docs/rpc-loro-streams-rpc.md | 3 +
.../2026-09-13-queue-steer-controls.md | 9 ++-
.../2026-09-13-queue-steer-controls.zh.md | 6 +-
apps/cli/src/lib/message-handler.ts | 21 +------
.../src/session/session-execution-service.ts | 1 -
.../tests/session-execution-service.test.ts | 5 --
packages/components/src/atoms/runtime.ts | 1 -
.../sessions/session-chat-interface.tsx | 5 +-
.../src/hooks/use-session-actions.ts | 10 ++-
.../src/providers/create-workspace-runtime.ts | 1 +
.../providers/workspace-machine-rpc-facade.ts | 14 ++++-
.../tests/use-session-actions.test.ts | 6 +-
.../workspace-machine-rpc-facade.test.ts | 62 ++++++++++++++++++-
packages/loro-streams-rpc/AGENTS.md | 4 +-
.../src/machine-rpc-server.ts | 2 -
packages/loro-streams-rpc/src/rpc.ts | 4 --
.../tests/loro-streams-rpc.test.ts | 23 ++++++-
packages/shared/src/local-machine-rpc.ts | 1 -
.../shared/tests/local-machine-rpc.test.ts | 1 -
specs/message-queue-interactions.md | 6 ++
specs/message-queue-interactions.zh.md | 5 ++
21 files changed, 132 insertions(+), 58 deletions(-)
diff --git a/.agents/docs/rpc-loro-streams-rpc.md b/.agents/docs/rpc-loro-streams-rpc.md
index e4ee0e8ea..352674d16 100644
--- a/.agents/docs/rpc-loro-streams-rpc.md
+++ b/.agents/docs/rpc-loro-streams-rpc.md
@@ -25,6 +25,9 @@ request names both the expected active turn and exact queued item, and callers r
negotiated `queueItemSteer` protocol capability. The CLI consumes the item only when its
editing lease is inactive, then preserves native ACP Steer when acknowledged or cancels the
expected turn for ordinary follow-up dispatch. Missing, editing, and stale targets do neither.
+Before a remote renderer writes this control request, it fails closed against its authenticated
+`machines:listVisibleMachines` snapshot. The retained request contains no requester identity:
+the target daemon cannot authenticate such a claim and must not grant its owner fast path from it.
## Remote lifecycle acknowledgements
diff --git a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
index 2853ef728..0cfd3baa9 100644
--- a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
+++ b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
@@ -26,6 +26,11 @@ the selected identity is missing.
`session/queue-steer` only when that version is present; missing means unsupported. The
request names the queue `$cid` and expected active turn, and the renderer waits for the
result without changing queue or history locally.
+- Authorize a remote request before appending it, using the renderer's authenticated,
+ Convex-authoritative visible-machine snapshot. Fail closed while that snapshot is unavailable
+ or excludes the target. The RPC carries no requester identity because a target daemon cannot
+ authenticate an identity claimed by a workspace stream writer. Same-host local IPC remains the
+ trusted local control path.
- Let the daemon choose the execution mechanism after validating both identities and the
target's editing lease. With acknowledged native ACP Steer, it atomically consumes the row
as `pending_apply` and enters the existing `steerPrompt` handoff. Without native Steer, it
@@ -61,8 +66,8 @@ become accidental drag starters.
- CLI service and Session Doc tests cover exact C consumption, native `steerPrompt`, exact
cancellation, missing and active-edit rejection, cancellation failure, and response-loss
retries.
-- Machine RPC and protocol-capability tests cover both required identities and mixed-version
- negotiation.
+- Machine RPC and protocol-capability tests cover the queue/turn identities, rejection of a
+ requester identity claim, source authorization, and mixed-version negotiation.
- Component tests use synthetic pointer state. Physical touch dragging and a full
provider-backed steer run were not exercised.
diff --git a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
index a86aff399..ad8977d20 100644
--- a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
@@ -21,6 +21,9 @@ Translation: current
- 在 `MachineMeta.protocolCapabilities` 声明 `queueItemSteer`。只有该版本存在时，Renderer
才调用 `session/queue-steer`；缺失即表示不支持。请求携带队列 `$cid` 与预期活动 turn，
Renderer 等待结果，不在本地修改队列或历史。
+- 远程请求写入前，Renderer 必须使用已认证且以 Convex 为权威来源的可见 machine 快照做
+ 授权；快照尚不可用或不包含目标时应 fail closed。RPC 不携带请求者身份，因为目标 daemon
+ 无法认证 workspace stream 写入者声称的身份。同机 local IPC 仍是可信的本地控制路径。
- Daemon 确认两个 ID 及目标 editing lease 后决定执行机制。支持 acknowledged native ACP
Steer 时，原子消费目标行为 `pending_apply`，并进入既有 `steerPrompt` handoff；否则消费为
普通 pending turn，再只取消预期活动 turn。
@@ -48,7 +51,8 @@ native steer，因为 `steerPrompt` 注入当前 prompt，而 cancel-and-dispatc
拖动区域边界。
- CLI service 与 Session Doc 测试覆盖精确消费 C、native `steerPrompt`、精确取消、目标缺失、
editing lease、取消失败及响应丢失重试。
-- Machine RPC 与 protocol capability 测试覆盖两个必需 ID 和混合版本协商。
+- Machine RPC 与 protocol capability 测试覆盖队列／turn 两个 ID、拒绝请求者身份声明、来源
+ 授权以及混合版本协商。
- 组件测试使用合成指针状态；未验证物理触摸拖动和完整的 Provider-backed steer 流程。
## 参考
diff --git a/apps/cli/src/lib/message-handler.ts b/apps/cli/src/lib/message-handler.ts
index 2596e0a45..a1b62931d 100644
--- a/apps/cli/src/lib/message-handler.ts
+++ b/apps/cli/src/lib/message-handler.ts
@@ -2635,23 +2635,6 @@ export class MessageHandler {
return await this.executionService.steerSession(args);
}
- private async steerQueuedMessageWithAccessCheck(
- args: Parameters[0]
- ): ReturnType {
- const access = await this.verifySessionMachineAccess(args.sessionId, args.requestedByUserId);
- if (access.outcome !== 'allowed') {
- return {
- type: 'session/queue-steer_response',
- sessionId: args.sessionId,
- queueItemId: args.queueItemId,
- accepted: false,
- disposition: 'error',
- error: `Queue steer access verification ${access.outcome}`,
- };
- }
- return await this.executionService.steerQueuedMessage(args);
- }
-
private async controlSessionGoalWithAccessCheck(args: {
sessionId: SessionId;
action: SessionGoalAction;
@@ -3297,7 +3280,7 @@ export class MessageHandler {
};
},
steerSession: async (args) => await this.steerSessionWithAccessCheck(args),
- steerQueuedMessage: async (args) => await this.steerQueuedMessageWithAccessCheck(args),
+ steerQueuedMessage: async (args) => await this.executionService.steerQueuedMessage(args),
controlSessionGoal: async (args) => await this.controlSessionGoalWithAccessCheck(args),
terminateSession: async ({ sessionId }) => await this.terminateAcpSession(sessionId),
forkSession: async (args) => await this.forkSessionWithAccessCheck(args),
@@ -6334,7 +6317,7 @@ export class MessageHandler {
});
}
case 'session/queue-steer': {
- return await this.steerQueuedMessageWithAccessCheck({
+ return await this.executionService.steerQueuedMessage({
...request.params,
sessionId: request.params.sessionId as SessionId,
});
diff --git a/apps/cli/src/session/session-execution-service.ts b/apps/cli/src/session/session-execution-service.ts
index 9d4e222f3..adf9af148 100644
--- a/apps/cli/src/session/session-execution-service.ts
+++ b/apps/cli/src/session/session-execution-service.ts
@@ -1414,7 +1414,6 @@ export class SessionExecutionService {
sessionId: SessionId;
expectedTurnId: string;
queueItemId: string;
- requestedByUserId: string;
}): Promise {
const operationKey = JSON.stringify([
options.sessionId,
diff --git a/apps/cli/tests/session-execution-service.test.ts b/apps/cli/tests/session-execution-service.test.ts
index 1c7522c1f..977f07c4c 100644
--- a/apps/cli/tests/session-execution-service.test.ts
+++ b/apps/cli/tests/session-execution-service.test.ts
@@ -340,7 +340,6 @@ describe('SessionExecutionService', () => {
sessionId,
expectedTurnId: activeTurnId,
queueItemId: 'C',
- requestedByUserId: 'owner-user',
};
await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
accepted: true,
@@ -407,7 +406,6 @@ describe('SessionExecutionService', () => {
sessionId,
expectedTurnId: activeTurnId,
queueItemId: 'C',
- requestedByUserId: 'owner-user',
})
).resolves.toMatchObject({
accepted: false,
@@ -460,7 +458,6 @@ describe('SessionExecutionService', () => {
sessionId,
expectedTurnId: activeTurnId,
queueItemId: 'C',
- requestedByUserId: 'owner-user',
})
).resolves.toMatchObject({ accepted: false, disposition: 'queue-item-editing' });
expect(cancel).not.toHaveBeenCalled();
@@ -511,7 +508,6 @@ describe('SessionExecutionService', () => {
sessionId,
expectedTurnId: activeTurnId,
queueItemId: 'C',
- requestedByUserId: 'owner-user',
};
await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
@@ -633,7 +629,6 @@ describe('SessionExecutionService', () => {
sessionId,
expectedTurnId: 'assistant:user-1',
queueItemId: queuedItem.$cid,
- requestedByUserId: 'user-1',
})
).resolves.toMatchObject({ accepted: true, disposition: 'accepted', userTurnId: 'user-2' });
expect(onTurnSettled).toHaveBeenCalledOnce();
diff --git a/packages/components/src/atoms/runtime.ts b/packages/components/src/atoms/runtime.ts
index f5e622afd..12364f432 100644
--- a/packages/components/src/atoms/runtime.ts
+++ b/packages/components/src/atoms/runtime.ts
@@ -322,7 +322,6 @@ export type WorkspaceRuntime = {
sessionId: SessionId;
expectedTurnId: string;
queueItemId: string;
- requestedByUserId: string;
},
options?: { timeoutMs?: number }
) => Promise;
diff --git a/packages/components/src/components/sessions/session-chat-interface.tsx b/packages/components/src/components/sessions/session-chat-interface.tsx
index c484030b0..522ef450c 100644
--- a/packages/components/src/components/sessions/session-chat-interface.tsx
+++ b/packages/components/src/components/sessions/session-chat-interface.tsx
@@ -5116,7 +5116,7 @@ export const SessionChatInterface = memo(
const handleExactQueueItemSteer = useCallback(
async (item: MessageQueueItem) => {
- if (isExternalHistoryRefreshing || !activeAssistantTurnId || !currentUser?.id) {
+ if (isExternalHistoryRefreshing || !activeAssistantTurnId) {
return;
}
if (steeringQueueItemIdsRef.current.has(item.$cid)) return;
@@ -5126,7 +5126,7 @@ export const SessionChatInterface = memo(
session.id,
activeAssistantTurnId,
item.$cid,
- { machineId: session.machineId, requestedByUserId: currentUser.id }
+ { machineId: session.machineId }
);
captureSessionEvent('session/queue_steer_result', {
queue_item_id: item.$cid,
@@ -5165,7 +5165,6 @@ export const SessionChatInterface = memo(
[
activeAssistantTurnId,
captureSessionEvent,
- currentUser?.id,
isExternalHistoryRefreshing,
requestSessionQueueSteer,
session.id,
diff --git a/packages/components/src/hooks/use-session-actions.ts b/packages/components/src/hooks/use-session-actions.ts
index 226547f00..6a3a8d2f6 100644
--- a/packages/components/src/hooks/use-session-actions.ts
+++ b/packages/components/src/hooks/use-session-actions.ts
@@ -305,7 +305,7 @@ export type SessionActions = {
sessionId: SessionId,
expectedTurnId: string,
queueItemId: string,
- options: { requestedByUserId: string; machineId?: MachineId | null }
+ options?: { machineId?: MachineId | null }
) => Promise;
/**
* Run a goal action through the agent's control extension.
@@ -964,13 +964,13 @@ export function useSessionActions(): SessionActions {
sessionId: SessionId,
expectedTurnId: string,
queueItemId: string,
- options: { requestedByUserId: string; machineId?: MachineId | null }
+ options?: { machineId?: MachineId | null }
): Promise => {
if (!runtime) {
throw new Error('Runtime not ready');
}
const roomId = getSessionRoomId(sessionId);
- let machineId = options.machineId ?? null;
+ let machineId = options?.machineId ?? null;
if (!machineId) {
const existing = await runtime.repo.getDocMeta(roomId);
const meta = isLoroRepoDocDeleted(existing)
@@ -978,15 +978,13 @@ export function useSessionActions(): SessionActions {
: (existing?.meta as SessionMeta | undefined);
machineId = meta?.machineId ?? null;
}
- const requestedByUserId = options.requestedByUserId.trim();
- if (!machineId || !requestedByUserId) {
+ if (!machineId) {
return null;
}
return await runtime.requestSessionQueueSteer(machineId, {
sessionId,
expectedTurnId,
queueItemId,
- requestedByUserId,
});
},
[runtime]
diff --git a/packages/components/src/providers/create-workspace-runtime.ts b/packages/components/src/providers/create-workspace-runtime.ts
index 407fe0d73..5e24f3fdf 100644
--- a/packages/components/src/providers/create-workspace-runtime.ts
+++ b/packages/components/src/providers/create-workspace-runtime.ts
@@ -1720,6 +1720,7 @@ export async function createWorkspaceRuntime(deps: RuntimeDeps): Promise | undefined)?.protocolCapabilities;
},
+ getAuthorizedMachineIds: deps.getAuthorizedMachineIds,
workspaceId,
targetRouter,
getMachineRpcClient,
diff --git a/packages/components/src/providers/workspace-machine-rpc-facade.ts b/packages/components/src/providers/workspace-machine-rpc-facade.ts
index 729e814d4..f7138862c 100644
--- a/packages/components/src/providers/workspace-machine-rpc-facade.ts
+++ b/packages/components/src/providers/workspace-machine-rpc-facade.ts
@@ -95,6 +95,8 @@ export type WorkspaceMachineRpcFacadeDeps = {
getMachineProtocolCapabilities: (
machineId: MachineId
) => Promise;
+ /** Authenticated source snapshot; null means cloud authorization is not ready. */
+ getAuthorizedMachineIds?: () => ReadonlySet | null;
getMachineRpcClient: (machineId: MachineId) => Promise;
};
@@ -774,7 +776,6 @@ export function createWorkspaceMachineRpcFacade(deps: WorkspaceMachineRpcFacadeD
sessionId: SessionId;
expectedTurnId: string;
queueItemId: string;
- requestedByUserId: string;
},
options?: { timeoutMs?: number }
): Promise => {
@@ -810,6 +811,17 @@ export function createWorkspaceMachineRpcFacade(deps: WorkspaceMachineRpcFacadeD
}
if (response?.ok) return response.result as SessionQueueSteerResponse;
}
+ const authorizedMachineIds = deps.getAuthorizedMachineIds?.() ?? null;
+ if (!authorizedMachineIds?.has(machineId)) {
+ return {
+ type: 'session/queue-steer_response',
+ sessionId: args.sessionId,
+ queueItemId: args.queueItemId,
+ accepted: false,
+ disposition: 'error',
+ error: 'Source authorization for this machine is unavailable or denied.',
+ };
+ }
return await (
await getMachineRpcClient(machineId)
).requestSessionQueueSteer({
diff --git a/packages/components/tests/use-session-actions.test.ts b/packages/components/tests/use-session-actions.test.ts
index a08776e88..1b7ee4a02 100644
--- a/packages/components/tests/use-session-actions.test.ts
+++ b/packages/components/tests/use-session-actions.test.ts
@@ -389,16 +389,12 @@ describe('useSessionActions', () => {
const actions = await renderActions(runtime);
await expect(
- actions.requestSessionQueueSteer(sessionId, 'assistant-active', 'queue-C', {
- machineId,
- requestedByUserId: 'user-1',
- })
+ actions.requestSessionQueueSteer(sessionId, 'assistant-active', 'queue-C', { machineId })
).resolves.toMatchObject({ accepted: true, queueItemId: 'queue-C' });
expect(requestSessionQueueSteer).toHaveBeenCalledWith(machineId, {
sessionId,
expectedTurnId: 'assistant-active',
queueItemId: 'queue-C',
- requestedByUserId: 'user-1',
});
});
diff --git a/packages/components/tests/workspace-machine-rpc-facade.test.ts b/packages/components/tests/workspace-machine-rpc-facade.test.ts
index be576d390..c4c459eb4 100644
--- a/packages/components/tests/workspace-machine-rpc-facade.test.ts
+++ b/packages/components/tests/workspace-machine-rpc-facade.test.ts
@@ -49,7 +49,6 @@ describe('createWorkspaceMachineRpcFacade', () => {
sessionId,
expectedTurnId: 'assistant-active',
queueItemId: 'queue-C',
- requestedByUserId: 'user-1',
})
).resolves.toMatchObject({ accepted: true, queueItemId: 'queue-C' });
expect(invoke).toHaveBeenCalledWith(
@@ -62,7 +61,6 @@ describe('createWorkspaceMachineRpcFacade', () => {
sessionId,
expectedTurnId: 'assistant-active',
queueItemId: 'queue-C',
- requestedByUserId: 'user-1',
},
})
);
@@ -88,12 +86,70 @@ describe('createWorkspaceMachineRpcFacade', () => {
sessionId,
expectedTurnId: 'assistant-active',
queueItemId: 'queue-C',
- requestedByUserId: 'user-1',
})
).resolves.toMatchObject({ accepted: false, disposition: 'unsupported' });
expect(getMachineRpcClient).not.toHaveBeenCalled();
});
+ it('fails closed before remote queue Steer when source authorization is unavailable', async () => {
+ const requestSessionQueueSteer = vi.fn();
+ const getMachineRpcClient = vi.fn(async () => ({ requestSessionQueueSteer }));
+ const facade = createWorkspaceMachineRpcFacade({
+ workspaceId,
+ getMachineProtocolCapabilities: async () => CURRENT_MACHINE_PROTOCOL_CAPABILITIES,
+ getAuthorizedMachineIds: () => null,
+ targetRouter: {
+ getPlaneForMachine: () => 'remote',
+ resolvePlaneForMachine: async () => 'remote',
+ },
+ getMachineRpcClient,
+ });
+
+ await expect(
+ facade.requestSessionQueueSteer(remoteMachineId, {
+ sessionId,
+ expectedTurnId: 'assistant-active',
+ queueItemId: 'queue-C',
+ })
+ ).resolves.toMatchObject({ accepted: false, disposition: 'error' });
+ expect(getMachineRpcClient).not.toHaveBeenCalled();
+ });
+
+ it('sends remote queue Steer only for a source-authorized machine and carries no identity claim', async () => {
+ const requestSessionQueueSteer = vi.fn(async () => ({
+ type: 'session/queue-steer_response' as const,
+ sessionId,
+ queueItemId: 'queue-C',
+ userTurnId: 'user-C',
+ accepted: true,
+ disposition: 'accepted' as const,
+ }));
+ const facade = createWorkspaceMachineRpcFacade({
+ workspaceId,
+ getMachineProtocolCapabilities: async () => CURRENT_MACHINE_PROTOCOL_CAPABILITIES,
+ getAuthorizedMachineIds: () => new Set([remoteMachineId]),
+ targetRouter: {
+ getPlaneForMachine: () => 'remote',
+ resolvePlaneForMachine: async () => 'remote',
+ },
+ getMachineRpcClient: async () => ({ requestSessionQueueSteer }) as never,
+ });
+
+ await expect(
+ facade.requestSessionQueueSteer(remoteMachineId, {
+ sessionId,
+ expectedTurnId: 'assistant-active',
+ queueItemId: 'queue-C',
+ })
+ ).resolves.toMatchObject({ accepted: true });
+ expect(requestSessionQueueSteer).toHaveBeenCalledWith({
+ sessionId,
+ expectedTurnId: 'assistant-active',
+ queueItemId: 'queue-C',
+ timeoutMs: 5_000,
+ });
+ });
+
it('never sends a scoped cancel to a daemon without the scoped-cancel protocol', async () => {
const facade = createWorkspaceMachineRpcFacade({
workspaceId,
diff --git a/packages/loro-streams-rpc/AGENTS.md b/packages/loro-streams-rpc/AGENTS.md
index d3d961d8e..83114c45d 100644
--- a/packages/loro-streams-rpc/AGENTS.md
+++ b/packages/loro-streams-rpc/AGENTS.md
@@ -55,8 +55,8 @@ and the `file/preview` namespace are in
dispatch watcher — never run the agent turn inside the handler. Its `expiresAt`
is deliberately short (== client timeout, ~15s) because a server restart replays
the request stream from offset `'-1'`.
-- Session orchestration authorization is checked source-side with the source CLI
- token because workspace RPC cannot authenticate a claimed requester identity.
+- Authorize orchestration at source (CLI token or renderer access snapshot);
+ workspace RPC never trusts claimed requester ids.
`session/live-status` reads the target
daemon's active-presence controller and must not infer liveness from durable
`SessionMeta.status` or message pointers.
diff --git a/packages/loro-streams-rpc/src/machine-rpc-server.ts b/packages/loro-streams-rpc/src/machine-rpc-server.ts
index a06a46adb..11d904b96 100644
--- a/packages/loro-streams-rpc/src/machine-rpc-server.ts
+++ b/packages/loro-streams-rpc/src/machine-rpc-server.ts
@@ -356,7 +356,6 @@ type RpcServerDeps = {
sessionId: SessionId;
expectedTurnId: string;
queueItemId: string;
- requestedByUserId: string;
}) => Promise;
steerSession?: (args: {
sessionId: SessionId;
@@ -1127,7 +1126,6 @@ export class LoroStreamsMachineRpcServer {
sessionId: request.params.sessionId as SessionId,
expectedTurnId: request.params.expectedTurnId,
queueItemId: request.params.queueItemId,
- requestedByUserId: request.params.requestedByUserId,
});
await this.appendResultResponse(request.replyTo, request.id, request.method, response);
return;
diff --git a/packages/loro-streams-rpc/src/rpc.ts b/packages/loro-streams-rpc/src/rpc.ts
index cdd7e6d68..6e44f05a0 100644
--- a/packages/loro-streams-rpc/src/rpc.ts
+++ b/packages/loro-streams-rpc/src/rpc.ts
@@ -482,7 +482,6 @@ export const LoroSessionQueueSteerRpcRequestSchema = BaseRpcRequestSchema.extend
sessionId: SessionIdSchema,
expectedTurnId: z.string().trim().min(1),
queueItemId: z.string().trim().min(1),
- requestedByUserId: z.string().trim().min(1),
})
.strict(),
}).strict();
@@ -2732,7 +2731,6 @@ export class LoroStreamsMachineRpcClient {
sessionId: SessionId;
expectedTurnId: string;
queueItemId: string;
- requestedByUserId: string;
timeoutMs?: number;
}): Promise {
return (await this.sendRequest({
@@ -2742,7 +2740,6 @@ export class LoroStreamsMachineRpcClient {
sessionId: options.sessionId,
expectedTurnId: options.expectedTurnId,
queueItemId: options.queueItemId,
- requestedByUserId: options.requestedByUserId,
},
})) as SessionQueueSteerResponse | null;
}
@@ -3231,7 +3228,6 @@ export class LoroStreamsMachineRpcClient {
sessionId: SessionId;
expectedTurnId: string;
queueItemId: string;
- requestedByUserId: string;
};
}
| {
diff --git a/packages/loro-streams-rpc/tests/loro-streams-rpc.test.ts b/packages/loro-streams-rpc/tests/loro-streams-rpc.test.ts
index ab49ede0c..2e5cd6495 100644
--- a/packages/loro-streams-rpc/tests/loro-streams-rpc.test.ts
+++ b/packages/loro-streams-rpc/tests/loro-streams-rpc.test.ts
@@ -115,12 +115,33 @@ describe('queued message steer RPC schema', () => {
sessionId: 'session-1',
expectedTurnId: 'assistant:user-1',
queueItemId: 'queue-C',
- requestedByUserId: 'user-1',
},
});
expect(result.success).toBe(true);
});
+
+ it('rejects an untrusted requester identity claim', () => {
+ const result = LoroStreamsRpcRequestSchema.safeParse({
+ jsonrpc: '2.0',
+ id: 'request-queue-steer-1',
+ method: 'session/queue-steer',
+ rpcVersion: '1',
+ workspaceId: 'workspace-1',
+ machineId: 'machine-1',
+ replyTo: 'workspace-1:rpc:res',
+ sentAt: 1,
+ expiresAt: 2,
+ params: {
+ sessionId: 'session-1',
+ expectedTurnId: 'assistant:user-1',
+ queueItemId: 'queue-C',
+ requestedByUserId: 'owner-user',
+ },
+ });
+
+ expect(result.success).toBe(false);
+ });
});
describe('session preparation RPC schema', () => {
diff --git a/packages/shared/src/local-machine-rpc.ts b/packages/shared/src/local-machine-rpc.ts
index fbdab4918..8b2c232df 100644
--- a/packages/shared/src/local-machine-rpc.ts
+++ b/packages/shared/src/local-machine-rpc.ts
@@ -201,7 +201,6 @@ export const LocalMachineRpcRequestSchema = z.discriminatedUnion('method', [
sessionId: SessionIdSchema,
expectedTurnId: z.string().trim().min(1),
queueItemId: z.string().trim().min(1),
- requestedByUserId: z.string().trim().min(1),
})
.strict(),
}).strict(),
diff --git a/packages/shared/tests/local-machine-rpc.test.ts b/packages/shared/tests/local-machine-rpc.test.ts
index 56dd08fc9..5333191b7 100644
--- a/packages/shared/tests/local-machine-rpc.test.ts
+++ b/packages/shared/tests/local-machine-rpc.test.ts
@@ -47,7 +47,6 @@ describe('local Machine RPC', () => {
sessionId: 'session-1',
expectedTurnId: 'assistant:turn-0',
queueItemId: 'queue-C',
- requestedByUserId: 'user-1',
},
},
{
diff --git a/specs/message-queue-interactions.md b/specs/message-queue-interactions.md
index dd27fcfa2..d2f60556f 100644
--- a/specs/message-queue-interactions.md
+++ b/specs/message-queue-interactions.md
@@ -36,6 +36,12 @@ the queue by hand.
No compatibility path may reorder a later item and then cancel. Selecting C from
`[A, B, C]` through the exact protocol consumes C and leaves `[A, B]` in that order.
+ A remote renderer must authorize the target before writing the request, using its
+ authenticated authoritative machine-access snapshot and failing closed if that snapshot is
+ unavailable. The request carries no requester identity: workspace Machine RPC cannot
+ authenticate a caller-supplied member ID, and the target daemon must not use one for an owner
+ fast path. Same-host local IPC is already the trusted local control boundary.
+
- A stale or conflicting exact Steer selection is a failed no-op. If the selected queue
identity is missing, its editing lease is active, or the expected turn no longer owns
execution, the daemon must not submit native Steer or stop any turn. The renderer waits for
diff --git a/specs/message-queue-interactions.zh.md b/specs/message-queue-interactions.zh.md
index e3692d3c7..5f5349244 100644
--- a/specs/message-queue-interactions.zh.md
+++ b/specs/message-queue-interactions.zh.md
@@ -31,6 +31,11 @@ Translation: current
任何兼容路径都不得先重排后续项再取消。从 `[A, B, C]` 通过精确协议选择 C 时，只消费 C，
剩余队列保持 `[A, B]`。
+ 远程 Renderer 在写入请求前，必须使用其已认证的权威 machine-access 快照验证目标；快照
+ 不可用时应 fail closed。请求不得携带请求者身份：workspace Machine RPC 无法认证调用方
+ 声称的成员 ID，目标 daemon 也不得用它命中 owner fast path。同机 local IPC 已是可信的
+ 本地控制边界。
+
- 过期或冲突的精确“引导”选择必须失败且无副作用。所选 ID 已不存在、编辑 lease 仍有效，或
预期 turn 已不再拥有执行权时，daemon 不得提交 native Steer，也不得停止任何 turn。Renderer
等待确认，不自行移除队列项或为精确协议写历史。
From feeb1180cfdbe1d65731ec2e278dafb2939ba9a4 Mon Sep 17 00:00:00 2001
From: wibus-wee <62133302+wibus-wee@users.noreply.github.com>
Date: Mon, 14 Sep 2026 12:42:01 +0800
Subject: [PATCH 05/15] fix: retain queue row through activation
Model: gpt-5
---
.agents/docs/rpc-loro-streams-rpc.md | 8 ++-
.../2026-09-13-queue-steer-controls.md | 8 ++-
.../2026-09-13-queue-steer-controls.zh.md | 5 +-
apps/cli/src/lib/loro/AGENTS.md | 3 +-
apps/cli/src/lib/loro/doc-user-turn.test.ts | 29 +++++++-
apps/cli/src/lib/loro/doc.ts | 42 ++++++++----
.../tests/session-execution-service.test.ts | 67 +++++++++++++++++++
specs/message-queue-interactions.md | 6 +-
specs/message-queue-interactions.zh.md | 6 +-
9 files changed, 150 insertions(+), 24 deletions(-)
diff --git a/.agents/docs/rpc-loro-streams-rpc.md b/.agents/docs/rpc-loro-streams-rpc.md
index 352674d16..5a4fed109 100644
--- a/.agents/docs/rpc-loro-streams-rpc.md
+++ b/.agents/docs/rpc-loro-streams-rpc.md
@@ -22,9 +22,11 @@ been removed.
`session/queue-steer` is an identity-based control operation, not queue reordering. Its
request names both the expected active turn and exact queued item, and callers require the
-negotiated `queueItemSteer` protocol capability. The CLI consumes the item only when its
-editing lease is inactive, then preserves native ACP Steer when acknowledged or cancels the
-expected turn for ordinary follow-up dispatch. Missing, editing, and stale targets do neither.
+negotiated `queueItemSteer` protocol capability. The CLI accepts the item only when its
+editing lease is inactive, then preserves native ACP Steer when acknowledged or creates an
+ordinary follow-up before cancelling the expected turn. The ordinary path retains the queue
+row until history and its activation pointer are durable. Missing, editing, and stale targets
+do neither.
Before a remote renderer writes this control request, it fails closed against its authenticated
`machines:listVisibleMachines` snapshot. The retained request contains no requester identity:
the target daemon cannot authenticate such a claim and must not grant its owner fast path from it.
diff --git a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
index 0cfd3baa9..ece904bbe 100644
--- a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
+++ b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
@@ -34,7 +34,9 @@ the selected identity is missing.
- Let the daemon choose the execution mechanism after validating both identities and the
target's editing lease. With acknowledged native ACP Steer, it atomically consumes the row
as `pending_apply` and enters the existing `steerPrompt` handoff. Without native Steer, it
- consumes the row as an ordinary pending turn and cancels only the expected active turn.
+ writes the row as an ordinary pending turn, publishes its activation pointer, removes the
+ queue row only after both writes succeed, then cancels only the expected active turn. A
+ partial publication retains the row as a retry marker and reuses the existing history ID.
- Retain mixed-version behavior without reintroducing reorder-then-cancel. An older daemon
with an authoritative acknowledged-Steer capability uses the legacy native path. Other
older daemons retain only the established queue-head interrupt; later-row Steer controls
@@ -64,8 +66,8 @@ become accidental drag starters.
- Queue component tests cover later-row Steer, old-daemon head-only disabling, authoritative
legacy native selection, and the drag activator boundary.
- CLI service and Session Doc tests cover exact C consumption, native `steerPrompt`, exact
- cancellation, missing and active-edit rejection, cancellation failure, and response-loss
- retries.
+ cancellation, missing and active-edit rejection, activation-publication failure,
+ cancellation failure, and response-loss retries.
- Machine RPC and protocol-capability tests cover the queue/turn identities, rejection of a
requester identity claim, source authorization, and mixed-version negotiation.
- Component tests use synthetic pointer state. Physical touch dragging and a full
diff --git a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
index ad8977d20..bf187588f 100644
--- a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
@@ -26,7 +26,8 @@ Translation: current
无法认证 workspace stream 写入者声称的身份。同机 local IPC 仍是可信的本地控制路径。
- Daemon 确认两个 ID 及目标 editing lease 后决定执行机制。支持 acknowledged native ACP
Steer 时，原子消费目标行为 `pending_apply`，并进入既有 `steerPrompt` handoff；否则消费为
- 普通 pending turn，再只取消预期活动 turn。
+ 普通 pending turn，发布 activation pointer，并仅在两项写入都成功后删除 queue row，再只
+ 取消预期活动 turn。部分发布失败时保留 row 作为重试标记，并复用已有 history ID。
- 混合版本兼容不得恢复“先重排后取消”。旧 daemon 若 authoritative capability 声明支持
acknowledged Steer，则使用旧 native 路径；其他旧 daemon 只保留既有队首 interrupt，后续行
“引导”禁用并提示升级。
@@ -50,7 +51,7 @@ native steer，因为 `steerPrompt` 注入当前 prompt，而 cancel-and-dispatc
- 队列组件测试覆盖后续行引导、旧 daemon 仅启用队首、authoritative legacy native 选择，以及
拖动区域边界。
- CLI service 与 Session Doc 测试覆盖精确消费 C、native `steerPrompt`、精确取消、目标缺失、
- editing lease、取消失败及响应丢失重试。
+ editing lease、activation 发布失败、取消失败及响应丢失重试。
- Machine RPC 与 protocol capability 测试覆盖队列／turn 两个 ID、拒绝请求者身份声明、来源
授权以及混合版本协商。
- 组件测试使用合成指针状态；未验证物理触摸拖动和完整的 Provider-backed steer 流程。
diff --git a/apps/cli/src/lib/loro/AGENTS.md b/apps/cli/src/lib/loro/AGENTS.md
index 46947501b..f4fddf05a 100644
--- a/apps/cli/src/lib/loro/AGENTS.md
+++ b/apps/cli/src/lib/loro/AGENTS.md
@@ -49,7 +49,8 @@ Rules:
fork targets).
The dispatch watcher's contract, "session metadata is the activation index", is
-documented in `../../session/AGENTS.md` and applies to any module enumerating rooms.
+documented in `../../session/AGENTS.md`. Queue promotion retains its row until history
+and that metadata activation are durable; the rule also applies to room enumeration.
## Shared ACP runtime config contains no secrets
diff --git a/apps/cli/src/lib/loro/doc-user-turn.test.ts b/apps/cli/src/lib/loro/doc-user-turn.test.ts
index 3a749e000..00a036fbe 100644
--- a/apps/cli/src/lib/loro/doc-user-turn.test.ts
+++ b/apps/cli/src/lib/loro/doc-user-turn.test.ts
@@ -63,7 +63,7 @@ const createUserTurn = (id: string): SessionHistoryInput => ({
});
describe('SessionDocument.consumeMessageQueueItemAsUserTurn', () => {
- it('atomically consumes the named later row without reordering the survivors', async () => {
+ it('consumes the named later row after activation without reordering the survivors', async () => {
const upsertDocMeta = vi.fn(async () => {});
const { doc } = createSessionDocument({ upsertDocMeta });
const queue = await seedMessageQueue(
@@ -85,6 +85,33 @@ describe('SessionDocument.consumeMessageQueueItemAsUserTurn', () => {
expect(upsertDocMeta).toHaveBeenCalledWith(doc.roomId, { latestUserMsgId: 'user:C' });
});
+ it('retains the queue row and resumes publication without duplicating history', async () => {
+ const upsertDocMeta = vi
+ .fn<() => Promise>()
+ .mockRejectedValueOnce(new Error('metadata unavailable'))
+ .mockResolvedValue(undefined);
+ const { doc } = createSessionDocument({ upsertDocMeta });
+ const [target] = await seedMessageQueue(doc, [
+ {
+ task: 'task C',
+ timestamp: '2026-09-13T00:00:00.000Z',
+ },
+ ]);
+
+ await expect(
+ doc.consumeMessageQueueItemAsUserTurn(target!.$cid, () => createUserTurn('user:C'))
+ ).rejects.toThrow('metadata unavailable');
+ expect((await doc.sessionData.history.readAll()).map((entry) => entry.id)).toEqual(['user:C']);
+ expect((await doc.getMessageQueue()).map((item) => item.task)).toEqual(['task C']);
+
+ await expect(
+ doc.consumeMessageQueueItemAsUserTurn(target!.$cid, () => createUserTurn('user:C'))
+ ).resolves.toMatchObject({ type: 'consumed', entry: { id: 'user:C' } });
+ expect((await doc.sessionData.history.readAll()).map((entry) => entry.id)).toEqual(['user:C']);
+ expect(await doc.getMessageQueue()).toEqual([]);
+ expect(upsertDocMeta).toHaveBeenCalledTimes(2);
+ });
+
it('does not write history or a dispatch pointer when the identity is absent', async () => {
const upsertDocMeta = vi.fn(async () => {});
const { doc } = createSessionDocument({ upsertDocMeta });
diff --git a/apps/cli/src/lib/loro/doc.ts b/apps/cli/src/lib/loro/doc.ts
index e83a436b0..90ac52ba6 100644
--- a/apps/cli/src/lib/loro/doc.ts
+++ b/apps/cli/src/lib/loro/doc.ts
@@ -2789,12 +2789,13 @@ export class SessionDocument implements LoroDocument {
const queue = (prev.mq ?? []) as MessageQueueItem[];
const item = queue.find((candidate) => candidate.$cid === cid);
@@ -2836,20 +2838,36 @@ export class SessionDocument implements LoroDocument candidate.$cid !== cid);
- outcome.value = { type: 'consumed', entry };
+ const existing = this.sessionData.writer.read(entry.id);
+ if (existing) {
+ const status = resolveSessionHistoryStatus(existing);
+ if (
+ !publishDispatch ||
+ existing.role !== 'user' ||
+ (status !== 'pending' && status !== 'seen')
+ ) {
+ outcome.value = { type: 'invalid' };
+ return prev;
+ }
+ // A previous ordinary consume may have committed history before metadata
+ // publication failed. Reuse that durable turn instead of appending it twice.
+ outcome.value = { type: 'consumed', entry: existing as SessionHistoryInput };
+ } else {
+ this.sessionData.writer.append(entry as SessionHistory);
+ outcome.value = { type: 'consumed', entry };
+ }
+ if (!publishDispatch) {
+ // @ts-ignore - mirror state is writable inside setState.
+ prev.mq = queue.filter((candidate) => candidate.$cid !== cid);
+ }
return prev;
});
- if (outcome.value.type === 'consumed' && options.publishDispatch !== false) {
+ if (outcome.value.type === 'consumed' && publishDispatch) {
await this.repo.upsertDocMeta(this.roomId, {
latestUserMsgId: outcome.value.entry.id,
} satisfies Partial);
+ await this.removeMessageQueueItem(cid);
}
return outcome.value;
}
diff --git a/apps/cli/tests/session-execution-service.test.ts b/apps/cli/tests/session-execution-service.test.ts
index 977f07c4c..5a1c7e5f8 100644
--- a/apps/cli/tests/session-execution-service.test.ts
+++ b/apps/cli/tests/session-execution-service.test.ts
@@ -420,6 +420,73 @@ describe('SessionExecutionService', () => {
).toBe(runtime);
});
+ it('keeps the active turn running when queue activation publication fails and allows retry', async () => {
+ const sessionId = 'session-queue-steer-publication-failed' as SessionId;
+ const activeTurnId = 'assistant:active';
+ const entry = {
+ id: 'user:C',
+ role: 'user' as const,
+ userId: 'owner-user',
+ timestamp: '2026-09-13T00:00:00.000Z',
+ items: [{ type: 'text' as const, text: 'task C' }],
+ status: 'pending' as const,
+ read: false,
+ inputConfig: { prompt: 'task C' },
+ };
+ const consumeMessageQueueItemAsUserTurn = vi
+ .fn()
+ .mockRejectedValueOnce(new Error('metadata unavailable'))
+ .mockResolvedValue({ type: 'consumed' as const, entry });
+ const sessionDoc = {
+ getMetaState: vi.fn(async () => ({ id: sessionId })),
+ consumeMessageQueueItemAsUserTurn,
+ };
+ const service = new SessionExecutionService(
+ createBaseDeps({
+ workspaceDocument: {
+ getOrCreateSessionDoc: vi.fn(async () => sessionDoc),
+ } as unknown as LoroDocumentManager,
+ })
+ );
+ const runtime = {
+ sessionId,
+ turnId: activeTurnId,
+ userTurnId: 'active',
+ session: {},
+ promptInFlight: true,
+ cancelRequested: false,
+ };
+ (
+ service as unknown as { turnRuntimeBySession: Map }
+ ).turnRuntimeBySession.set(sessionId, runtime);
+ const cancel = vi.spyOn(service, 'cancelSession').mockResolvedValue({ success: true });
+ const request = {
+ sessionId,
+ expectedTurnId: activeTurnId,
+ queueItemId: 'C',
+ };
+
+ await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
+ accepted: false,
+ disposition: 'error',
+ error: 'metadata unavailable',
+ });
+ expect(cancel).not.toHaveBeenCalled();
+ expect(
+ (
+ service as unknown as { turnRuntimeBySession: Map }
+ ).turnRuntimeBySession.get(sessionId)
+ ).toBe(runtime);
+
+ await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
+ accepted: true,
+ disposition: 'accepted',
+ userTurnId: 'user:C',
+ });
+ expect(consumeMessageQueueItemAsUserTurn).toHaveBeenCalledTimes(2);
+ expect(cancel).toHaveBeenCalledOnce();
+ });
+
it('keeps the active turn and queue row while the target editing lease is active', async () => {
const sessionId = 'session-queue-steer-editing' as SessionId;
const activeTurnId = 'assistant:active';
diff --git a/specs/message-queue-interactions.md b/specs/message-queue-interactions.md
index d2f60556f..31040ca14 100644
--- a/specs/message-queue-interactions.md
+++ b/specs/message-queue-interactions.md
@@ -29,7 +29,7 @@ the queue by hand.
| Active daemon/runtime | Steer behavior |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Exact-item protocol and acknowledged native ACP Steer | Atomically consume the selected row as `pending_apply`, then inject it into the current prompt through `steerPrompt`. |
- | Exact-item protocol without native ACP Steer | Atomically consume the selected row as the next user turn, then stop only the expected turn. |
+ | Exact-item protocol without native ACP Steer | Persist and activate the selected row as the next user turn, remove it from the queue, then stop only the expected turn. |
| Older daemon with authoritative acknowledged native ACP Steer | Preserve the legacy native Steer path. |
| Older daemon without acknowledged native ACP Steer | Keep the established queue-head interrupt behavior; disable Steer on later rows and require a daemon update for exact selection. |
@@ -42,6 +42,10 @@ the queue by hand.
authenticate a caller-supplied member ID, and the target daemon must not use one for an owner
fast path. Same-host local IPC is already the trusted local control boundary.
+ For cancel-and-dispatch Steer, the selected queue row is the durable retry marker: append
+ history first, publish `latestUserMsgId`, and remove the row only after both writes succeed.
+ A retry after partial publication reuses the existing turn ID rather than duplicating history.
+
- A stale or conflicting exact Steer selection is a failed no-op. If the selected queue
identity is missing, its editing lease is active, or the expected turn no longer owns
execution, the daemon must not submit native Steer or stop any turn. The renderer waits for
diff --git a/specs/message-queue-interactions.zh.md b/specs/message-queue-interactions.zh.md
index 5f5349244..233486202 100644
--- a/specs/message-queue-interactions.zh.md
+++ b/specs/message-queue-interactions.zh.md
@@ -24,7 +24,7 @@ Translation: current
| 当前 daemon/runtime | 引导行为 |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| 支持精确队列项协议，且支持 acknowledged native ACP Steer | 原子消费目标行为 `pending_apply`，再通过 `steerPrompt` 注入当前 prompt。 |
- | 支持精确队列项协议，但不支持 native ACP Steer | 原子消费目标行为下一个用户 turn，再只停止预期 turn。 |
+ | 支持精确队列项协议，但不支持 native ACP Steer | 将目标行持久化并激活为下一用户 turn，从队列删除后再只停止预期 turn。 |
| 旧 daemon，但 authoritative capability 声明支持 acknowledged native ACP Steer | 保留旧版真正 native Steer 路径。 |
| 旧 daemon，且不支持 acknowledged native ACP Steer | 仅保留既有队首 interrupt 行为；禁用后续行“引导”，并要求升级 daemon 才能精确选择。 |
@@ -36,6 +36,10 @@ Translation: current
声称的成员 ID，目标 daemon 也不得用它命中 owner fast path。同机 local IPC 已是可信的
本地控制边界。
+ 对 cancel-and-dispatch Steer，所选 queue row 是持久重试标记：先追加 history，再发布
+ `latestUserMsgId`，且仅在两项写入都成功后删除 row。部分发布后的重试应复用已有 turn ID，
+ 不得重复追加 history。
+
- 过期或冲突的精确“引导”选择必须失败且无副作用。所选 ID 已不存在、编辑 lease 仍有效，或
预期 turn 已不再拥有执行权时，daemon 不得提交 native Steer，也不得停止任何 turn。Renderer
等待确认，不自行移除队列项或为精确协议写历史。
From b0ba37d55016770c38dbe4b53ab0fbd6968a2827 Mon Sep 17 00:00:00 2001
From: wibus-wee <62133302+wibus-wee@users.noreply.github.com>
Date: Mon, 14 Sep 2026 12:57:42 +0800
Subject: [PATCH 06/15] fix: preserve authenticated native steer identity
Model: gpt-5
---
.agents/docs/rpc-loro-streams-rpc.md | 2 +
.../2026-09-13-queue-steer-controls.md | 8 ++-
.../2026-09-13-queue-steer-controls.zh.md | 6 +-
.../src/session/session-execution-service.ts | 20 ++++--
.../tests/session-execution-service.test.ts | 65 +++++++++++++++++--
specs/message-queue-interactions.md | 4 ++
specs/message-queue-interactions.zh.md | 5 +-
7 files changed, 94 insertions(+), 16 deletions(-)
diff --git a/.agents/docs/rpc-loro-streams-rpc.md b/.agents/docs/rpc-loro-streams-rpc.md
index 5a4fed109..c5df93c98 100644
--- a/.agents/docs/rpc-loro-streams-rpc.md
+++ b/.agents/docs/rpc-loro-streams-rpc.md
@@ -30,6 +30,8 @@ do neither.
Before a remote renderer writes this control request, it fails closed against its authenticated
`machines:listVisibleMachines` snapshot. The retained request contains no requester identity:
the target daemon cannot authenticate such a claim and must not grant its owner fast path from it.
+Native queue Steer instead inherits the frozen requester from the authenticated active invocation;
+it fails before consumption when that identity is unavailable and never trusts the queue row.
## Remote lifecycle acknowledgements
diff --git a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
index ece904bbe..8dd90b735 100644
--- a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
+++ b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
@@ -33,7 +33,9 @@ the selected identity is missing.
trusted local control path.
- Let the daemon choose the execution mechanism after validating both identities and the
target's editing lease. With acknowledged native ACP Steer, it atomically consumes the row
- as `pending_apply` and enters the existing `steerPrompt` handoff. Without native Steer, it
+ as `pending_apply` and enters the existing `steerPrompt` handoff. Native Steer derives its
+ requester from the authenticated active invocation, never the shared queue row, and fails
+ before consumption if that frozen identity is absent. Without native Steer, it
writes the row as an ordinary pending turn, publishes its activation pointer, removes the
queue row only after both writes succeed, then cancels only the expected active turn. A
partial publication retains the row as a retry marker and reuses the existing history ID.
@@ -66,8 +68,8 @@ become accidental drag starters.
- Queue component tests cover later-row Steer, old-daemon head-only disabling, authoritative
legacy native selection, and the drag activator boundary.
- CLI service and Session Doc tests cover exact C consumption, native `steerPrompt`, exact
- cancellation, missing and active-edit rejection, activation-publication failure,
- cancellation failure, and response-loss retries.
+ cancellation, forged and missing native identity, missing and active-edit rejection,
+ activation-publication failure, cancellation failure, and response-loss retries.
- Machine RPC and protocol-capability tests cover the queue/turn identities, rejection of a
requester identity claim, source authorization, and mixed-version negotiation.
- Component tests use synthetic pointer state. Physical touch dragging and a full
diff --git a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
index bf187588f..fdb157572 100644
--- a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
@@ -25,7 +25,9 @@ Translation: current
授权；快照尚不可用或不包含目标时应 fail closed。RPC 不携带请求者身份，因为目标 daemon
无法认证 workspace stream 写入者声称的身份。同机 local IPC 仍是可信的本地控制路径。
- Daemon 确认两个 ID 及目标 editing lease 后决定执行机制。支持 acknowledged native ACP
- Steer 时，原子消费目标行为 `pending_apply`，并进入既有 `steerPrompt` handoff；否则消费为
+ Steer 时，原子消费目标行为 `pending_apply`，并进入既有 `steerPrompt` handoff。Native Steer
+ 的 requester 必须来自已认证的活动 invocation，绝不信任共享 queue row；若缺少该冻结身份，
+ 应在消费前失败。否则消费为
普通 pending turn，发布 activation pointer，并仅在两项写入都成功后删除 queue row，再只
取消预期活动 turn。部分发布失败时保留 row 作为重试标记，并复用已有 history ID。
- 混合版本兼容不得恢复“先重排后取消”。旧 daemon 若 authoritative capability 声明支持
@@ -51,7 +53,7 @@ native steer，因为 `steerPrompt` 注入当前 prompt，而 cancel-and-dispatc
- 队列组件测试覆盖后续行引导、旧 daemon 仅启用队首、authoritative legacy native 选择，以及
拖动区域边界。
- CLI service 与 Session Doc 测试覆盖精确消费 C、native `steerPrompt`、精确取消、目标缺失、
- editing lease、activation 发布失败、取消失败及响应丢失重试。
+ 伪造或缺失的 native identity、editing lease、activation 发布失败、取消失败及响应丢失重试。
- Machine RPC 与 protocol capability 测试覆盖队列／turn 两个 ID、拒绝请求者身份声明、来源
授权以及混合版本协商。
- 组件测试使用合成指针状态；未验证物理触摸拖动和完整的 Provider-backed steer 流程。
diff --git a/apps/cli/src/session/session-execution-service.ts b/apps/cli/src/session/session-execution-service.ts
index adf9af148..b6865eac0 100644
--- a/apps/cli/src/session/session-execution-service.ts
+++ b/apps/cli/src/session/session-execution-service.ts
@@ -1477,16 +1477,25 @@ export class SessionExecutionService {
runtime.session.acpSessionId &&
agentClient.getAcknowledgedSteerCapability()
);
+ const authenticatedRequesterUserId = runtime.invocation?.requesterUserId?.trim() ?? '';
+ if (useNativeSteer && !authenticatedRequesterUserId) {
+ return respond('error', {
+ error: 'Active invocation identity is unavailable for native queue Steer.',
+ });
+ }
// Queue order and immediate steering are separate mutations. Consume the
// selected identity directly; A/B keep their relative order when C wins.
// Native steer owns dispatch publication through its handoff path.
const consumed = await sessionDoc.consumeMessageQueueItemAsUserTurn(
options.queueItemId,
- (item) =>
- buildQueuedMessageUserTurn(item, meta, {
+ (item) => {
+ const queuedTurn = buildQueuedMessageUserTurn(item, meta, {
status: useNativeSteer ? 'pending_apply' : 'pending',
- }),
+ });
+ if (!queuedTurn || !useNativeSteer) return queuedTurn;
+ return { ...queuedTurn, userId: authenticatedRequesterUserId };
+ },
{ publishDispatch: !useNativeSteer }
);
if (consumed.type === 'missing') {
@@ -1503,9 +1512,8 @@ export class SessionExecutionService {
if (useNativeSteer) {
const inputConfig = normalizeSessionTurnInputConfig(entry.inputConfig);
- const userId = entry.userId?.trim();
const timestamp = entry.timestamp?.trim();
- if (!inputConfig || !userId || !timestamp) {
+ if (!inputConfig || !timestamp) {
return finishConsumed(
respond('invalid-queue-item', {
userTurnId: entry.id,
@@ -1517,7 +1525,7 @@ export class SessionExecutionService {
sessionId: options.sessionId,
expectedTurnId: options.expectedTurnId,
userTurnId: entry.id,
- userId,
+ userId: authenticatedRequesterUserId,
timestamp,
inputConfig,
});
diff --git a/apps/cli/tests/session-execution-service.test.ts b/apps/cli/tests/session-execution-service.test.ts
index 5a1c7e5f8..1d5e67942 100644
--- a/apps/cli/tests/session-execution-service.test.ts
+++ b/apps/cli/tests/session-execution-service.test.ts
@@ -592,6 +592,62 @@ describe('SessionExecutionService', () => {
expect(cancel).toHaveBeenCalledOnce();
});
+ it('rejects native queued Steer before consume when active requester identity is unavailable', async () => {
+ const sessionId = 'session-queue-steer-no-identity' as SessionId;
+ const activeTurnId = 'assistant:active';
+ const steerPrompt = vi.fn();
+ const consumeMessageQueueItemAsUserTurn = vi.fn();
+ const sessionDoc = {
+ getMetaState: vi.fn(async () => ({ id: sessionId })),
+ consumeMessageQueueItemAsUserTurn,
+ };
+ const service = new SessionExecutionService(
+ createBaseDeps({
+ workspaceDocument: {
+ getOrCreateSessionDoc: vi.fn(async () => sessionDoc),
+ } as unknown as LoroDocumentManager,
+ })
+ );
+ const runtime = {
+ sessionId,
+ turnId: activeTurnId,
+ userTurnId: 'active',
+ session: {
+ agentClient: {
+ getAcknowledgedSteerCapability: vi.fn(() => ({
+ provider: 'claudeCode',
+ appliedNotificationMethod: 'claude/steerApplied',
+ upstreamTurn: 'handoff',
+ configPolicy: 'apply',
+ })),
+ steerPrompt,
+ },
+ acpSessionId: 'acp-steer' as ACPSessionId,
+ },
+ promptInFlight: true,
+ cancelRequested: false,
+ };
+ (
+ service as unknown as { turnRuntimeBySession: Map }
+ ).turnRuntimeBySession.set(sessionId, runtime);
+ const cancel = vi.spyOn(service, 'cancelSession');
+
+ await expect(
+ service.steerQueuedMessage({
+ sessionId,
+ expectedTurnId: activeTurnId,
+ queueItemId: 'C',
+ })
+ ).resolves.toMatchObject({
+ accepted: false,
+ disposition: 'error',
+ error: expect.stringContaining('identity is unavailable'),
+ });
+ expect(consumeMessageQueueItemAsUserTurn).not.toHaveBeenCalled();
+ expect(steerPrompt).not.toHaveBeenCalled();
+ expect(cancel).not.toHaveBeenCalled();
+ });
+
it('advances one session owner through consecutive prompt handoffs', async () => {
const steerPrompt = vi.fn(() => ({
completion: new Promise(() => {}),
@@ -613,7 +669,7 @@ describe('SessionExecutionService', () => {
const queuedItem: MessageQueueItem = {
$cid: 'queue-user-2',
task: 'change direction',
- userId: 'user-1',
+ userId: 'forged-owner',
userTurnId: 'user-2',
timestamp: '2026-07-11T00:00:00.000Z',
acpSessionConfig: { prompt: 'change direction' },
@@ -631,6 +687,7 @@ describe('SessionExecutionService', () => {
expect(cid).toBe(queuedItem.$cid);
const entry = buildEntry(queuedItem);
if (!entry) return { type: 'invalid' as const };
+ expect(entry.userId).toBe('authenticated-user');
return { type: 'consumed' as const, entry };
}
),
@@ -678,7 +735,7 @@ describe('SessionExecutionService', () => {
promptInFlight: true,
invocation: {
sourceTurnId: 'user-1',
- requesterUserId: 'user-1',
+ requesterUserId: 'authenticated-user',
inputConfig: { prompt: 'initial prompt' },
},
activePromptRun: initialPromptRun,
@@ -717,12 +774,12 @@ describe('SessionExecutionService', () => {
expect(runtime.turnId).toBe('assistant:user-2');
expect(runtime.userTurnId).toBe('user-2');
expect(runtime.invocation).toMatchObject({
- requesterUserId: 'user-1',
+ requesterUserId: 'authenticated-user',
sourceTurnId: 'user-2',
inputConfig: { prompt: 'change direction' },
});
expect(service.getActiveInvocationContext(sessionId)).toMatchObject({
- requesterUserId: 'user-1',
+ requesterUserId: 'authenticated-user',
sourceTurnId: 'user-2',
inputConfig: { prompt: 'change direction' },
});
diff --git a/specs/message-queue-interactions.md b/specs/message-queue-interactions.md
index 31040ca14..0a2df6f7c 100644
--- a/specs/message-queue-interactions.md
+++ b/specs/message-queue-interactions.md
@@ -42,6 +42,10 @@ the queue by hand.
authenticate a caller-supplied member ID, and the target daemon must not use one for an owner
fast path. Same-host local IPC is already the trusted local control boundary.
+ Native exact Steer must derive its requester identity from the authenticated active
+ invocation, never from the shared queue row. If that frozen identity is unavailable, the
+ daemon fails before consuming the row, submitting to the provider, or stopping the turn.
+
For cancel-and-dispatch Steer, the selected queue row is the durable retry marker: append
history first, publish `latestUserMsgId`, and remove the row only after both writes succeed.
A retry after partial publication reuses the existing turn ID rather than duplicating history.
diff --git a/specs/message-queue-interactions.zh.md b/specs/message-queue-interactions.zh.md
index 233486202..803ae1d10 100644
--- a/specs/message-queue-interactions.zh.md
+++ b/specs/message-queue-interactions.zh.md
@@ -24,7 +24,7 @@ Translation: current
| 当前 daemon/runtime | 引导行为 |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| 支持精确队列项协议，且支持 acknowledged native ACP Steer | 原子消费目标行为 `pending_apply`，再通过 `steerPrompt` 注入当前 prompt。 |
- | 支持精确队列项协议，但不支持 native ACP Steer | 将目标行持久化并激活为下一用户 turn，从队列删除后再只停止预期 turn。 |
+ | 支持精确队列项协议，但不支持 native ACP Steer | 将目标行持久化并激活为下一用户 turn，从队列删除后再只停止预期 turn。 |
| 旧 daemon，但 authoritative capability 声明支持 acknowledged native ACP Steer | 保留旧版真正 native Steer 路径。 |
| 旧 daemon，且不支持 acknowledged native ACP Steer | 仅保留既有队首 interrupt 行为；禁用后续行“引导”，并要求升级 daemon 才能精确选择。 |
@@ -36,6 +36,9 @@ Translation: current
声称的成员 ID，目标 daemon 也不得用它命中 owner fast path。同机 local IPC 已是可信的
本地控制边界。
+ Native 精确“引导”的 requester identity 必须来自已认证的活动 invocation，绝不来自共享
+ queue row。若该冻结身份不可用，daemon 必须在消费 row、提交 provider 或停止 turn 之前失败。
+
对 cancel-and-dispatch Steer，所选 queue row 是持久重试标记：先追加 history，再发布
`latestUserMsgId`，且仅在两项写入都成功后删除 row。部分发布后的重试应复用已有 turn ID，
不得重复追加 history。
From ee8c30c9a34bbed6b8144638ac4b1c6dcb25ce93 Mon Sep 17 00:00:00 2001
From: wibus-wee <62133302+wibus-wee@users.noreply.github.com>
Date: Mon, 14 Sep 2026 14:41:44 +0800
Subject: [PATCH 07/15] fix: make native queue steer crash recoverable
Model: gpt-5
---
.../2026-09-13-queue-steer-controls.md | 27 +-
.../2026-09-13-queue-steer-controls.zh.md | 21 +-
apps/cli/src/lib/loro/doc-user-turn.test.ts | 17 +-
apps/cli/src/lib/loro/doc.ts | 13 +-
apps/cli/src/lib/message-handler.ts | 10 +
apps/cli/src/session/AGENTS.md | 7 +-
.../src/session/session-execution-service.ts | 534 ++++++++++++++++--
...ession-queue-steer-operation-store.test.ts | 73 +++
.../session-queue-steer-operation-store.ts | 160 ++++++
.../tests/session-execution-service.test.ts | 397 +++++++++++++
specs/message-queue-interactions.md | 30 +-
specs/message-queue-interactions.zh.md | 25 +-
12 files changed, 1239 insertions(+), 75 deletions(-)
create mode 100644 apps/cli/src/session/session-queue-steer-operation-store.test.ts
create mode 100644 apps/cli/src/session/session-queue-steer-operation-store.ts
diff --git a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
index 8dd90b735..861dcd04d 100644
--- a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
+++ b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md
@@ -32,8 +32,9 @@ the selected identity is missing.
authenticate an identity claimed by a workspace stream writer. Same-host local IPC remains the
trusted local control path.
- Let the daemon choose the execution mechanism after validating both identities and the
- target's editing lease. With acknowledged native ACP Steer, it atomically consumes the row
- as `pending_apply` and enters the existing `steerPrompt` handoff. Native Steer derives its
+ target's editing lease. With acknowledged native ACP Steer, it records a durable phase marker,
+ retains the selected row while history is `pending_apply`, and enters the existing `steerPrompt`
+ handoff. Native Steer derives its
requester from the authenticated active invocation, never the shared queue row, and fails
before consumption if that frozen identity is absent. Without native Steer, it
writes the row as an ordinary pending turn, publishes its activation pointer, removes the
@@ -43,9 +44,19 @@ the selected identity is missing.
with an authoritative acknowledged-Steer capability uses the legacy native path. Other
older daemons retain only the established queue-head interrupt; later-row Steer controls
are disabled with an upgrade explanation.
-- Keep a bounded daemon receipt for each completed exact operation key. A response-loss retry
- returns the same result instead of consuming or cancelling twice. A cancellation failure
- after consumption leaves one durable follow-up and is also returned idempotently.
+- Keep a bounded in-memory daemon receipt for each completed exact operation key, and retain the
+ latest native result in its durable saga marker. A response-loss retry, including an immediate
+ retry after daemon restart for native Steer, returns the same result. A cancellation failure
+ after consumption leaves one durable follow-up and is also returned idempotently. Native
+ rejection receipts are written only after fallback publication and row cleanup succeed.
+- Recover native handoff as a saga with `reserved`, write-ahead `submitting`, provider
+ `acknowledged`, locally committed `applied`, and `fallback` phases in a machine-local,
+ daemon-owned marker. Shared Session metadata is not trusted as a recovery authority.
+ `reserved` work that reached history and `fallback` are safe to convert to exact ordinary
+ dispatch; a pre-history reservation leaves the row queued. `submitting` is indeterminate and
+ `acknowledged` may have side effects, so both fail visibly without replay after restart.
+ `applied` proves the local handoff and retains an accepted receipt. The row stays present until
+ the durable result is complete.
- Make the leading number and message body a single pointer and keyboard drag activator.
Keep action buttons outside it, and disable it while the row editor owns interaction.
@@ -57,6 +68,9 @@ the selected row, causing Stop to target the current turn without any message to
Renderer-side history materialization remains only for old-daemon native compatibility; it
cannot provide exact-item atomicity. Removing native steering was rejected because
`steerPrompt` injects into the current prompt, while cancel-and-dispatch starts a new turn.
+Treating the provider call and CRDT writes as atomic was rejected because ACP exposes neither
+an idempotent caller-owned submission key nor a delivery query; replaying an indeterminate call
+could execute tools twice.
Making the complete row draggable was also rejected because Steer, edit, and remove would
become accidental drag starters.
@@ -70,6 +84,9 @@ become accidental drag starters.
- CLI service and Session Doc tests cover exact C consumption, native `steerPrompt`, exact
cancellation, forged and missing native identity, missing and active-edit rejection,
activation-publication failure, cancellation failure, and response-loss retries.
+- Crash/recovery tests cover retry after failed fallback publication, exact recovery from
+ `reserved`, non-replay of `submitting`/`acknowledged` provider calls, `applied` cleanup, and
+ durable receipt replay after restart.
- Machine RPC and protocol-capability tests cover the queue/turn identities, rejection of a
requester identity claim, source authorization, and mixed-version negotiation.
- Component tests use synthetic pointer state. Physical touch dragging and a full
diff --git a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
index fdb157572..81273f949 100644
--- a/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md
@@ -25,7 +25,8 @@ Translation: current
授权；快照尚不可用或不包含目标时应 fail closed。RPC 不携带请求者身份，因为目标 daemon
无法认证 workspace stream 写入者声称的身份。同机 local IPC 仍是可信的本地控制路径。
- Daemon 确认两个 ID 及目标 editing lease 后决定执行机制。支持 acknowledged native ACP
- Steer 时，原子消费目标行为 `pending_apply`，并进入既有 `steerPrompt` handoff。Native Steer
+ Steer 时，先记录持久阶段标记，在 history 为 `pending_apply` 期间保留目标 row，再进入既有
+ `steerPrompt` handoff。Native Steer
的 requester 必须来自已认证的活动 invocation，绝不信任共享 queue row；若缺少该冻结身份，
应在消费前失败。否则消费为
普通 pending turn，发布 activation pointer，并仅在两项写入都成功后删除 queue row，再只
@@ -33,8 +34,16 @@ Translation: current
- 混合版本兼容不得恢复“先重排后取消”。旧 daemon 若 authoritative capability 声明支持
acknowledged Steer，则使用旧 native 路径；其他旧 daemon 只保留既有队首 interrupt，后续行
“引导”禁用并提示升级。
-- Daemon 为已完成的精确操作 key 保留有界 receipt。响应丢失后的重试返回相同结果，不再次
- 消费或取消。消费后取消失败也只留下一个持久 follow-up，并以幂等方式返回。
+- Daemon 为已完成的精确操作 key 保留有界内存 receipt，并在 native saga marker 中保留最近一次
+ 持久结果。响应丢失后的重试（包括 native Steer 后 daemon 重启）返回相同结果，不再次消费或
+ 取消。消费后取消失败也只留下一个持久 follow-up。Native 拒绝只有在 fallback activation 和
+ row 清理持久成功后才完成 receipt。
+- Native handoff 以 machine-local、由 daemon 持有的 marker 中的 `reserved`、write-ahead
+ `submitting`、provider `acknowledged`、本地已提交 `applied`、`fallback` 阶段组成 saga；共享
+ Session metadata 不作为恢复权威。已进入 history 的
+ `reserved` 与 `fallback` 可安全恢复为精确普通 dispatch；写 history 前中断则保留 row。
+ `submitting` 结果不确定，`acknowledged` 可能已有 side effect，重启后两者均落成可见失败且不
+ 重放。`applied` 证明本地 handoff 已完成并恢复 accepted 回执。持久结果完成前始终保留目标 row。
- 左侧序号和消息正文合并为一个支持鼠标及键盘的拖动区域。操作按钮保持在区域外；编辑器
接管交互时禁用该行拖动。
@@ -44,7 +53,9 @@ Translation: current
行时，重排仍可能 resolve，进而在没有可提升消息的情况下错误 Stop 当前 turn。也没有让
Renderer 写历史仅保留给旧 daemon 的 native 兼容路径；它无法提供精确队列项原子性。没有删除
native steer，因为 `steerPrompt` 注入当前 prompt，而 cancel-and-dispatch 会开启新 turn，两者
-语义不同。没有让整行都可拖动，因为那会使“引导”、“编辑”和“移除”成为意外拖动起点。
+语义不同。也不能把 provider 调用和 CRDT 写入宣称为原子操作：ACP 既没有 caller-owned 幂等
+提交键，也没有交付查询，重放结果不确定的请求可能重复执行工具。没有让整行都可拖动，因为
+那会使“引导”、“编辑”和“移除”成为意外拖动起点。
## 验证与边界
@@ -54,6 +65,8 @@ native steer，因为 `steerPrompt` 注入当前 prompt，而 cancel-and-dispatc
拖动区域边界。
- CLI service 与 Session Doc 测试覆盖精确消费 C、native `steerPrompt`、精确取消、目标缺失、
伪造或缺失的 native identity、editing lease、activation 发布失败、取消失败及响应丢失重试。
+- 崩溃恢复测试覆盖 fallback 发布失败后的重试、`reserved` 精确恢复、`submitting`／
+ `acknowledged` provider 调用不重放、`applied` 清理，以及重启后的持久回执重放。
- Machine RPC 与 protocol capability 测试覆盖队列／turn 两个 ID、拒绝请求者身份声明、来源
授权以及混合版本协商。
- 组件测试使用合成指针状态；未验证物理触摸拖动和完整的 Provider-backed steer 流程。
diff --git a/apps/cli/src/lib/loro/doc-user-turn.test.ts b/apps/cli/src/lib/loro/doc-user-turn.test.ts
index 00a036fbe..c9fc6fda7 100644
--- a/apps/cli/src/lib/loro/doc-user-turn.test.ts
+++ b/apps/cli/src/lib/loro/doc-user-turn.test.ts
@@ -163,12 +163,21 @@ describe('SessionDocument.consumeMessageQueueItemAsUserTurn', () => {
const target = queue[0]!;
await expect(
- doc.consumeMessageQueueItemAsUserTurn(target.$cid, () => createUserTurn('user:C'), {
- publishDispatch: false,
- })
+ doc.consumeMessageQueueItemAsUserTurn(
+ target.$cid,
+ () => ({ ...createUserTurn('user:C'), status: 'pending_apply' }),
+ { publishDispatch: false }
+ )
+ ).resolves.toMatchObject({ type: 'consumed', entry: { id: 'user:C' } });
+ await expect(
+ doc.consumeMessageQueueItemAsUserTurn(
+ target.$cid,
+ () => ({ ...createUserTurn('user:C'), status: 'pending_apply' }),
+ { publishDispatch: false }
+ )
).resolves.toMatchObject({ type: 'consumed', entry: { id: 'user:C' } });
expect((await doc.sessionData.history.readAll()).map((entry) => entry.id)).toEqual(['user:C']);
- expect(await doc.getMessageQueue()).toEqual([]);
+ expect((await doc.getMessageQueue()).map((item) => item.task)).toEqual(['task C']);
expect(upsertDocMeta).not.toHaveBeenCalled();
});
});
diff --git a/apps/cli/src/lib/loro/doc.ts b/apps/cli/src/lib/loro/doc.ts
index 90ac52ba6..f3b33dca1 100644
--- a/apps/cli/src/lib/loro/doc.ts
+++ b/apps/cli/src/lib/loro/doc.ts
@@ -327,6 +327,7 @@ export type LoroRepoPersistReason =
| 'session-fork-prepare'
| 'session-fork-commit'
| 'session-fork-rollback'
+ | 'queue-steer-commit'
| 'session-edit-and-resend-commit'
| 'session-edit-and-resend-rollback';
@@ -1743,7 +1744,7 @@ const acpRuntimeConfigEqual = (
*/
const EDITING_LEASE_MS = 5 * 60 * 1000;
-const hasActiveMessageQueueEditingLease = (item: MessageQueueItem): boolean => {
+export const hasActiveMessageQueueEditingLease = (item: MessageQueueItem): boolean => {
if (!item.isEditing) return false;
const startedAt = item.editingStartedAt ?? 0;
return getServerNow() - startedAt < EDITING_LEASE_MS;
@@ -2794,8 +2795,7 @@ export class SessionDocument implements LoroDocument candidate.$cid !== cid);
- }
return prev;
});
diff --git a/apps/cli/src/lib/message-handler.ts b/apps/cli/src/lib/message-handler.ts
index a1b62931d..74444cef2 100644
--- a/apps/cli/src/lib/message-handler.ts
+++ b/apps/cli/src/lib/message-handler.ts
@@ -287,6 +287,7 @@ import { SessionDispatchWatcher } from '@/session/session-dispatch-watcher';
import { SessionUserResolver } from '@/session/session-user-resolver';
import { SessionForkService } from '@/session/session-fork-service';
import { createFileSessionForkOperationStore } from '@/session/session-fork-operation-store';
+import { createFileQueueSteerOperationStore } from '@/session/session-queue-steer-operation-store';
import {
SessionEditAndResendService,
type SessionEditAndResendInput,
@@ -2961,6 +2962,10 @@ export class MessageHandler {
machineId: this.machineId,
userId: this.userId,
workspaceId: this.workspaceId,
+ queueSteerOperationStore: createFileQueueSteerOperationStore({
+ workspaceId: this.workspaceId,
+ machineId: this.machineId,
+ }),
preferredBaseBranch: this.preferredBaseBranch,
touchSession: (sessionId) => this.touchSession(sessionId),
startSessionActivePresence: (sessionId, phase) =>
@@ -3411,6 +3416,11 @@ export class MessageHandler {
},
onFatalAuthFailure: (error) => this.onFatalAuthFailure?.(error),
});
+ void this.executionService.recoverPendingQueueSteers().catch((error: unknown) => {
+ this.logger.debug(
+ `[queue-steer] Failed to recover pending operations: ${formatErrorMessage(error)}`
+ );
+ });
this.sessionForkService = new SessionForkService({
workspaceDocument: this.workspaceDocument,
sessionManager: this.sessionManager,
diff --git a/apps/cli/src/session/AGENTS.md b/apps/cli/src/session/AGENTS.md
index f5be54a59..be5f4ddb6 100644
--- a/apps/cli/src/session/AGENTS.md
+++ b/apps/cli/src/session/AGENTS.md
@@ -56,10 +56,9 @@ Contract: specs/session-orchestration.md.
tombstone; CLI dispatch producers keep their own marker policy.
- Ordinary turn execution writes only `processingUserMsgId` and `lastHandledUserMsgId`; no start
or terminal path may read-await-rewrite the other slots.
-- Never submit steer after Stop. A late accepted ACK cancels that exact steer entry without
- transferring ownership, changing dispatch pointers or requeueing it.
- Requeue unaccepted steer via its pointer, not entry status, only before submission or on
- `AgentSteerNotDeliveredError`; skip active or handled entries.
+- Never steer after Stop; late ACK cancels entry. Native queue Steer keeps row + machine-local
+ phase. Restart dispatches reserved/fallback, fails submitting/acknowledged without replay, and
+ receipts applied. Cache after recovery. Requeue unaccepted via pointer; skip active/handled.
- Resume must REOPEN the in-progress assistant entry, clearing
`finished`/`endedAt`/`permissionWaitMs` there only; never write `finished=false` from teardown.
- Keep JSON-RPC/transport matching in `acp-error-classification.ts`: disposed/stale `-32603` is
diff --git a/apps/cli/src/session/session-execution-service.ts b/apps/cli/src/session/session-execution-service.ts
index b6865eac0..3e6e4c0ca 100644
--- a/apps/cli/src/session/session-execution-service.ts
+++ b/apps/cli/src/session/session-execution-service.ts
@@ -34,6 +34,7 @@ import {
type ProjectRef,
resolveBaseBranchPreference,
resolveProjectGitHubRepo,
+ resolveSessionHistoryStatus,
getSessionRoomId,
getServerNow,
SessionCreateRequestValidated,
@@ -107,7 +108,7 @@ import type { SessionActivePresencePhase } from '@/lib/loro/session-active-prese
import type { SessionConfig } from './types';
import type { ISession, SessionManager } from './session-manager';
import type { LoroDocumentManager, SessionDocument } from '@/lib/loro/doc';
-import { subscribeSessionChanges } from '@/lib/loro/doc';
+import { hasActiveMessageQueueEditingLease, subscribeSessionChanges } from '@/lib/loro/doc';
import { buildPrompt, normalizeSessionInputBlocks } from './session-execution-helpers';
import type { MemoryPressureEvictionResult } from '@/lib/session-gc-manager';
import {
@@ -116,6 +117,11 @@ import {
} from './session-dispatch-logic';
import { resolveSessionLaunchConfig } from './session-launch-config-resolver';
import { buildQueuedMessageUserTurn } from './queued-message-turn';
+import {
+ isQueueSteerMarkerOwnedBy,
+ type QueueSteerOperationMarker,
+ type QueueSteerOperationStore,
+} from './session-queue-steer-operation-store';
import type { MachineAccessVerification } from './session-access-retry';
import {
GIT_EXECUTABLE_NOT_FOUND_CODE,
@@ -494,6 +500,7 @@ export type SessionExecutionServiceDeps = {
machineId: MachineId;
userId: string;
workspaceId: WorkspaceId;
+ queueSteerOperationStore: QueueSteerOperationStore;
preferredBaseBranch: string;
touchSession: (sessionId: SessionId) => void;
startSessionActivePresence: (
@@ -728,6 +735,7 @@ type TurnAnalyticsState = {
};
const QUEUE_STEER_RECEIPT_LIMIT = 512;
+type QueueSteerOperation = QueueSteerOperationMarker;
export class SessionExecutionService {
private readonly canceledTurnBySession = new Map();
@@ -782,6 +790,57 @@ export class SessionExecutionService {
return response;
}
+ private async writeQueueSteerOperation(
+ sessionId: SessionId,
+ operation: Omit
+ ): Promise {
+ const durable = {
+ ...operation,
+ workspaceId: this.deps.workspaceId,
+ machineId: this.deps.machineId,
+ sessionId,
+ updatedAt: getServerNow(),
+ } satisfies QueueSteerOperation;
+ await this.deps.queueSteerOperationStore.record(durable);
+ return durable;
+ }
+
+ private async clearQueueSteerOperation(sessionId: SessionId): Promise {
+ await this.deps.queueSteerOperationStore.clear(sessionId);
+ }
+
+ private queueSteerResponseFromOperation(
+ sessionId: SessionId,
+ operation: QueueSteerOperation
+ ): SessionQueueSteerResponse | null {
+ if (!operation.completedAt || !operation.response) return null;
+ return {
+ type: 'session/queue-steer_response',
+ sessionId,
+ queueItemId: operation.queueItemId,
+ accepted: operation.response.disposition === 'accepted',
+ disposition: operation.response.disposition,
+ ...(operation.response.userTurnId ? { userTurnId: operation.response.userTurnId } : {}),
+ ...(operation.response.error ? { error: operation.response.error } : {}),
+ };
+ }
+
+ private async completeQueueSteerOperation(
+ sessionId: SessionId,
+ operation: QueueSteerOperation,
+ response: SessionQueueSteerResponse
+ ): Promise {
+ return await this.writeQueueSteerOperation(sessionId, {
+ ...operation,
+ response: {
+ disposition: response.disposition,
+ ...(response.userTurnId ? { userTurnId: response.userTurnId } : {}),
+ ...(response.error ? { error: response.error } : {}),
+ },
+ completedAt: getServerNow(),
+ });
+ }
+
private createPromptHandoffRun(options: {
turnId: string;
promptPromise: Promise;
@@ -1390,7 +1449,7 @@ export class SessionExecutionService {
// Nothing was submitted, so this guide is still ours to run. Only the
// dispatch pointer is written: the history flip needs the lease we just
// failed to take, and dispatch honors the pointer on its own.
- await this.requeueUndeliveredSteer(options.sessionId, options.userTurnId, {
+ const recovery = await this.requeueUndeliveredSteer(options.sessionId, options.userTurnId, {
canWriteHistory: false,
});
return {
@@ -1398,8 +1457,11 @@ export class SessionExecutionService {
sessionId: options.sessionId,
userTurnId: options.userTurnId,
applied: false,
- disposition: 'busy',
- error: 'The session history is being replaced.',
+ disposition: recovery === 'requeue-failed' ? 'error' : 'busy',
+ error:
+ recovery === 'requeue-failed'
+ ? 'The session history is being replaced and Steer recovery failed.'
+ : 'The session history is being replaced.',
};
}
try {
@@ -1441,18 +1503,11 @@ export class SessionExecutionService {
if (!releaseConflict) {
return respond('busy', { error: 'The session history is being replaced.' });
}
- let queueItemConsumed = false;
- const finishConsumed = (response: SessionQueueSteerResponse): SessionQueueSteerResponse =>
- queueItemConsumed ? this.rememberQueueSteerReceipt(operationKey, response) : response;
+ let receiptEligible = false;
+ let ownsDurableOperation = false;
+ const finish = (response: SessionQueueSteerResponse): SessionQueueSteerResponse =>
+ receiptEligible ? this.rememberQueueSteerReceipt(operationKey, response) : response;
try {
- const runtime = this.turnRuntimeBySession.get(options.sessionId);
- if (!runtime || !runtime.session || !runtime.promptInFlight || runtime.cancelRequested) {
- return respond('no-active-turn');
- }
- if (runtime.turnId !== options.expectedTurnId) {
- return respond('stale-turn');
- }
-
const sessionDoc = await this.deps.workspaceDocument.getOrCreateSessionDoc(
options.sessionId
);
@@ -1461,6 +1516,53 @@ export class SessionExecutionService {
return respond('error', { error: 'Session metadata is unavailable.' });
}
+ const previousOperation = await this.deps.queueSteerOperationStore.read(options.sessionId);
+ if (previousOperation) {
+ if (
+ !isQueueSteerMarkerOwnedBy(
+ previousOperation,
+ this.deps.workspaceId,
+ this.deps.machineId
+ )
+ ) {
+ return respond('busy', { error: 'A queue Steer marker belongs to another owner.' });
+ }
+ const durableReceipt = this.queueSteerResponseFromOperation(
+ options.sessionId,
+ previousOperation
+ );
+ if (durableReceipt && previousOperation.operationKey === operationKey) {
+ return this.rememberQueueSteerReceipt(operationKey, durableReceipt);
+ }
+ // A completed marker is the crash-safe receipt for the immediately
+ // preceding operation. A new exact request may replace it.
+ if (!durableReceipt && previousOperation.operationKey !== operationKey) {
+ return respond('busy', { error: 'Another queued Steer is being recovered.' });
+ }
+ if (!durableReceipt) {
+ const recovery = await this.recoverQueueSteerOperationLocked(
+ options.sessionId,
+ sessionDoc,
+ previousOperation
+ );
+ if (recovery === 'deferred') {
+ return respond('error', {
+ userTurnId: previousOperation.userTurnId,
+ error: 'The previous native Steer delivery is still indeterminate.',
+ });
+ }
+ return this.rememberQueueSteerReceipt(operationKey, recovery);
+ }
+ }
+
+ const runtime = this.turnRuntimeBySession.get(options.sessionId);
+ if (!runtime || !runtime.session || !runtime.promptInFlight || runtime.cancelRequested) {
+ return respond('no-active-turn');
+ }
+ if (runtime.turnId !== options.expectedTurnId) {
+ return respond('stale-turn');
+ }
+
const currentRuntime = this.turnRuntimeBySession.get(options.sessionId);
if (
currentRuntime !== runtime ||
@@ -1484,9 +1586,30 @@ export class SessionExecutionService {
});
}
+ let nativeOperation: QueueSteerOperation | undefined;
+ if (useNativeSteer) {
+ const queuedItem = (await sessionDoc.getMessageQueue()).find(
+ (item) => item.$cid === options.queueItemId
+ );
+ if (!queuedItem) return respond('queue-item-missing');
+ const prepared = buildQueuedMessageUserTurn(queuedItem, meta, {
+ status: 'pending_apply',
+ });
+ if (!prepared) return respond('invalid-queue-item');
+ ownsDurableOperation = true;
+ nativeOperation = await this.writeQueueSteerOperation(options.sessionId, {
+ version: 1,
+ operationKey,
+ queueItemId: options.queueItemId,
+ expectedTurnId: options.expectedTurnId,
+ userTurnId: prepared.id,
+ phase: 'reserved',
+ });
+ }
+
// Queue order and immediate steering are separate mutations. Consume the
// selected identity directly; A/B keep their relative order when C wins.
- // Native steer owns dispatch publication through its handoff path.
+ // Native steer keeps the row as its durable retry record until handoff.
const consumed = await sessionDoc.consumeMessageQueueItemAsUserTurn(
options.queueItemId,
(item) => {
@@ -1494,33 +1617,53 @@ export class SessionExecutionService {
status: useNativeSteer ? 'pending_apply' : 'pending',
});
if (!queuedTurn || !useNativeSteer) return queuedTurn;
+ if (nativeOperation && queuedTurn.id !== nativeOperation.userTurnId) return null;
return { ...queuedTurn, userId: authenticatedRequesterUserId };
},
{ publishDispatch: !useNativeSteer }
);
if (consumed.type === 'missing') {
+ if (ownsDurableOperation) await this.clearQueueSteerOperation(options.sessionId);
return respond('queue-item-missing');
}
if (consumed.type === 'editing') {
+ if (ownsDurableOperation) await this.clearQueueSteerOperation(options.sessionId);
return respond('queue-item-editing');
}
if (consumed.type === 'invalid') {
+ if (ownsDurableOperation) await this.clearQueueSteerOperation(options.sessionId);
return respond('invalid-queue-item');
}
- queueItemConsumed = true;
const entry = consumed.entry;
if (useNativeSteer) {
+ await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
const inputConfig = normalizeSessionTurnInputConfig(entry.inputConfig);
const timestamp = entry.timestamp?.trim();
if (!inputConfig || !timestamp) {
- return finishConsumed(
- respond('invalid-queue-item', {
- userTurnId: entry.id,
- error: 'The queued message cannot be converted to a steer turn.',
- })
+ const invalid = respond('invalid-queue-item', {
+ userTurnId: entry.id,
+ error: 'The queued message cannot be converted to a steer turn.',
+ });
+ nativeOperation = await this.recoverQueueSteerAsDispatch(
+ options.sessionId,
+ sessionDoc,
+ nativeOperation!,
+ {
+ disposition: invalid.disposition,
+ userTurnId: invalid.userTurnId,
+ error: invalid.error,
+ }
);
+ nativeOperation = await this.completeQueueSteerOperation(
+ options.sessionId,
+ nativeOperation,
+ invalid
+ );
+ receiptEligible = true;
+ return finish(invalid);
}
+ let durableRejection = false;
const nativeResult = await this.steerSessionLocked({
sessionId: options.sessionId,
expectedTurnId: options.expectedTurnId,
@@ -1528,10 +1671,64 @@ export class SessionExecutionService {
userId: authenticatedRequesterUserId,
timestamp,
inputConfig,
+ onSubmitting: async () => {
+ nativeOperation = await this.writeQueueSteerOperation(options.sessionId, {
+ ...nativeOperation!,
+ phase: 'submitting',
+ });
+ },
+ onAcknowledged: async () => {
+ nativeOperation = await this.writeQueueSteerOperation(options.sessionId, {
+ ...nativeOperation!,
+ phase: 'acknowledged',
+ });
+ },
+ onApplied: async () => {
+ await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
+ nativeOperation = await this.writeQueueSteerOperation(options.sessionId, {
+ ...nativeOperation!,
+ phase: 'applied',
+ });
+ },
+ onUndelivered: async (disposition, error) => {
+ nativeOperation = await this.recoverQueueSteerAsDispatch(
+ options.sessionId,
+ sessionDoc,
+ nativeOperation!,
+ {
+ disposition,
+ userTurnId: entry.id,
+ ...(error ? { error } : {}),
+ }
+ );
+ durableRejection = true;
+ },
});
const rejectedDisposition =
nativeResult.disposition === 'applied' ? 'error' : nativeResult.disposition;
- return finishConsumed(
+ if (nativeResult.applied) {
+ await sessionDoc.removeMessageQueueItem(options.queueItemId);
+ await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
+ const accepted = respond('accepted', { userTurnId: entry.id });
+ nativeOperation = await this.completeQueueSteerOperation(
+ options.sessionId,
+ nativeOperation!,
+ accepted
+ );
+ receiptEligible = true;
+ } else if (durableRejection) {
+ const rejected = respond(rejectedDisposition, {
+ userTurnId: entry.id,
+ error: nativeResult.error,
+ });
+ nativeOperation = await this.completeQueueSteerOperation(
+ options.sessionId,
+ nativeOperation!,
+ rejected
+ );
+ receiptEligible = true;
+ }
+ return finish(
nativeResult.applied
? respond('accepted', { userTurnId: entry.id })
: respond(rejectedDisposition, {
@@ -1541,6 +1738,8 @@ export class SessionExecutionService {
);
}
+ receiptEligible = true;
+
const cancellation = await this.cancelSession({
type: 'session/cancel',
sessionId: options.sessionId,
@@ -1549,16 +1748,16 @@ export class SessionExecutionService {
turnId: options.expectedTurnId,
});
if (!cancellation.success) {
- return finishConsumed(
+ return finish(
respond('error', {
userTurnId: entry.id,
error: cancellation.error ?? 'The active turn could not be stopped.',
})
);
}
- return finishConsumed(respond('accepted', { userTurnId: entry.id }));
+ return finish(respond('accepted', { userTurnId: entry.id }));
} catch (error) {
- return finishConsumed(respond('error', { error: formatErrorMessage(error) }));
+ return finish(respond('error', { error: formatErrorMessage(error) }));
} finally {
releaseConflict();
}
@@ -1572,6 +1771,13 @@ export class SessionExecutionService {
userId: string;
timestamp: string;
inputConfig: SessionTurnInputConfig;
+ onSubmitting?: () => Promise;
+ onAcknowledged?: () => Promise;
+ onApplied?: () => Promise;
+ onUndelivered?: (
+ disposition: Exclude,
+ error?: string
+ ) => Promise;
}): Promise {
const reject = (
disposition: Exclude,
@@ -1594,11 +1800,17 @@ export class SessionExecutionService {
disposition: Exclude,
error?: string
): Promise => {
- await this.requeueUndeliveredSteer(options.sessionId, options.userTurnId, {
- canWriteHistory: true,
- });
+ recoveryAttempted = true;
+ if (options.onUndelivered) {
+ await options.onUndelivered(disposition, error);
+ } else {
+ await this.requeueUndeliveredSteer(options.sessionId, options.userTurnId, {
+ canWriteHistory: true,
+ });
+ }
return reject(disposition, error);
};
+ let recoveryAttempted = false;
const runtime = this.turnRuntimeBySession.get(options.sessionId);
if (!runtime || !runtime.session) {
return await rejectUndelivered('no-active-turn');
@@ -1687,10 +1899,18 @@ export class SessionExecutionService {
const previousTurnId = runtime.turnId;
const previousUserTurnId = runtime.userTurnId;
+ await options.onSubmitting?.();
const steerRun = agentClient.steerPrompt(acpSessionId, promptBlocks);
submittedToAgent = true;
const application = await steerRun.applied;
try {
+ try {
+ await options.onAcknowledged?.();
+ } catch (error) {
+ this.deps.logger.error(
+ `[${options.sessionId}] Failed to persist accepted steer ${options.userTurnId}: ${formatErrorMessage(error)}`
+ );
+ }
if (
runtime.cancelRequested ||
this.turnRuntimeBySession.get(options.sessionId) !== runtime ||
@@ -1742,6 +1962,7 @@ export class SessionExecutionService {
this.deps.logger.error(
`[${options.sessionId}] Failed to persist applied steer ownership for ${options.userTurnId}: ${formatErrorMessage(error)}`
);
+ if (options.onApplied) throw error;
}
const nextTurnId = this.deps.beginConversationTurn(options.sessionId, options.userTurnId, {
dispatchSource: 'rpc',
@@ -1778,6 +1999,7 @@ export class SessionExecutionService {
runtime.userTurnId = options.userTurnId;
this.markCurrentTurn(options.sessionId, nextTurnId);
ownedPromptRun.signalSuccessor();
+ await options.onApplied?.();
return {
type: 'session/steer_response',
sessionId: options.sessionId,
@@ -1789,6 +2011,9 @@ export class SessionExecutionService {
application.release();
}
} catch (error) {
+ if (recoveryAttempted) {
+ throw error;
+ }
const notDelivered = !submittedToAgent || error instanceof AgentSteerNotDeliveredError;
if (!notDelivered) {
return reject('error', formatErrorMessage(error));
@@ -1803,6 +2028,243 @@ export class SessionExecutionService {
}
}
+ /**
+ * Reconcile a durable native queue-Steer saga after daemon restart or a
+ * failed recovery write. Provider calls are never replayed: only a reserved
+ * or already-fallback operation is provably safe to publish as an ordinary
+ * turn. A submitting/acknowledged operation becomes a visible failure once
+ * its original prompt owner is gone because ACP has no query/idempotency
+ * contract that could distinguish "not sent" from "already injected". An
+ * applied operation has already committed local ownership and is only cleaned
+ * up; its accepted receipt survives a lost response and daemon restart.
+ */
+ async recoverPendingQueueSteer(
+ sessionId: SessionId,
+ sessionDoc: SessionDocument
+ ): Promise {
+ return await this.steerMutationQueue.enqueue(sessionId, async () => {
+ const releaseConflict = this.tryAcquireSessionRewriteConflictLease(sessionId);
+ if (!releaseConflict) return 'deferred';
+ try {
+ const operation = await this.deps.queueSteerOperationStore.read(sessionId);
+ if (!operation) return null;
+ if (!isQueueSteerMarkerOwnedBy(operation, this.deps.workspaceId, this.deps.machineId)) {
+ return 'deferred';
+ }
+ return await this.recoverQueueSteerOperationLocked(sessionId, sessionDoc, operation);
+ } finally {
+ releaseConflict();
+ }
+ });
+ }
+
+ async recoverPendingQueueSteers(): Promise {
+ let operations: QueueSteerOperation[];
+ try {
+ operations = await this.deps.queueSteerOperationStore.list();
+ } catch (error) {
+ this.deps.logger.error(
+ `[queue-steer] Failed to list recovery markers: ${formatErrorMessage(error)}`
+ );
+ return;
+ }
+ for (const operation of operations) {
+ if (
+ operation.completedAt ||
+ !isQueueSteerMarkerOwnedBy(operation, this.deps.workspaceId, this.deps.machineId)
+ ) {
+ continue;
+ }
+ try {
+ const sessionId = operation.sessionId as SessionId;
+ const sessionDoc = await this.deps.workspaceDocument.getOrCreateSessionDoc(sessionId);
+ await this.recoverPendingQueueSteer(sessionId, sessionDoc);
+ } catch (error) {
+ this.deps.logger.error(
+ `[${operation.sessionId}] Failed to recover queued Steer ${operation.operationKey}: ${formatErrorMessage(error)}`
+ );
+ }
+ }
+ }
+
+ private async recoverQueueSteerOperationLocked(
+ sessionId: SessionId,
+ sessionDoc: SessionDocument,
+ operation: QueueSteerOperation
+ ): Promise {
+ const durableReceipt = this.queueSteerResponseFromOperation(sessionId, operation);
+ if (durableReceipt) return durableReceipt;
+ const runtime = this.turnRuntimeBySession.get(sessionId);
+ if (
+ (operation.phase === 'submitting' || operation.phase === 'acknowledged') &&
+ runtime?.turnId === operation.expectedTurnId &&
+ runtime.promptInFlight
+ ) {
+ return 'deferred';
+ }
+
+ await sessionDoc.waitUntilSynced?.();
+ const history = readSessionHistory(sessionDoc.sessionData.history);
+ const entry = history.find(
+ (candidate) => candidate.role === 'user' && candidate.id === operation.userTurnId
+ );
+ if (!entry) {
+ if (operation.phase === 'reserved') {
+ // The index is written before queue consumption. No history entry means
+ // the crash happened before reservation crossed the history boundary.
+ const response = {
+ type: 'session/queue-steer_response',
+ sessionId,
+ queueItemId: operation.queueItemId,
+ accepted: false,
+ disposition: 'error',
+ userTurnId: operation.userTurnId,
+ error: 'The daemon restarted before the queued Steer reservation completed.',
+ } satisfies SessionQueueSteerResponse;
+ await this.completeQueueSteerOperation(sessionId, operation, response);
+ return response;
+ }
+ this.deps.logger.error(
+ `[${sessionId}] Queue Steer ${operation.operationKey} is ${operation.phase} but its history entry is unavailable`
+ );
+ return 'deferred';
+ }
+
+ if (operation.phase === 'reserved' || operation.phase === 'fallback') {
+ const fallbackResponse = operation.response ?? {
+ disposition: 'error' as const,
+ userTurnId: operation.userTurnId,
+ error: 'The daemon restarted before native Steer submission; the turn was queued instead.',
+ };
+ const fallbackOperation = await this.recoverQueueSteerAsDispatch(
+ sessionId,
+ sessionDoc,
+ operation,
+ fallbackResponse
+ );
+ const response = {
+ type: 'session/queue-steer_response',
+ sessionId,
+ queueItemId: operation.queueItemId,
+ accepted: false,
+ ...fallbackResponse,
+ } satisfies SessionQueueSteerResponse;
+ await this.completeQueueSteerOperation(sessionId, fallbackOperation, response);
+ return response;
+ }
+
+ const historyStatus = resolveSessionHistoryStatus(entry);
+ if (operation.phase === 'applied' || runtime?.userTurnId === operation.userTurnId) {
+ if (
+ runtime?.userTurnId !== operation.userTurnId &&
+ historyStatus !== 'handled' &&
+ historyStatus !== 'failed' &&
+ historyStatus !== 'canceled'
+ ) {
+ await this.setTerminalUserTurnStatus(sessionId, sessionDoc, operation.userTurnId, 'failed');
+ await this.deps.recordChatFailure(
+ sessionDoc,
+ 'agent_disconnected',
+ 'The daemon restarted after this Steer was applied. The provider call was not replayed.'
+ );
+ }
+ await sessionDoc.removeMessageQueueItem(operation.queueItemId);
+ await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
+ const response = {
+ type: 'session/queue-steer_response',
+ sessionId,
+ queueItemId: operation.queueItemId,
+ accepted: true,
+ disposition: 'accepted',
+ userTurnId: operation.userTurnId,
+ } satisfies SessionQueueSteerResponse;
+ await this.completeQueueSteerOperation(
+ sessionId,
+ { ...operation, phase: 'applied' },
+ response
+ );
+ return response;
+ }
+
+ if (historyStatus === 'handled') {
+ await sessionDoc.removeMessageQueueItem(operation.queueItemId);
+ await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
+ const response = {
+ type: 'session/queue-steer_response',
+ sessionId,
+ queueItemId: operation.queueItemId,
+ accepted: true,
+ disposition: 'accepted',
+ userTurnId: operation.userTurnId,
+ } satisfies SessionQueueSteerResponse;
+ await this.completeQueueSteerOperation(
+ sessionId,
+ { ...operation, phase: 'applied' },
+ response
+ );
+ return response;
+ }
+
+ if (historyStatus !== 'failed' && historyStatus !== 'canceled') {
+ await this.setTerminalUserTurnStatus(sessionId, sessionDoc, operation.userTurnId, 'failed');
+ await this.deps.recordChatFailure(
+ sessionDoc,
+ 'agent_disconnected',
+ operation.phase === 'acknowledged'
+ ? 'The daemon restarted after the agent acknowledged this Steer but before local handoff completed. It was not replayed because that could execute it twice.'
+ : 'The daemon restarted while delivering this Steer. Delivery could not be confirmed, so it was not replayed.'
+ );
+ }
+ await sessionDoc.removeMessageQueueItem(operation.queueItemId);
+ await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
+ const response = {
+ type: 'session/queue-steer_response',
+ sessionId,
+ queueItemId: operation.queueItemId,
+ accepted: false,
+ disposition: 'error',
+ userTurnId: operation.userTurnId,
+ error:
+ operation.phase === 'acknowledged'
+ ? 'The agent acknowledged this Steer before the daemon restarted, but local handoff did not complete; it was not replayed.'
+ : 'Native Steer delivery became indeterminate when the daemon restarted; it was not replayed.',
+ } satisfies SessionQueueSteerResponse;
+ await this.completeQueueSteerOperation(sessionId, operation, response);
+ return response;
+ }
+
+ private async recoverQueueSteerAsDispatch(
+ sessionId: SessionId,
+ sessionDoc: SessionDocument,
+ operation: QueueSteerOperation,
+ response: NonNullable
+ ): Promise {
+ const queueItem = (await sessionDoc.getMessageQueue()).find(
+ (item) => item.$cid === operation.queueItemId
+ );
+ if (queueItem && hasActiveMessageQueueEditingLease(queueItem)) {
+ throw new Error(`Queued Steer ${operation.userTurnId} is being edited`);
+ }
+ let fallbackOperation = operation;
+ if (operation.phase !== 'fallback' || operation.response !== response) {
+ fallbackOperation = await this.writeQueueSteerOperation(sessionId, {
+ ...operation,
+ phase: 'fallback',
+ response,
+ completedAt: undefined,
+ });
+ }
+ const recovery = await this.requeueUndeliveredSteer(sessionId, operation.userTurnId, {
+ canWriteHistory: true,
+ });
+ if (recovery === 'requeue-failed') {
+ throw new Error(`Failed to durably recover queued Steer ${operation.userTurnId}`);
+ }
+ await sessionDoc.removeMessageQueueItem(operation.queueItemId);
+ await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
+ return fallbackOperation;
+ }
+
/**
* Re-route a steer the agent never accepted into ordinary dispatch, so it runs
* as the next message once the active turn ends — the same treatment a queued
@@ -1820,7 +2282,7 @@ export class SessionExecutionService {
sessionId: SessionId,
userTurnId: string,
{ canWriteHistory }: { canWriteHistory: boolean }
- ): Promise {
+ ): Promise<'requeued' | 'not-requeueable' | 'requeue-failed'> {
try {
// Guards against a late duplicate steer request resurrecting a turn that
// already ran: it is running now, it finished here, or it finished before
@@ -1829,16 +2291,16 @@ export class SessionExecutionService {
this.getActiveUserTurnId(sessionId) === userTurnId ||
this.getTerminalUserTurnStatusWithoutEntry(sessionId, userTurnId) !== undefined
) {
- return;
+ return 'not-requeueable';
}
const meta = await this.getSessionMeta(sessionId);
if (meta?.lastHandledUserMsgId === userTurnId) {
- return;
+ return 'not-requeueable';
}
if (canWriteHistory) {
const sessionDoc = await this.deps.workspaceDocument.getOrCreateSessionDoc(sessionId);
if (!(await this.markSteerTurnPending(sessionDoc, userTurnId))) {
- return;
+ return 'not-requeueable';
}
}
await this.upsertSessionMeta(sessionId, {
@@ -1848,12 +2310,12 @@ export class SessionExecutionService {
this.deps.logger.info(
`[${sessionId}] Undelivered steer ${userTurnId} requeued as a follow-up turn`
);
+ return 'requeued';
} catch (error) {
this.deps.logger.error(
- `[${sessionId}] Failed to requeue undelivered steer ${userTurnId}: ${formatErrorMessage(
- error
- )}`
+ `[${sessionId}] Failed to requeue undelivered steer ${userTurnId}: ${formatErrorMessage(error)}`
);
+ return 'requeue-failed';
}
}
diff --git a/apps/cli/src/session/session-queue-steer-operation-store.test.ts b/apps/cli/src/session/session-queue-steer-operation-store.test.ts
new file mode 100644
index 000000000..02beac641
--- /dev/null
+++ b/apps/cli/src/session/session-queue-steer-operation-store.test.ts
@@ -0,0 +1,73 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { MachineId, SessionId, WorkspaceId } from '@lody/shared';
+import {
+ createFileQueueSteerOperationStore,
+ type QueueSteerOperationMarker,
+} from './session-queue-steer-operation-store';
+
+const marker: QueueSteerOperationMarker = {
+ version: 1,
+ workspaceId: 'workspace-1',
+ machineId: 'machine-1',
+ sessionId: 'session-1',
+ operationKey: '["session-1","assistant-1","C"]',
+ queueItemId: 'C',
+ expectedTurnId: 'assistant-1',
+ userTurnId: 'user:C',
+ phase: 'reserved',
+ updatedAt: 1,
+};
+
+describe('file queue Steer operation store', () => {
+ let tempHome: string;
+
+ beforeEach(() => {
+ tempHome = mkdtempSync(path.join(os.tmpdir(), 'lody-queue-steer-operation-store-'));
+ vi.stubEnv('HOME', tempHome);
+ });
+
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ rmSync(tempHome, { recursive: true, force: true });
+ });
+
+ it('atomically records, overwrites, reads, lists, and clears a session marker', async () => {
+ const store = createFileQueueSteerOperationStore({
+ workspaceId: 'workspace-1' as WorkspaceId,
+ machineId: 'machine-1' as MachineId,
+ });
+ await store.record(marker);
+ await expect(store.read('session-1' as SessionId)).resolves.toEqual(marker);
+
+ const completed = {
+ ...marker,
+ phase: 'applied' as const,
+ response: { disposition: 'accepted' as const, userTurnId: 'user:C' },
+ completedAt: 2,
+ updatedAt: 2,
+ };
+ await store.record(completed);
+ await expect(store.list()).resolves.toEqual([completed]);
+
+ const root = path.join(tempHome, '.lody', 'session-queue-steer-operations');
+ expect((await stat(root)).mode & 0o777).toBe(0o700);
+ await store.clear('session-1' as SessionId);
+ await expect(store.read('session-1' as SessionId)).resolves.toBeNull();
+ });
+
+ it('ignores corrupt or unknown-version marker files', async () => {
+ const store = createFileQueueSteerOperationStore({
+ workspaceId: 'workspace-1' as WorkspaceId,
+ machineId: 'machine-1' as MachineId,
+ });
+ await store.record(marker);
+ const root = path.join(tempHome, '.lody', 'session-queue-steer-operations');
+ await writeFile(path.join(root, 'corrupt.json'), 'not json', 'utf8');
+ await writeFile(path.join(root, 'future.json'), JSON.stringify({ ...marker, version: 2 }));
+ await expect(store.list()).resolves.toEqual([marker]);
+ });
+});
diff --git a/apps/cli/src/session/session-queue-steer-operation-store.ts b/apps/cli/src/session/session-queue-steer-operation-store.ts
new file mode 100644
index 000000000..98936ad92
--- /dev/null
+++ b/apps/cli/src/session/session-queue-steer-operation-store.ts
@@ -0,0 +1,160 @@
+import { createHash, randomUUID } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { z } from 'zod';
+import type { MachineId, SessionId, WorkspaceId } from '@lody/shared';
+
+/**
+ * Machine-local authority for the native queue-Steer saga. Shared Session data
+ * cannot prove that the daemon accepted an RPC because collaborators may write
+ * it. One owner-scoped file per Session survives process death and is replaced
+ * by the next native operation; a completed marker doubles as the latest
+ * crash-safe receipt. Atomic rename prevents recovery from reading a partial
+ * phase transition.
+ */
+const QueueSteerResponseSchema = z
+ .object({
+ disposition: z.enum([
+ 'accepted',
+ 'queue-item-missing',
+ 'queue-item-editing',
+ 'invalid-queue-item',
+ 'no-active-turn',
+ 'stale-turn',
+ 'unsupported',
+ 'busy',
+ 'error',
+ ]),
+ userTurnId: z.string().min(1).optional(),
+ error: z.string().min(1).optional(),
+ })
+ .strict();
+
+const QueueSteerOperationMarkerSchema = z
+ .object({
+ version: z.literal(1),
+ workspaceId: z.string().min(1),
+ machineId: z.string().min(1),
+ sessionId: z.string().min(1),
+ operationKey: z.string().min(1),
+ queueItemId: z.string().min(1),
+ expectedTurnId: z.string().min(1),
+ userTurnId: z.string().min(1),
+ phase: z.enum(['reserved', 'submitting', 'acknowledged', 'applied', 'fallback']),
+ response: QueueSteerResponseSchema.optional(),
+ completedAt: z.number().finite().optional(),
+ updatedAt: z.number().finite(),
+ })
+ .strict();
+
+export type QueueSteerOperationMarker = z.infer;
+
+export type QueueSteerOperationStore = {
+ record(marker: QueueSteerOperationMarker): Promise;
+ read(sessionId: SessionId): Promise;
+ clear(sessionId: SessionId): Promise;
+ list(): Promise;
+};
+
+function getStoreRoot(): string {
+ return path.join(os.homedir(), '.lody', 'session-queue-steer-operations');
+}
+
+function getMarkerPath(
+ sessionId: SessionId,
+ owner: { workspaceId: WorkspaceId; machineId: MachineId }
+): string {
+ const key = createHash('sha256')
+ .update(JSON.stringify([owner.workspaceId, owner.machineId, sessionId]))
+ .digest('hex');
+ return path.join(getStoreRoot(), `${key}.json`);
+}
+
+async function readMarkerFile(markerPath: string): Promise {
+ try {
+ const parsed = QueueSteerOperationMarkerSchema.safeParse(
+ JSON.parse(await readFile(markerPath, 'utf8')) as unknown
+ );
+ return parsed.success ? parsed.data : null;
+ } catch {
+ return null;
+ }
+}
+
+export function createFileQueueSteerOperationStore(owner: {
+ workspaceId: WorkspaceId;
+ machineId: MachineId;
+}): QueueSteerOperationStore {
+ return {
+ async record(marker) {
+ if (!isQueueSteerMarkerOwnedBy(marker, owner.workspaceId, owner.machineId)) {
+ throw new Error('Cannot persist a queue Steer marker for another owner');
+ }
+ const markerPath = getMarkerPath(marker.sessionId as SessionId, owner);
+ await mkdir(path.dirname(markerPath), { recursive: true, mode: 0o700 });
+ const temporaryPath = `${markerPath}.${process.pid}.${randomUUID()}.tmp`;
+ await writeFile(temporaryPath, `${JSON.stringify(marker)}\n`, {
+ encoding: 'utf8',
+ mode: 0o600,
+ });
+ await rename(temporaryPath, markerPath);
+ },
+
+ async read(sessionId) {
+ const marker = await readMarkerFile(getMarkerPath(sessionId, owner));
+ return marker && isQueueSteerMarkerOwnedBy(marker, owner.workspaceId, owner.machineId)
+ ? marker
+ : null;
+ },
+
+ async clear(sessionId) {
+ await rm(getMarkerPath(sessionId, owner), { force: true });
+ },
+
+ async list() {
+ let entries: string[];
+ try {
+ entries = await readdir(getStoreRoot());
+ } catch {
+ return [];
+ }
+ const markers: QueueSteerOperationMarker[] = [];
+ for (const entry of entries) {
+ if (!entry.endsWith('.json')) continue;
+ const marker = await readMarkerFile(path.join(getStoreRoot(), entry));
+ if (marker && isQueueSteerMarkerOwnedBy(marker, owner.workspaceId, owner.machineId)) {
+ markers.push(marker);
+ }
+ }
+ return markers;
+ },
+ };
+}
+
+export function createMemoryQueueSteerOperationStore(): QueueSteerOperationStore {
+ const markers = new Map();
+ return {
+ async record(marker) {
+ markers.set(marker.sessionId, structuredClone(marker));
+ },
+ async read(sessionId) {
+ const marker = markers.get(sessionId);
+ return marker ? structuredClone(marker) : null;
+ },
+ async clear(sessionId) {
+ markers.delete(sessionId);
+ },
+ async list() {
+ return [...markers.values()].map((marker) => structuredClone(marker));
+ },
+ };
+}
+
+export function isQueueSteerMarkerOwnedBy(
+ marker: QueueSteerOperationMarker,
+ workspaceId: WorkspaceId,
+ machineId: MachineId
+): boolean {
+ return marker.workspaceId === workspaceId && marker.machineId === machineId;
+}
diff --git a/apps/cli/tests/session-execution-service.test.ts b/apps/cli/tests/session-execution-service.test.ts
index 1d5e67942..6928ab5c6 100644
--- a/apps/cli/tests/session-execution-service.test.ts
+++ b/apps/cli/tests/session-execution-service.test.ts
@@ -46,6 +46,7 @@ import { GitExecutableNotFoundError } from '../src/session/worktree/git-process-
import { LodyOperationStore } from '../src/orchestration/operation-store';
import { markAssistantTurnFinished } from '../src/lib/assistant-turn-finalize';
import { shouldWatchSession } from '../src/session/session-dispatch-logic';
+import { createMemoryQueueSteerOperationStore } from '../src/session/session-queue-steer-operation-store';
const capabilityConfigId = 'config-1' as AgentConfigId;
@@ -163,6 +164,7 @@ const createBaseDeps = (
machineId: 'machine-1',
userId: 'owner-user',
workspaceId: 'workspace-1' as WorkspaceId,
+ queueSteerOperationStore: createMemoryQueueSteerOperationStore(),
preferredBaseBranch: 'main',
touchSession: vi.fn(),
startSessionActivePresence: vi.fn(async () => {}),
@@ -232,7 +234,9 @@ const createBaseDeps = (
const workspaceWithDocFactory = deps.workspaceDocument as unknown as {
getOrCreateSessionDoc: (...args: unknown[]) => Promise;
+ persistPendingChanges?: (reason: string) => Promise;
};
+ workspaceWithDocFactory.persistPendingChanges ??= vi.fn(async () => {});
const originalGetOrCreateSessionDoc = workspaceWithDocFactory.getOrCreateSessionDoc;
workspaceWithDocFactory.getOrCreateSessionDoc = vi.fn(async (...args: unknown[]) =>
ensureSessionDocDefaults(await originalGetOrCreateSessionDoc(...args))
@@ -315,7 +319,9 @@ describe('SessionExecutionService', () => {
}
),
};
+ const queueSteerOperationStore = createMemoryQueueSteerOperationStore();
const deps = createBaseDeps({
+ queueSteerOperationStore,
workspaceDocument: {
getOrCreateSessionDoc: vi.fn(async () => sessionDoc),
} as unknown as LoroDocumentManager,
@@ -648,6 +654,389 @@ describe('SessionExecutionService', () => {
expect(cancel).not.toHaveBeenCalled();
});
+ it('does not cache a native rejection until fallback publication is durable', async () => {
+ const sessionId = 'session-native-steer-recovery-retry' as SessionId;
+ const queuedItem: MessageQueueItem = {
+ $cid: 'C',
+ task: 'task C',
+ userId: 'forged-owner',
+ userTurnId: 'user:C',
+ timestamp: '2026-09-14T00:00:00.000Z',
+ acpSessionConfig: { prompt: 'task C' },
+ };
+ let queue = [queuedItem];
+ let history: SessionHistoryInput[] = [];
+ let meta = {
+ id: sessionId,
+ userId: 'owner-user',
+ machineId: 'machine-1',
+ cliType: 'builtin',
+ agentType: 'codex',
+ } as SessionMeta;
+ let rejectNextActivation = true;
+ let queueSteerPersistenceCount = 0;
+ const upsertDocMeta = vi.fn(async (_roomId: string, patch: Partial) => {
+ if (patch.latestUserMsgId && rejectNextActivation) {
+ rejectNextActivation = false;
+ throw new Error('activation unavailable');
+ }
+ meta = { ...meta, ...patch };
+ });
+ const persistPendingChanges = vi.fn(async (reason: string) => {
+ if (reason !== 'queue-steer-commit') return;
+ queueSteerPersistenceCount += 1;
+ if (queueSteerPersistenceCount === 2) {
+ throw new Error('queue Steer persistence unavailable');
+ }
+ });
+ const sessionDoc = withHistoryPort({
+ getMetaState: vi.fn(async () => meta),
+ getMessageQueue: vi.fn(async () => queue),
+ waitUntilSynced: vi.fn(async () => {}),
+ getHistory: () => history,
+ updateHistory: vi.fn(
+ async (update: (entries: SessionHistoryInput[]) => SessionHistoryInput[]) => {
+ history = update(history);
+ }
+ ),
+ consumeMessageQueueItemAsUserTurn: vi.fn(
+ async (_cid: string, build: (item: MessageQueueItem) => SessionHistoryInput | null) => {
+ const entry = build(queuedItem);
+ if (!entry) return { type: 'invalid' as const };
+ history.push(entry);
+ return { type: 'consumed' as const, entry };
+ }
+ ),
+ removeMessageQueueItem: vi.fn(async (cid: string) => {
+ queue = queue.filter((item) => item.$cid !== cid);
+ }),
+ });
+ const queueSteerOperationStore = createMemoryQueueSteerOperationStore();
+ const deps = createBaseDeps({
+ queueSteerOperationStore,
+ workspaceDocument: {
+ repo: { upsertDocMeta, getDocMeta: vi.fn(async () => ({ meta })) },
+ getOrCreateSessionDoc: vi.fn(async () => sessionDoc),
+ persistPendingChanges,
+ } as unknown as LoroDocumentManager,
+ });
+ const service = new SessionExecutionService(deps);
+ const activeTurnId = 'assistant:active';
+ const runtime = {
+ sessionId,
+ turnId: activeTurnId,
+ userTurnId: 'user:active',
+ session: {
+ agentClient: {
+ getAcknowledgedSteerCapability: vi.fn(() => ({
+ provider: 'codex',
+ appliedNotificationMethod: 'codex/steerApplied',
+ upstreamTurn: 'same',
+ configPolicy: 'active',
+ })),
+ findSteerConfigMismatch: vi.fn(() => null),
+ steerPrompt: vi.fn(() => {
+ throw new AgentSteerNotDeliveredError('provider refused');
+ }),
+ },
+ acpSessionId: 'acp-native-retry' as ACPSessionId,
+ },
+ promptInFlight: true,
+ cancelRequested: false,
+ invocation: {
+ sourceTurnId: 'user:active',
+ requesterUserId: 'authenticated-user',
+ inputConfig: { prompt: 'active' },
+ },
+ activePromptRun: { turnId: activeTurnId },
+ };
+ (
+ service as unknown as { turnRuntimeBySession: Map }
+ ).turnRuntimeBySession.set(sessionId, runtime);
+ const request = { sessionId, expectedTurnId: activeTurnId, queueItemId: 'C' };
+
+ await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
+ accepted: false,
+ disposition: 'error',
+ error: expect.stringContaining('Failed to durably recover'),
+ });
+ await expect(queueSteerOperationStore.read(sessionId)).resolves.toMatchObject({
+ phase: 'fallback',
+ completedAt: undefined,
+ });
+ expect(history).toEqual([expect.objectContaining({ id: 'user:C', status: 'pending' })]);
+ expect(queue).toHaveLength(1);
+ expect(
+ (service as unknown as { queueSteerReceipts: Map }).queueSteerReceipts.size
+ ).toBe(0);
+
+ await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
+ accepted: false,
+ disposition: 'error',
+ error: 'queue Steer persistence unavailable',
+ });
+ await expect(queueSteerOperationStore.read(sessionId)).resolves.toMatchObject({
+ phase: 'fallback',
+ completedAt: undefined,
+ });
+ expect(
+ (service as unknown as { queueSteerReceipts: Map }).queueSteerReceipts.size
+ ).toBe(0);
+
+ await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
+ accepted: false,
+ disposition: 'no-active-turn',
+ error: 'provider refused',
+ });
+ expect(queue).toEqual([]);
+ expect(meta.latestUserMsgId).toBe('user:C');
+ await expect(queueSteerOperationStore.read(sessionId)).resolves.toMatchObject({
+ phase: 'fallback',
+ completedAt: expect.any(Number),
+ response: { disposition: 'no-active-turn', error: 'provider refused' },
+ });
+ expect(upsertDocMeta.mock.calls.filter(([, patch]) => patch.latestUserMsgId)).toHaveLength(3);
+
+ const restartedService = new SessionExecutionService(deps);
+ await expect(restartedService.steerQueuedMessage(request)).resolves.toMatchObject({
+ accepted: false,
+ disposition: 'no-active-turn',
+ error: 'provider refused',
+ });
+ expect(upsertDocMeta.mock.calls.filter(([, patch]) => patch.latestUserMsgId)).toHaveLength(3);
+ });
+
+ it.each(['submitting', 'acknowledged', 'applied'] as const)(
+ 'recovers a crashed native Steer in %s without replaying the provider call',
+ async (phase) => {
+ const sessionId = `session-native-steer-crash-${phase}` as SessionId;
+ const operation = {
+ version: 1 as const,
+ workspaceId: 'workspace-1',
+ machineId: 'machine-1',
+ sessionId,
+ operationKey: `operation-${phase}`,
+ queueItemId: 'C',
+ expectedTurnId: 'assistant:old',
+ userTurnId: 'user:C',
+ phase,
+ updatedAt: 1,
+ };
+ let queue = [{ $cid: 'A' }, { $cid: 'C' }];
+ let history: SessionHistoryInput[] = [
+ {
+ id: 'user:C',
+ role: 'user',
+ userId: 'authenticated-user',
+ status: 'pending_apply',
+ read: false,
+ items: [{ type: 'text', text: 'task C' }],
+ } as SessionHistoryInput,
+ ];
+ let meta = {
+ id: sessionId,
+ userId: 'owner-user',
+ machineId: 'machine-1',
+ cliType: 'builtin',
+ agentType: 'codex',
+ } as SessionMeta;
+ const upsertDocMeta = vi.fn(async (_roomId: string, patch: Partial) => {
+ meta = { ...meta, ...patch };
+ });
+ const sessionDoc = withHistoryPort({
+ getMetaState: vi.fn(async () => meta),
+ getMessageQueue: vi.fn(async () => queue),
+ waitUntilSynced: vi.fn(async () => {}),
+ getHistory: () => history,
+ updateHistory: vi.fn(
+ async (update: (entries: SessionHistoryInput[]) => SessionHistoryInput[]) => {
+ history = update(history);
+ }
+ ),
+ removeMessageQueueItem: vi.fn(async (cid: string) => {
+ queue = queue.filter((item) => item.$cid !== cid);
+ }),
+ });
+ const queueSteerOperationStore = createMemoryQueueSteerOperationStore();
+ await queueSteerOperationStore.record(operation);
+ const deps = createBaseDeps({
+ queueSteerOperationStore,
+ workspaceDocument: {
+ repo: { upsertDocMeta, getDocMeta: vi.fn(async () => ({ meta })) },
+ getOrCreateSessionDoc: vi.fn(async () => sessionDoc),
+ } as unknown as LoroDocumentManager,
+ });
+ const service = new SessionExecutionService(deps);
+
+ await service.recoverPendingQueueSteer(sessionId, sessionDoc);
+ expect(queue).toEqual([{ $cid: 'A' }]);
+ expect(history).toEqual([expect.objectContaining({ id: 'user:C', status: 'failed' })]);
+ expect(meta.latestUserMsgId).toBeUndefined();
+ await expect(queueSteerOperationStore.read(sessionId)).resolves.toMatchObject({
+ phase,
+ completedAt: expect.any(Number),
+ response: {
+ disposition: phase === 'applied' ? 'accepted' : 'error',
+ userTurnId: 'user:C',
+ },
+ });
+ expect(deps.recordChatFailure).toHaveBeenCalledWith(
+ sessionDoc,
+ 'agent_disconnected',
+ expect.stringContaining(phase === 'applied' ? 'was applied' : 'not replayed')
+ );
+ }
+ );
+
+ it('recovers a crash after native reservation by dispatching that exact row', async () => {
+ const sessionId = 'session-native-steer-crash-reserved' as SessionId;
+ let queue = [
+ { $cid: 'A' },
+ { $cid: 'B' },
+ { $cid: 'C', isEditing: true, editingStartedAt: Number.MAX_SAFE_INTEGER },
+ ];
+ let history: SessionHistoryInput[] = [
+ {
+ id: 'user:C',
+ role: 'user',
+ userId: 'authenticated-user',
+ status: 'pending_apply',
+ read: false,
+ items: [{ type: 'text', text: 'task C' }],
+ } as SessionHistoryInput,
+ ];
+ let meta = {
+ id: sessionId,
+ userId: 'owner-user',
+ machineId: 'machine-1',
+ cliType: 'builtin',
+ agentType: 'codex',
+ } as SessionMeta;
+ const upsertDocMeta = vi.fn(async (_roomId: string, patch: Partial) => {
+ meta = { ...meta, ...patch };
+ });
+ const sessionDoc = withHistoryPort({
+ getMetaState: vi.fn(async () => meta),
+ getMessageQueue: vi.fn(async () => queue),
+ waitUntilSynced: vi.fn(async () => {}),
+ getHistory: () => history,
+ updateHistory: vi.fn(
+ async (update: (entries: SessionHistoryInput[]) => SessionHistoryInput[]) => {
+ history = update(history);
+ }
+ ),
+ removeMessageQueueItem: vi.fn(async (cid: string) => {
+ queue = queue.filter((item) => item.$cid !== cid);
+ }),
+ });
+ const queueSteerOperationStore = createMemoryQueueSteerOperationStore();
+ await queueSteerOperationStore.record({
+ version: 1,
+ workspaceId: 'workspace-1',
+ machineId: 'machine-1',
+ sessionId,
+ operationKey: 'operation-reserved',
+ queueItemId: 'C',
+ expectedTurnId: 'assistant:old',
+ userTurnId: 'user:C',
+ phase: 'reserved',
+ updatedAt: 1,
+ });
+ const service = new SessionExecutionService(
+ createBaseDeps({
+ queueSteerOperationStore,
+ workspaceDocument: {
+ repo: { upsertDocMeta, getDocMeta: vi.fn(async () => ({ meta })) },
+ getOrCreateSessionDoc: vi.fn(async () => sessionDoc),
+ } as unknown as LoroDocumentManager,
+ })
+ );
+
+ await service.recoverPendingQueueSteers();
+ expect(queue.map((item) => item.$cid)).toEqual(['A', 'B', 'C']);
+ const editingMarker = await queueSteerOperationStore.read(sessionId);
+ expect(editingMarker).toMatchObject({ phase: 'reserved' });
+ expect(editingMarker?.completedAt).toBeUndefined();
+
+ queue = queue.map((item) => (item.$cid === 'C' ? { ...item, isEditing: false } : item));
+ await service.recoverPendingQueueSteers();
+
+ expect(history).toEqual([expect.objectContaining({ id: 'user:C', status: 'pending' })]);
+ expect(queue).toEqual([{ $cid: 'A' }, { $cid: 'B' }]);
+ expect(meta).toMatchObject({ latestUserMsgId: 'user:C' });
+ await expect(queueSteerOperationStore.read(sessionId)).resolves.toMatchObject({
+ phase: 'fallback',
+ completedAt: expect.any(Number),
+ response: { disposition: 'error', userTurnId: 'user:C' },
+ });
+ });
+
+ it('ignores queue Steer recovery markers owned by another machine', async () => {
+ const queueSteerOperationStore = createMemoryQueueSteerOperationStore();
+ await queueSteerOperationStore.record({
+ version: 1,
+ workspaceId: 'workspace-1',
+ machineId: 'machine-2',
+ sessionId: 'session-foreign',
+ operationKey: 'foreign-operation',
+ queueItemId: 'C',
+ expectedTurnId: 'assistant:old',
+ userTurnId: 'user:C',
+ phase: 'reserved',
+ updatedAt: 1,
+ });
+ const deps = createBaseDeps({ queueSteerOperationStore });
+ const service = new SessionExecutionService(deps);
+
+ await service.recoverPendingQueueSteers();
+
+ expect(deps.workspaceDocument.getOrCreateSessionDoc).not.toHaveBeenCalled();
+ await expect(
+ queueSteerOperationStore.read('session-foreign' as SessionId)
+ ).resolves.toMatchObject({ machineId: 'machine-2', phase: 'reserved' });
+ });
+
+ it('leaves the row queued when a crash precedes the reserved history write', async () => {
+ const sessionId = 'session-native-steer-pre-history-crash' as SessionId;
+ const queueSteerOperationStore = createMemoryQueueSteerOperationStore();
+ await queueSteerOperationStore.record({
+ version: 1,
+ workspaceId: 'workspace-1',
+ machineId: 'machine-1',
+ sessionId,
+ operationKey: 'pre-history-operation',
+ queueItemId: 'C',
+ expectedTurnId: 'assistant:old',
+ userTurnId: 'user:C',
+ phase: 'reserved',
+ updatedAt: 1,
+ });
+ const removeMessageQueueItem = vi.fn(async () => {});
+ const sessionDoc = withHistoryPort({
+ waitUntilSynced: vi.fn(async () => {}),
+ getHistory: () => [],
+ getMessageQueue: vi.fn(async () => [{ $cid: 'C', task: 'task C' }]),
+ removeMessageQueueItem,
+ });
+ const deps = createBaseDeps({
+ queueSteerOperationStore,
+ workspaceDocument: {
+ repo: { upsertDocMeta: vi.fn(async () => {}) },
+ getOrCreateSessionDoc: vi.fn(async () => sessionDoc),
+ } as unknown as LoroDocumentManager,
+ });
+ const service = new SessionExecutionService(deps);
+
+ await service.recoverPendingQueueSteers();
+
+ expect(removeMessageQueueItem).not.toHaveBeenCalled();
+ await expect(queueSteerOperationStore.read(sessionId)).resolves.toMatchObject({
+ phase: 'reserved',
+ completedAt: expect.any(Number),
+ response: { disposition: 'error' },
+ });
+ });
+
it('advances one session owner through consecutive prompt handoffs', async () => {
const steerPrompt = vi.fn(() => ({
completion: new Promise(() => {}),
@@ -682,6 +1071,8 @@ describe('SessionExecutionService', () => {
cliType: 'builtin',
agentType: 'codex',
})),
+ getMessageQueue: vi.fn(async () => [queuedItem]),
+ removeMessageQueueItem: vi.fn(async () => {}),
consumeMessageQueueItemAsUserTurn: vi.fn(
async (cid: string, buildEntry: (item: MessageQueueItem) => SessionHistoryInput | null) => {
expect(cid).toBe(queuedItem.$cid);
@@ -788,6 +1179,12 @@ describe('SessionExecutionService', () => {
expect.any(Function),
{ publishDispatch: false }
);
+ expect(sessionDoc.removeMessageQueueItem).toHaveBeenCalledWith(queuedItem.$cid);
+ await expect(deps.queueSteerOperationStore.read(sessionId)).resolves.toMatchObject({
+ phase: 'applied',
+ completedAt: expect.any(Number),
+ response: { disposition: 'accepted', userTurnId: 'user-2' },
+ });
expect(initialPromptRun.successor?.turnId).toBe('assistant:user-2');
expect(runtime.activePromptRun.turnId).toBe('assistant:user-2');
diff --git a/specs/message-queue-interactions.md b/specs/message-queue-interactions.md
index 0a2df6f7c..6b25e7535 100644
--- a/specs/message-queue-interactions.md
+++ b/specs/message-queue-interactions.md
@@ -28,7 +28,7 @@ the queue by hand.
| Active daemon/runtime | Steer behavior |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
- | Exact-item protocol and acknowledged native ACP Steer | Atomically consume the selected row as `pending_apply`, then inject it into the current prompt through `steerPrompt`. |
+ | Exact-item protocol and acknowledged native ACP Steer | Reserve the selected row as `pending_apply`, retain it through the durable handoff saga, then inject it through `steerPrompt`. |
| Exact-item protocol without native ACP Steer | Persist and activate the selected row as the next user turn, remove it from the queue, then stop only the expected turn. |
| Older daemon with authoritative acknowledged native ACP Steer | Preserve the legacy native Steer path. |
| Older daemon without acknowledged native ACP Steer | Keep the established queue-head interrupt behavior; disable Steer on later rows and require a daemon update for exact selection. |
@@ -46,6 +46,17 @@ the queue by hand.
invocation, never from the shared queue row. If that frozen identity is unavailable, the
daemon fails before consuming the row, submitting to the provider, or stopping the turn.
+ Native handoff is a durable saga, not an atomic CRDT/provider operation. A machine-local,
+ daemon-owned marker records `reserved`, write-ahead `submitting`, provider `acknowledged`,
+ locally committed `applied`, or `fallback`, and keeps the selected queue row until the result
+ is durable. A `reserved` entry that reached history, or any `fallback`, may become the exact
+ ordinary turn;
+ a reservation interrupted before history leaves the row queued. `submitting` is indeterminate
+ and `acknowledged` may already have side effects, so neither is replayed after its prompt owner
+ disappears. `applied` proves local handoff and recovers as accepted while ordinary crash
+ handling makes an interrupted turn visible. This is the fail-closed boundary required because
+ ACP supplies no idempotent submission key or delivery-query operation.
+
For cancel-and-dispatch Steer, the selected queue row is the durable retry marker: append
history first, publish `latestUserMsgId`, and remove the row only after both writes succeed.
A retry after partial publication reuses the existing turn ID rather than duplicating history.
@@ -54,11 +65,14 @@ the queue by hand.
identity is missing, its editing lease is active, or the expected turn no longer owns
execution, the daemon must not submit native Steer or stop any turn. The renderer waits for
this acknowledgement and never removes or materializes an exact-protocol row itself.
-- The daemon retains a bounded receipt for each recently consumed exact-item request, keyed by
- session, expected turn, and queue identity. A same-process retry after a lost response returns
- the recorded result without consuming or cancelling again. If consumption succeeded but
+- The daemon retains a bounded in-memory receipt for each recently consumed exact-item request,
+ keyed by session, expected turn, and queue identity. Native saga completion also persists its
+ latest receipt in the operation marker, so an immediate retry survives daemon restart; a later
+ native operation may replace that terminal marker. Shared Session metadata is not a recovery
+ authority because collaborators can write it. If consumption succeeded but
cancellation failed, the message remains a durable follow-up and a retained-receipt retry must
- not duplicate it.
+ not duplicate it. A native rejection is receipt-eligible only after its history status,
+ activation pointer, and queue-row cleanup are durable; failed recovery remains retryable.
- The number and non-editing message body form the drag target for queue reordering.
Steer, edit, and remove remain separate controls and must not begin a drag.
- Editing keeps its existing keyboard and focus behavior and disables reordering for
@@ -70,7 +84,9 @@ The shortcut changes routing only when Queue and Steer are meaningfully distinct
idle session still dispatches normally, and a session without positive live prompt
activity retains the conservative queue barrier even if the inverse intent would be
Steer. Touch and pointer interactions share the same drag target; installed-app and
-physical-device coverage remains separate from component tests.
+physical-device coverage remains separate from component tests. The provider boundary cannot
+offer exactly-once recovery without protocol support: indeterminate native submissions are
+reported, never silently replayed.
## Implementation evidence
@@ -78,7 +94,7 @@ physical-device coverage remains separate from component tests.
- `packages/components/src/components/sessions/session-chat-input-area.tsx`
- `packages/components/src/components/sessions/message-queue/`
- `packages/components/tests/{session-message-submit-route,session-chat-input-submission,message-queue-row-editing}.test.*`
-- `apps/cli/{tests/session-execution-service.test.ts,src/lib/loro/doc-user-turn.test.ts}`
+- `apps/cli/{tests/session-execution-service.test.ts,src/lib/loro/doc-user-turn.test.ts,src/session/session-queue-steer-operation-store.ts}`
- [Decision record](../.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md)
This is a draft for human review. Implementation and passing tests do not approve it.
diff --git a/specs/message-queue-interactions.zh.md b/specs/message-queue-interactions.zh.md
index 803ae1d10..b4935784a 100644
--- a/specs/message-queue-interactions.zh.md
+++ b/specs/message-queue-interactions.zh.md
@@ -23,7 +23,7 @@ Translation: current
| 当前 daemon/runtime | 引导行为 |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
- | 支持精确队列项协议，且支持 acknowledged native ACP Steer | 原子消费目标行为 `pending_apply`，再通过 `steerPrompt` 注入当前 prompt。 |
+ | 支持精确队列项协议，且支持 acknowledged native ACP Steer | 将目标保留为 `pending_apply`，通过持久 handoff saga 后由 `steerPrompt` 注入。 |
| 支持精确队列项协议，但不支持 native ACP Steer | 将目标行持久化并激活为下一用户 turn，从队列删除后再只停止预期 turn。 |
| 旧 daemon，但 authoritative capability 声明支持 acknowledged native ACP Steer | 保留旧版真正 native Steer 路径。 |
| 旧 daemon，且不支持 acknowledged native ACP Steer | 仅保留既有队首 interrupt 行为；禁用后续行“引导”，并要求升级 daemon 才能精确选择。 |
@@ -39,6 +39,14 @@ Translation: current
Native 精确“引导”的 requester identity 必须来自已认证的活动 invocation，绝不来自共享
queue row。若该冻结身份不可用，daemon 必须在消费 row、提交 provider 或停止 turn 之前失败。
+ Native handoff 是持久 saga，而不是 CRDT 写入与 provider side effect 之间不存在的原子操作。
+ machine-local、由 daemon 持有的 marker 记录 `reserved`、write-ahead `submitting`、provider `acknowledged`、本地已提交
+ `applied` 或 `fallback`，且在结果持久化前保留所选 queue row。已进入 history 的 `reserved` 和
+ `fallback` 可转为精确普通 turn；若 reservation 在写 history 前中断，则保留 row 在队列。
+ `submitting` 结果不确定，`acknowledged` 可能已有 side effect，原 prompt owner 消失后两者都
+ 不得重放，而应落成可见失败。`applied` 证明本地 handoff 已完成，应恢复 accepted 回执，并由
+ 普通 crash handling 显示被中断的 turn。ACP 没有幂等提交键或交付查询，因此这里必须 fail closed。
+
对 cancel-and-dispatch Steer，所选 queue row 是持久重试标记：先追加 history，再发布
`latestUserMsgId`，且仅在两项写入都成功后删除 row。部分发布后的重试应复用已有 turn ID，
不得重复追加 history。
@@ -46,9 +54,13 @@ Translation: current
- 过期或冲突的精确“引导”选择必须失败且无副作用。所选 ID 已不存在、编辑 lease 仍有效，或
预期 turn 已不再拥有执行权时，daemon 不得提交 native Steer，也不得停止任何 turn。Renderer
等待确认，不自行移除队列项或为精确协议写历史。
-- daemon 会按 session、预期 turn 和队列 ID，为最近已消费的精确请求保留有界 receipt。
- 同一 daemon 进程内因响应丢失而重试时，应返回已记录结果，不得再次消费或取消。若消费
- 成功但取消失败，消息仍是持久 follow-up；receipt 仍保留时的重试不得复制它。
+- daemon 会按 session、预期 turn 和队列 ID，为最近已消费的精确请求保留有界内存 receipt；
+ native saga 还会把最近一次最终回执保留在持久 marker 中，使 daemon 重启后的立即重试仍能
+ 返回原结果。后续 native 操作可替换该终态 marker。共享 Session metadata 可由协作者写入，
+ 因而不得作为恢复权威。若消费
+ 成功但取消失败，消息仍是持久 follow-up；receipt 仍保留时的重试不得复制它。Native 拒绝
+ 只有在 history 状态、activation pointer 和 queue row 清理都持久化后才能写入 receipt；恢复
+ 失败必须保持可重试。
- 序号和非编辑状态的消息正文共同组成队列重排拖动区域。“引导”、“编辑”和“移除”是独立
控件，不能触发拖动。
- 编辑状态保留已有键盘与焦点行为，并在编辑结束前禁用该行重排。
@@ -57,7 +69,8 @@ Translation: current
只有“排队”和“引导”具有不同含义时，该快捷键才改变路由。空闲会话仍正常直接发送；没有
明确实时 prompt 活动时，即使反转意图是“引导”，也继续采用保守的排队屏障。触摸和鼠标共用
-同一拖动区域；已安装应用和物理设备验证不由组件测试替代。
+同一拖动区域；已安装应用和物理设备验证不由组件测试替代。Provider 未提供协议支持时无法
+实现 exactly-once 恢复；结果不确定的 native 提交必须明确报错，绝不能静默重放。
## 实现证据
@@ -65,7 +78,7 @@ Translation: current
- `packages/components/src/components/sessions/session-chat-input-area.tsx`
- `packages/components/src/components/sessions/message-queue/`
- `packages/components/tests/{session-message-submit-route,session-chat-input-submission,message-queue-row-editing}.test.*`
-- `apps/cli/{tests/session-execution-service.test.ts,src/lib/loro/doc-user-turn.test.ts}`
+- `apps/cli/{tests/session-execution-service.test.ts,src/lib/loro/doc-user-turn.test.ts,src/session/session-queue-steer-operation-store.ts}`
- [决策记录](../.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md)
这是供人工审阅的草稿；实现和测试通过不代表 Spec 已获批准。
From 4e97db58bd9eaa0a53b3dfbcdb433bf1ec98231e Mon Sep 17 00:00:00 2001
From: wibus-wee <62133302+wibus-wee@users.noreply.github.com>
Date: Mon, 14 Sep 2026 15:24:13 +0800
Subject: [PATCH 08/15] docs: record Effect ownership proposal for queue steer
Model: gpt-6
---
.../2026-09-14-queue-steer-effect-boundary.md | 96 +++++++++++++++++++
...26-09-14-queue-steer-effect-boundary.zh.md | 83 ++++++++++++++++
2 files changed, 179 insertions(+)
create mode 100644 .agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md
create mode 100644 .agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
diff --git a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md
new file mode 100644
index 000000000..d85cb9113
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md
@@ -0,0 +1,96 @@
+# Effect ownership for queue Steer
+
+Status: proposed
+Translation: current
+
+[中文](2026-09-14-queue-steer-effect-boundary.zh.md)
+
+## Abstract
+
+Queue Steer currently distributes delivery decisions across the renderer and
+operation bookkeeping across `SessionExecutionService`. The proposed boundary
+puts exact-item selection behind one daemon operation and gives `QueueSteerService`
+ownership of delivery, resource lifetimes, receipts, and recovery. Effect can
+express those lifetimes and failures compositionally, but its core runtime does
+not make ACP delivery transactional or durable. This source investigation establishes
+implementation constraints; the refactor and its behavioral verification remain pending.
+
+## Source evidence
+
+The installed package is `effect@3.18.4`. Its npm package contains source, but no
+`AGENTS.md`. The official v3 checkout has an
+[AGENTS.md](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/AGENTS.md)
+and a [documentation entry](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/docs/index.md).
+Current upstream `main` develops v4; examples using `Context.Service` or
+`Effect.catch` must not be copied into this v3 application. CLI instructions
+reference `context/cli-effect-ts.md`, which is absent from this checkout.
+
+| Principle | Verified meaning | Consequence for Steer |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| A program is a value | `Effect` describes a lazy computation, its expected failures, and required services. | Compose the operation before running it; Promise execution belongs at the integration boundary. |
+| Failures have different meanings | Expected failures are typed; defects and interruption remain distinguishable through `Cause` and `Exit`. | Model missing, editing, stale, rejected, and indeterminate outcomes explicitly; never turn every failure into fallback delivery. |
+| Resources have an owner | `acquireRelease` protects acquisition and finalizer registration against interruption; `acquireUseRelease` restores interruptibility for use. | Scope rewrite leases and provider application leases; cleanup must also run on failure and interruption. |
+| Concurrency has a lifetime | Fibers have supervision and scope relationships. A Promise adapter cannot cancel external work without cooperation. | Keep session serialization shared with prompt completion; Stop must preserve the ACP owner's lifetime until completion or confirmed termination. |
+| Dependencies are explicit | v3 `Context.Tag` identifies a service and `Layer` constructs its implementation. | Inject storage and execution ports; avoid passing the entire execution service or its mutable maps into the new service. |
+
+The installed implementation was inspected in `src/internal/core.ts`
+(`acquireUseRelease`), `src/internal/fiberRuntime.ts` (`acquireRelease`),
+`src/internal/core-effect.ts` (`tryPromise`), and `src/ManagedRuntime.ts`.
+The corresponding [3.18.4 source](https://github.com/Effect-TS/effect/tree/ede2ea11c2abe7038bac3c83fb7b5eef101858d2/packages/effect/src)
+is the API authority. Upstream v3
+[resource tests](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/acquire-release.test.ts)
+and [interruption tests](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/interruption.test.ts)
+were read as additional semantic evidence, not run or assumed identical to the pinned release.
+
+## Proposed boundary
+
+The UI supplies `{ sessionId, queueItemId, expectedTurnId }` for the selected row.
+It displays the result without choosing provider delivery. The daemon operation
+validates those identities and editing ownership, then chooses native delivery
+or cancel-and-dispatch inside `QueueSteerService`. Effect owns composition,
+typed failures, leases, and finalization within that service.
+
+`SessionExecutionService` retains ownership of the live turn and exposes narrow
+execution operations. It should not receive queue phases or callbacks such as
+`onSubmitting` solely to advance a queue recovery journal. Queue storage retains
+its existing history and activation publication responsibilities. Request handlers
+convert Effect results to the existing response contract at one boundary.
+
+Native preparation, provider submission, acknowledged ownership handoff, and
+receipt completion form one composed delivery path. Cancel-and-dispatch forms
+the other. Use `Effect.gen` for sequencing and tagged recovery handlers for
+specific recoverable failures. Merely wrapping the current async method in
+`Effect.tryPromise` would leave lifecycle ownership unchanged.
+
+The existing renderer also supports older daemons. That compatibility policy
+must be reconciled with the single-operation UI before implementation: preserving
+it requires encapsulating legacy behavior below the UI; removing it requires
+updating the draft [interaction Spec](../../../../specs/message-queue-interactions.md)
+and compatibility tests. This investigation does not silently remove it.
+
+## Recovery boundary
+
+Finalizers release owned resources; they cannot undo provider acceptance. A typed
+provider refusal can authorize ordinary dispatch, while an indeterminate submission
+cannot. Do not apply `Effect.retry` to the complete delivery operation or interpret
+timeout/interruption as evidence of non-delivery.
+
+Keep the existing machine-local recovery evidence and fail-closed replay rules
+from the [original decision](../../implemented/feature/2026-09-13-queue-steer-controls.md).
+Move its ownership into the operation service; do not add a durable phase for
+each Effect step. Core `Scope` cleanup does not survive process death. A workflow
+engine would be a separate dependency and architectural decision, and is not
+required merely to express these two delivery paths.
+
+## Verification still required
+
+Implementation should retain observable coverage for selecting C while preserving
+A/B, missing or editing rows, stale expected turns, native acceptance/refusal,
+Stop racing acknowledgment, failed persistence, and response-loss/restart recovery.
+Add deterministic failure/interruption coverage that proves leases are released
+without relinquishing a still-running ACP owner. Check UI invocation through the
+single operation and verify legacy compatibility at its chosen boundary.
+
+This note records source inspection and a proposed decomposition only. Business
+code, dependency versions, and the existing Spec are unchanged; no runtime tests
+were executed for the proposal.
diff --git a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
new file mode 100644
index 000000000..aa50739fa
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
@@ -0,0 +1,83 @@
+# 队列 Steer 的 Effect 归属边界
+
+Status: proposed
+Translation: current
+
+[English](2026-09-14-queue-steer-effect-boundary.md)
+
+## 摘要
+
+当前队列 Steer 的交付选择分散在 renderer，operation 记录则集中在
+`SessionExecutionService`。拟议边界将精确队列项选择收口为一个 daemon operation，
+由 `QueueSteerService` 负责交付、资源生命周期、回执和恢复。Effect 可以组合表达这些
+生命周期与失败，但核心 runtime 无法让 ACP 交付具备事务性或持久性。本次源码研究明确了
+实现约束；重构及其行为验证仍待完成。
+
+## 源码证据
+
+当前安装版本是 `effect@3.18.4`。npm 包包含源码，但没有 `AGENTS.md`。官方 v3
+checkout 包含
+[AGENTS.md](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/AGENTS.md)
+与[文档入口](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/docs/index.md)。
+上游当前 `main` 开发的是 v4，不能将使用 `Context.Service` 或 `Effect.catch` 的示例
+直接复制到本项目的 v3。CLI 规则引用的 `context/cli-effect-ts.md` 在当前 checkout 缺失。
+
+| 原则 | 已核实的语义 | 对 Steer 的影响 |
+| ---------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| 程序是值 | `Effect` 描述惰性计算、预期失败和所需服务。 | 先组合 operation，再执行；Promise 执行集中在集成边界。 |
+| 失败具有不同含义 | 预期失败进入类型；defect 与 interruption 可通过 `Cause`、`Exit` 区分。 | 显式表达缺失、编辑中、过期、拒绝与交付不确定，不能把所有失败转成 fallback。 |
+| 资源有归属 | `acquireRelease` 保护资源获取及 finalizer 注册不被中断；`acquireUseRelease` 在 use 阶段恢复可中断性。 | rewrite lease 与 provider application lease 归属 scope；失败或中断也须清理。 |
+| 并发有生命周期 | fiber 具有监督与 scope 关系；Promise 适配无法在外部工作不配合时取消它。 | 与 prompt completion 共享 session 串行边界；Stop 必须保留 ACP owner，直到完成或确认终止。 |
+| 依赖显式声明 | v3 `Context.Tag` 标识服务，`Layer` 构造实现。 | 注入存储与执行 port，避免把整个 execution service 或其可变 map 传进新服务。 |
+
+已检查安装包的 `src/internal/core.ts`（`acquireUseRelease`）、
+`src/internal/fiberRuntime.ts`（`acquireRelease`）、`src/internal/core-effect.ts`
+（`tryPromise`）以及 `src/ManagedRuntime.ts`。对应的
+[3.18.4 源码](https://github.com/Effect-TS/effect/tree/ede2ea11c2abe7038bac3c83fb7b5eef101858d2/packages/effect/src)
+是 API 依据。另已阅读上游 v3 的
+[资源测试](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/acquire-release.test.ts)
+与[中断测试](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/interruption.test.ts)
+作为补充语义证据；未运行这些测试，也未假定它们与固定版本完全相同。
+
+## 拟议边界
+
+UI 为选中的行传入 `{ sessionId, queueItemId, expectedTurnId }`，展示结果，无需选择
+provider 交付方式。daemon operation 验证这些标识与编辑归属，再由
+`QueueSteerService` 内部选择 native delivery 或 cancel-and-dispatch。Effect 在服务
+内部负责组合、类型化失败、lease 与 finalization。
+
+`SessionExecutionService` 保留 live turn 的所有权，暴露窄执行操作。它不应仅为推进
+queue recovery journal 而接收 queue phase 或 `onSubmitting` 等回调。队列存储保留
+现有 history 与 activation 发布责任。request handler 在一个边界把 Effect 结果转换
+为现有响应协议。
+
+native preparation、provider submission、确认后的所有权交接与回执完成组成一条
+交付链；cancel-and-dispatch 组成另一条。用 `Effect.gen` 表达顺序，以 tagged recovery
+handler 处理特定可恢复失败。仅把现有 async 方法包进 `Effect.tryPromise` 不会改变
+生命周期归属。
+
+当前 renderer 还兼容旧 daemon，实现前需要使这项兼容策略与单 operation UI 一致：
+保留兼容需要将 legacy 行为封装到 UI 下层；移除兼容则需要更新 draft
+[交互 Spec](../../../../specs/message-queue-interactions.md) 与兼容性测试。
+本次研究没有隐式移除这项能力。
+
+## 恢复边界
+
+finalizer 释放拥有的资源，无法撤销 provider 已接受的交付。类型化的 provider 拒绝
+可以允许普通 dispatch；交付不确定则不允许。不能对整个交付 operation 使用
+`Effect.retry`，也不能把 timeout 或 interruption 当成未交付的证据。
+
+保留[原决策](../../implemented/feature/2026-09-13-queue-steer-controls.md)中的
+machine-local 恢复证据与保守重放规则，将其归属迁移到 operation service；不为每个
+Effect 步骤新增 durable phase。核心 `Scope` 清理无法跨越进程死亡。引入 workflow
+engine 是独立的依赖与架构决策，仅为表达这两条交付链无需引入它。
+
+## 待完成的验证
+
+实现须保留可观察行为覆盖：选择 C 后 A/B 顺序不变、队列项缺失或编辑中、expected turn
+过期、native 接受或拒绝、Stop 与 acknowledgment 竞态、持久化失败，以及响应丢失和
+重启恢复。新增确定性失败与中断验证，证明 lease 会释放，同时不会放弃仍在运行的 ACP
+owner。验证 UI 通过单 operation 调用，并在选定边界验证旧版本兼容。
+
+本 note 仅记录源码研究与拟议拆分。业务代码、依赖版本及现有 Spec 均未修改；未为此
+提案运行 runtime 测试。
From 5758984a608395ba52f8b4127481ad2babd3a9ce Mon Sep 17 00:00:00 2001
From: wibus-wee <62133302+wibus-wee@users.noreply.github.com>
Date: Mon, 14 Sep 2026 15:40:40 +0800
Subject: [PATCH 09/15] docs: refine queue steer ownership and capability
contract
Model: gpt-6
---
.../2026-09-14-queue-steer-effect-boundary.md | 210 ++++++++++++------
...26-09-14-queue-steer-effect-boundary.zh.md | 178 +++++++++------
specs/message-queue-interactions.md | 32 ++-
specs/message-queue-interactions.zh.md | 30 ++-
4 files changed, 298 insertions(+), 152 deletions(-)
diff --git a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md
index d85cb9113..9966bde2e 100644
--- a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md
+++ b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md
@@ -9,88 +9,150 @@ Translation: current
Queue Steer currently distributes delivery decisions across the renderer and
operation bookkeeping across `SessionExecutionService`. The proposed boundary
-puts exact-item selection behind one daemon operation and gives `QueueSteerService`
-ownership of delivery, resource lifetimes, receipts, and recovery. Effect can
-express those lifetimes and failures compositionally, but its core runtime does
-not make ACP delivery transactional or durable. This source investigation establishes
-implementation constraints; the refactor and its behavioral verification remain pending.
+gives `QueueSteerService` exact selection, validation, durable recovery evidence,
+fallback policy, and results; `ActiveTurnSteerPort` owns native submission and
+live-turn handoff. Effect expresses local resource lifetimes and typed failure
+semantics without making provider submission reversible. Queue Steer requires a
+supported `queueItemSteer` capability, with no old-daemon compatibility path.
+The design is revised; implementation and behavioral verification remain pending.
## Source evidence
-The installed package is `effect@3.18.4`. Its npm package contains source, but no
-`AGENTS.md`. The official v3 checkout has an
-[AGENTS.md](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/AGENTS.md)
+The [workspace catalog](../../../../pnpm-workspace.yaml) pins `effect: 3.18.4`,
+and [CLI dependencies](../../../../apps/cli/package.json) consume `catalog:`.
+[SessionExecutionService](../../../../apps/cli/src/session/session-execution-service.ts)
+already uses `Effect.gen` and `Effect.acquireRelease` for turn ownership and
+finalization. The proposal extends that existing approach.
+
+The installed package has source but no `AGENTS.md`. The official v3 checkout has
+[agent instructions](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/AGENTS.md)
and a [documentation entry](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/docs/index.md).
-Current upstream `main` develops v4; examples using `Context.Service` or
-`Effect.catch` must not be copied into this v3 application. CLI instructions
-reference `context/cli-effect-ts.md`, which is absent from this checkout.
-
-| Principle | Verified meaning | Consequence for Steer |
-| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| A program is a value | `Effect` describes a lazy computation, its expected failures, and required services. | Compose the operation before running it; Promise execution belongs at the integration boundary. |
-| Failures have different meanings | Expected failures are typed; defects and interruption remain distinguishable through `Cause` and `Exit`. | Model missing, editing, stale, rejected, and indeterminate outcomes explicitly; never turn every failure into fallback delivery. |
-| Resources have an owner | `acquireRelease` protects acquisition and finalizer registration against interruption; `acquireUseRelease` restores interruptibility for use. | Scope rewrite leases and provider application leases; cleanup must also run on failure and interruption. |
-| Concurrency has a lifetime | Fibers have supervision and scope relationships. A Promise adapter cannot cancel external work without cooperation. | Keep session serialization shared with prompt completion; Stop must preserve the ACP owner's lifetime until completion or confirmed termination. |
-| Dependencies are explicit | v3 `Context.Tag` identifies a service and `Layer` constructs its implementation. | Inject storage and execution ports; avoid passing the entire execution service or its mutable maps into the new service. |
-
-The installed implementation was inspected in `src/internal/core.ts`
-(`acquireUseRelease`), `src/internal/fiberRuntime.ts` (`acquireRelease`),
-`src/internal/core-effect.ts` (`tryPromise`), and `src/ManagedRuntime.ts`.
+Upstream v4 examples using `Context.Service` or `Effect.catch` must not be copied
+into this v3 application. CLI instructions reference `context/cli-effect-ts.md`,
+which is absent from this checkout.
+
+The installed implementations of `acquireUseRelease` in `src/internal/core.ts`,
+`acquireRelease` in `src/internal/fiberRuntime.ts`, `tryPromise` in
+`src/internal/core-effect.ts`, and the `ManagedRuntime` API were inspected.
The corresponding [3.18.4 source](https://github.com/Effect-TS/effect/tree/ede2ea11c2abe7038bac3c83fb7b5eef101858d2/packages/effect/src)
is the API authority. Upstream v3
[resource tests](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/acquire-release.test.ts)
and [interruption tests](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/interruption.test.ts)
-were read as additional semantic evidence, not run or assumed identical to the pinned release.
-
-## Proposed boundary
-
-The UI supplies `{ sessionId, queueItemId, expectedTurnId }` for the selected row.
-It displays the result without choosing provider delivery. The daemon operation
-validates those identities and editing ownership, then chooses native delivery
-or cancel-and-dispatch inside `QueueSteerService`. Effect owns composition,
-typed failures, leases, and finalization within that service.
-
-`SessionExecutionService` retains ownership of the live turn and exposes narrow
-execution operations. It should not receive queue phases or callbacks such as
-`onSubmitting` solely to advance a queue recovery journal. Queue storage retains
-its existing history and activation publication responsibilities. Request handlers
-convert Effect results to the existing response contract at one boundary.
-
-Native preparation, provider submission, acknowledged ownership handoff, and
-receipt completion form one composed delivery path. Cancel-and-dispatch forms
-the other. Use `Effect.gen` for sequencing and tagged recovery handlers for
-specific recoverable failures. Merely wrapping the current async method in
-`Effect.tryPromise` would leave lifecycle ownership unchanged.
-
-The existing renderer also supports older daemons. That compatibility policy
-must be reconciled with the single-operation UI before implementation: preserving
-it requires encapsulating legacy behavior below the UI; removing it requires
-updating the draft [interaction Spec](../../../../specs/message-queue-interactions.md)
-and compatibility tests. This investigation does not silently remove it.
-
-## Recovery boundary
-
-Finalizers release owned resources; they cannot undo provider acceptance. A typed
-provider refusal can authorize ordinary dispatch, while an indeterminate submission
-cannot. Do not apply `Effect.retry` to the complete delivery operation or interpret
-timeout/interruption as evidence of non-delivery.
-
-Keep the existing machine-local recovery evidence and fail-closed replay rules
-from the [original decision](../../implemented/feature/2026-09-13-queue-steer-controls.md).
-Move its ownership into the operation service; do not add a durable phase for
-each Effect step. Core `Scope` cleanup does not survive process death. A workflow
-engine would be a separate dependency and architectural decision, and is not
-required merely to express these two delivery paths.
+were read as supplementary evidence, not run or assumed identical to the pinned release.
+
+## Responsibilities
+
+| Owner | Responsibility |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| UI | Pass `{ sessionId, queueItemId, expectedTurnId }` for the selected row; display the result. |
+| `QueueSteerService` | Exact queue-item selection, validation, durable recovery evidence, fallback policy, result and receipt. |
+| `ActiveTurnSteerPort` | Live-turn ownership, provider native submission, prompt handoff, and serialization with Stop and other active-turn operations. |
+| Queue storage | Existing history and activation publication responsibilities. |
+| Integration boundary | Provide v3 `Context.Tag` services through `Layer`; execute the composed operation and map its result to the response contract. |
+
+The active-turn implementation stays with the execution owner. QueueSteerService
+must not access `runtime.session.agentClient`, runtime maps, `promptInFlight`,
+`successor`, or `invocation`. The port derives the frozen requester identity
+from the active invocation and validates the expected turn under its own
+serialization boundary; caller validation never replaces that check.
+
+The native operation exposes a domain result, conceptually:
+
+```ts
+interface ActiveTurnSteerPort {
+ steer(input: {
+ sessionId: SessionId;
+ expectedTurnId: string;
+ turn: SteerTurn;
+ }): Effect.Effect;
+}
+```
+
+`SteerTurn` is validated immutable turn data, not a runtime handle.
+`NativeSteerApplied` proves successful local handoff, not prompt completion.
+`StaleTurn` proves rejection before submission. Lost ownership after submission
+cannot be reported as that safe rejection.
+
+This is the native operation's contract, not an exhaustive interface for every
+execution operation. Native-support discovery and expected-turn cancellation
+also stay behind execution-owned operations. QueueSteerService chooses the policy
+without inspecting the provider client. Never expose `onSubmitting`,
+`onAcknowledged`, `onApplied`, or `onUndelivered` callbacks to advance a queue
+journal. The new service must not be the existing runtime-dependent code moved
+to another file.
+
+## Resource and failure model
+
+`Effect` describes a lazy computation with explicit expected failures
+and dependencies. Use `Effect.gen` to compose operations, with typed recovery
+handlers at the owner of the policy. A single `Effect.tryPromise` around the
+existing async workflow would not change lifecycle ownership.
+
+Rewrite leases and local live-turn ownership/serialization guards belong to
+`Scope`. Provider submission is an irreversible external side effect, not a
+resource that can be released. The sequence is acquire local ownership, submit
+the provider side effect, then release local ownership when its contract allows.
+Finalizers prevent local ownership leaks; they do not prove non-execution.
+An existing adapter acknowledgment handle is only a local synchronization
+resource and stays internal to the port.
+
+The expected error model has three categories:
+
+| Category | Evidence and examples | Recovery policy |
+| ---------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Safe rejection | Provider did not execute: `ProviderRejected`, pre-submission `StaleTurn`. | Fallback/retry is eligible only if operation preconditions still hold. Stale, missing, or editing selections remain failed no-ops; they must not stop a turn. |
+| Indeterminate delivery | `ProviderDeliveryUnknown`: submission may have executed, including acknowledgment or handoff uncertainty. | Propagate the failure; no fallback handler and no replay. |
+| Local failure | `PersistenceFailure`, validation or lease acquisition failure. | Recover from durable evidence; a local error alone never establishes non-delivery. |
+
+Use distinct v3 `Data.TaggedError` classes for `ProviderRejected`,
+`ProviderDeliveryUnknown`, and `PersistenceFailure`. The native port classifies
+delivery evidence; the operation's persistence boundary owns `PersistenceFailure`.
+A local failure after submission must preserve possible delivery and cannot be
+reclassified as `ProviderRejected`.
+
+The policy handler is `Effect.catchTag("ProviderRejected", fallbackToDispatch)`.
+There is no corresponding fallback handler for `ProviderDeliveryUnknown`.
+Defects and interruption remain distinguishable through `Cause`/`Exit`;
+neither a timeout nor an interrupted Promise establishes provider non-execution.
+Do not retry the complete delivery operation.
+
+## Durability and capability policy
+
+QueueSteerService owns durable recovery evidence, including write-ahead evidence
+before entering a potentially submitting port call and durable receipts after its
+result. A crash between these boundaries remains conservatively indeterminate
+unless authoritative evidence proves otherwise. Implement the journal contract
+without phase callbacks or exposing live runtime state. Preserve recovery of the
+existing markers and fail-closed replay guarantees from the
+[original decision](../../implemented/feature/2026-09-13-queue-steer-controls.md);
+do not add a durable phase for every Effect step.
+
+Core Scope cleanup cannot survive process death. Stop must retain the ACP owner
+until raw completion or confirmed termination; a Promise wrapper cannot cancel
+external work without its cooperation. A workflow engine is a separate
+architectural decision, not required for these two delivery paths.
+
+Queue Steer has no old-daemon compatibility path. Without an advertised supported
+`queueItemSteer` version, every row's Steer action is unavailable, including the
+queue head. Do not fall back to renderer history materialization, legacy native
+Steer, or queue-head cancel. On supported daemons every row passes its own queue
+identity; the daemon chooses native delivery or cancel-and-dispatch.
+
+This supersedes the original decision's old-daemon compatibility policy for
+queue Steer only. Composer submission behavior is outside this change.
+The draft [interaction Spec](../../../../specs/message-queue-interactions.md)
+records the revised intent; the renderer still contains the old paths.
## Verification still required
-Implementation should retain observable coverage for selecting C while preserving
-A/B, missing or editing rows, stale expected turns, native acceptance/refusal,
-Stop racing acknowledgment, failed persistence, and response-loss/restart recovery.
-Add deterministic failure/interruption coverage that proves leases are released
-without relinquishing a still-running ACP owner. Check UI invocation through the
-single operation and verify legacy compatibility at its chosen boundary.
-
-This note records source inspection and a proposed decomposition only. Business
-code, dependency versions, and the existing Spec are unchanged; no runtime tests
-were executed for the proposal.
+Retain observable coverage for selecting C while preserving A/B, missing/editing
+rows, stale expected turns, native acceptance/refusal, Stop racing acknowledgment,
+failed persistence, and response-loss/restart recovery. Verify each error category:
+only eligible safe rejections dispatch fallback; indeterminate outcomes never
+replay; local failures recover according to durable evidence. Deterministic
+failure/interruption tests must prove local guards release without relinquishing
+a still-running ACP owner. Unsupported daemons must expose no usable queue Steer
+action on any row and issue no legacy submission or cancellation.
+
+Business code and dependency versions are unchanged. This revised design and
+Spec are not implementation evidence; no runtime tests were executed.
diff --git a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
index aa50739fa..87f1a58f1 100644
--- a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
+++ b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
@@ -8,76 +8,130 @@ Translation: current
## 摘要
当前队列 Steer 的交付选择分散在 renderer，operation 记录则集中在
-`SessionExecutionService`。拟议边界将精确队列项选择收口为一个 daemon operation，
-由 `QueueSteerService` 负责交付、资源生命周期、回执和恢复。Effect 可以组合表达这些
-生命周期与失败，但核心 runtime 无法让 ACP 交付具备事务性或持久性。本次源码研究明确了
-实现约束；重构及其行为验证仍待完成。
+`SessionExecutionService`。拟议边界由 `QueueSteerService` 负责精确选择、验证、
+持久恢复证据、fallback 策略与结果；`ActiveTurnSteerPort` 负责 native 提交和 live turn
+交接。Effect 表达本地资源生命周期与类型化失败语义，不会让 provider 提交变得可撤销。
+队列 Steer 必须具备受支持的 `queueItemSteer` capability，不提供旧 daemon 兼容路径。
+设计已修订，实现与行为验证仍待完成。
## 源码证据
-当前安装版本是 `effect@3.18.4`。npm 包包含源码，但没有 `AGENTS.md`。官方 v3
-checkout 包含
-[AGENTS.md](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/AGENTS.md)
+[workspace catalog](../../../../pnpm-workspace.yaml) 固定 `effect: 3.18.4`，
+[CLI 依赖](../../../../apps/cli/package.json) 通过 `catalog:` 使用它。
+[SessionExecutionService](../../../../apps/cli/src/session/session-execution-service.ts)
+已经用 `Effect.gen`、`Effect.acquireRelease` 表达 turn ownership 与 finalization，
+本提案延续现有方式。
+
+安装包有源码但没有 `AGENTS.md`。官方 v3 checkout 包含
+[agent 规则](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/AGENTS.md)
与[文档入口](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/docs/index.md)。
-上游当前 `main` 开发的是 v4，不能将使用 `Context.Service` 或 `Effect.catch` 的示例
-直接复制到本项目的 v3。CLI 规则引用的 `context/cli-effect-ts.md` 在当前 checkout 缺失。
-
-| 原则 | 已核实的语义 | 对 Steer 的影响 |
-| ---------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| 程序是值 | `Effect` 描述惰性计算、预期失败和所需服务。 | 先组合 operation，再执行；Promise 执行集中在集成边界。 |
-| 失败具有不同含义 | 预期失败进入类型；defect 与 interruption 可通过 `Cause`、`Exit` 区分。 | 显式表达缺失、编辑中、过期、拒绝与交付不确定，不能把所有失败转成 fallback。 |
-| 资源有归属 | `acquireRelease` 保护资源获取及 finalizer 注册不被中断；`acquireUseRelease` 在 use 阶段恢复可中断性。 | rewrite lease 与 provider application lease 归属 scope；失败或中断也须清理。 |
-| 并发有生命周期 | fiber 具有监督与 scope 关系；Promise 适配无法在外部工作不配合时取消它。 | 与 prompt completion 共享 session 串行边界；Stop 必须保留 ACP owner，直到完成或确认终止。 |
-| 依赖显式声明 | v3 `Context.Tag` 标识服务，`Layer` 构造实现。 | 注入存储与执行 port，避免把整个 execution service 或其可变 map 传进新服务。 |
-
-已检查安装包的 `src/internal/core.ts`（`acquireUseRelease`）、
-`src/internal/fiberRuntime.ts`（`acquireRelease`）、`src/internal/core-effect.ts`
-（`tryPromise`）以及 `src/ManagedRuntime.ts`。对应的
-[3.18.4 源码](https://github.com/Effect-TS/effect/tree/ede2ea11c2abe7038bac3c83fb7b5eef101858d2/packages/effect/src)
+不能把使用 `Context.Service` 或 `Effect.catch` 的上游 v4 示例复制到本项目的 v3。
+CLI 规则引用的 `context/cli-effect-ts.md` 在当前 checkout 缺失。
+
+已检查安装包 `src/internal/core.ts` 的 `acquireUseRelease`、
+`src/internal/fiberRuntime.ts` 的 `acquireRelease`、
+`src/internal/core-effect.ts` 的 `tryPromise`，以及 `ManagedRuntime` API。
+对应的 [3.18.4 源码](https://github.com/Effect-TS/effect/tree/ede2ea11c2abe7038bac3c83fb7b5eef101858d2/packages/effect/src)
是 API 依据。另已阅读上游 v3 的
[资源测试](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/acquire-release.test.ts)
与[中断测试](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/interruption.test.ts)
-作为补充语义证据；未运行这些测试，也未假定它们与固定版本完全相同。
-
-## 拟议边界
-
-UI 为选中的行传入 `{ sessionId, queueItemId, expectedTurnId }`，展示结果，无需选择
-provider 交付方式。daemon operation 验证这些标识与编辑归属，再由
-`QueueSteerService` 内部选择 native delivery 或 cancel-and-dispatch。Effect 在服务
-内部负责组合、类型化失败、lease 与 finalization。
-
-`SessionExecutionService` 保留 live turn 的所有权，暴露窄执行操作。它不应仅为推进
-queue recovery journal 而接收 queue phase 或 `onSubmitting` 等回调。队列存储保留
-现有 history 与 activation 发布责任。request handler 在一个边界把 Effect 结果转换
-为现有响应协议。
-
-native preparation、provider submission、确认后的所有权交接与回执完成组成一条
-交付链；cancel-and-dispatch 组成另一条。用 `Effect.gen` 表达顺序，以 tagged recovery
-handler 处理特定可恢复失败。仅把现有 async 方法包进 `Effect.tryPromise` 不会改变
-生命周期归属。
-
-当前 renderer 还兼容旧 daemon，实现前需要使这项兼容策略与单 operation UI 一致：
-保留兼容需要将 legacy 行为封装到 UI 下层；移除兼容则需要更新 draft
-[交互 Spec](../../../../specs/message-queue-interactions.md) 与兼容性测试。
-本次研究没有隐式移除这项能力。
-
-## 恢复边界
-
-finalizer 释放拥有的资源，无法撤销 provider 已接受的交付。类型化的 provider 拒绝
-可以允许普通 dispatch；交付不确定则不允许。不能对整个交付 operation 使用
-`Effect.retry`，也不能把 timeout 或 interruption 当成未交付的证据。
-
-保留[原决策](../../implemented/feature/2026-09-13-queue-steer-controls.md)中的
-machine-local 恢复证据与保守重放规则，将其归属迁移到 operation service；不为每个
-Effect 步骤新增 durable phase。核心 `Scope` 清理无法跨越进程死亡。引入 workflow
-engine 是独立的依赖与架构决策，仅为表达这两条交付链无需引入它。
+作为补充证据；未运行它们，也未假定它们与固定版本完全相同。
+
+## 职责边界
+
+| 归属 | 责任 |
+| --------------------- | -------------------------------------------------------------------------------------------------------------- |
+| UI | 为所选行传入 `{ sessionId, queueItemId, expectedTurnId }`，展示结果。 |
+| `QueueSteerService` | 精确队列项选择、验证、持久恢复证据、fallback 策略、结果与回执。 |
+| `ActiveTurnSteerPort` | live turn ownership、provider native submission、prompt handoff，以及与 Stop 和其他 active turn 操作的串行化。 |
+| 队列存储 | 现有 history 与 activation 发布责任。 |
+| 集成边界 | 通过 `Layer` 提供 v3 `Context.Tag` 服务，执行组合后的 operation，将结果映射到响应协议。 |
+
+active turn 实现留在 execution owner。QueueSteerService 不得访问
+`runtime.session.agentClient`、runtime map、`promptInFlight`、`successor` 或
+`invocation`。port 从活动 invocation 派生冻结的 requester identity，并在自己的串行边界
+内验证 expected turn；调用方验证不能替代这个检查。
+
+native operation 暴露领域结果，概念契约如下：
+
+```ts
+interface ActiveTurnSteerPort {
+ steer(input: {
+ sessionId: SessionId;
+ expectedTurnId: string;
+ turn: SteerTurn;
+ }): Effect.Effect;
+}
+```
+
+`SteerTurn` 是经过验证的不可变 turn 数据，不是 runtime handle。
+`NativeSteerApplied` 证明本地 handoff 成功，不代表 prompt 已完成。
+`StaleTurn` 证明在提交前拒绝；提交后失去 ownership 不能报告为这种安全拒绝。
+
+这是 native operation 的契约，不是全部 execution operation 的完整接口。native 支持
+查询和 expected-turn cancellation 也由 execution owner 的操作封装。
+QueueSteerService 选择策略，无需检查 provider client。禁止暴露
+`onSubmitting`、`onAcknowledged`、`onApplied`、`onUndelivered` 回调来推进
+queue journal。新服务不能只是把现有依赖 runtime 的代码换个文件。
+
+## 资源与失败模型
+
+`Effect` 描述惰性计算，显式声明预期失败与依赖。用 `Effect.gen`
+组合 operation，在策略所属层以类型化 handler 恢复。仅把现有 async workflow 包进
+一个 `Effect.tryPromise` 不会改变生命周期归属。
+
+rewrite lease 与本地 live-turn ownership/serialization guard 归属 `Scope`。
+provider submission 是不可撤销的外部副作用，不属于可 release 的资源。顺序是获取本地
+ownership、提交 provider 副作用，再在契约允许时释放本地 ownership。finalizer 防止
+本地 ownership 泄漏，不证明 provider 没执行。现有 adapter acknowledgment handle
+也仅是本地同步资源，留在 port 内部。
+
+预期错误模型分为三类：
+
+| 类别 | 证据与示例 | 恢复策略 |
+| ---------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Safe rejection | 确定 provider 没执行：`ProviderRejected`、提交前的 `StaleTurn`。 | 仅在 operation 前提仍成立时才有资格 fallback/retry。过期、缺失或编辑中的选择仍是失败且无副作用，不得停止 turn。 |
+| Indeterminate delivery | `ProviderDeliveryUnknown`：提交可能已执行，包括确认或 handoff 不确定。 | 向上传递失败，不设 fallback handler，禁止 replay。 |
+| Local failure | `PersistenceFailure`、验证或 lease 获取失败。 | 根据 durable evidence 恢复；本地错误本身不证明未交付。 |
+
+使用独立的 v3 `Data.TaggedError` 类表达 `ProviderRejected`、
+`ProviderDeliveryUnknown` 与 `PersistenceFailure`。native port 对交付证据分类，
+operation 的持久化边界负责 `PersistenceFailure`。提交后的本地失败必须保留可能已交付
+这一事实，不能改标成 `ProviderRejected`。
+
+策略 handler 是 `Effect.catchTag("ProviderRejected", fallbackToDispatch)`。
+`ProviderDeliveryUnknown` 没有对应的 fallback handler。defect 与 interruption
+仍通过 `Cause`/`Exit` 区分；timeout 或 Promise 中断都不能证明 provider 没执行。
+不得重试整个交付 operation。
+
+## 持久化与 capability 策略
+
+QueueSteerService 拥有持久恢复证据：在进入可能提交的 port 调用前持久化 write-ahead
+证据，取得结果后持久化回执。若在这两个边界之间崩溃，除非权威证据证明其他结果，否则
+保守地视为交付不确定。journal 契约的实现不得引入 phase callback 或暴露 live runtime
+状态。保留[原决策](../../implemented/feature/2026-09-13-queue-steer-controls.md)中
+已有 marker 的恢复与保守重放保证；不为每个 Effect 步骤增加 durable phase。
+
+核心 Scope 清理无法跨越进程死亡。Stop 必须保留 ACP owner，直到原始调用完成或确认
+终止；外部工作不配合时，Promise 包装无法取消它。引入 workflow engine 是独立架构
+决策，不是这两条交付链的必需条件。
+
+队列 Steer 不兼容旧 daemon。未声明受支持的 `queueItemSteer` 版本时，所有行的
+Steer 都不可用，包括队首。不得退回 renderer 写历史、legacy native Steer 或队首
+cancel。支持该协议的 daemon 上，每一行传自己的队列标识，由 daemon 选择 native
+delivery 或 cancel-and-dispatch。
+
+这仅替代原决策中队列 Steer 的旧 daemon 兼容策略，composer 提交行为不在本次变更内。
+draft [交互 Spec](../../../../specs/message-queue-interactions.md) 记录修订后的意图；
+renderer 当前仍包含旧路径。
## 待完成的验证
-实现须保留可观察行为覆盖：选择 C 后 A/B 顺序不变、队列项缺失或编辑中、expected turn
-过期、native 接受或拒绝、Stop 与 acknowledgment 竞态、持久化失败，以及响应丢失和
-重启恢复。新增确定性失败与中断验证，证明 lease 会释放，同时不会放弃仍在运行的 ACP
-owner。验证 UI 通过单 operation 调用，并在选定边界验证旧版本兼容。
+保留选择 C 后 A/B 顺序不变、队列项缺失或编辑中、expected turn 过期、native
+接受/拒绝、Stop 与 acknowledgment 竞态、持久化失败及响应丢失/重启恢复的行为覆盖。
+验证三类错误：只有满足前提的安全拒绝才进入 fallback dispatch；交付不确定绝不
+replay；本地失败根据 durable evidence 恢复。确定性失败/中断测试须证明本地 guard
+会释放，且不会放弃仍在运行的 ACP owner。不支持协议的 daemon 上，任何行都不得有
+可用的队列 Steer 操作，也不得发出 legacy submission 或 cancellation。
-本 note 仅记录源码研究与拟议拆分。业务代码、依赖版本及现有 Spec 均未修改；未为此
-提案运行 runtime 测试。
+业务代码与依赖版本均未修改。修订后的设计与 Spec 不代表实现证据；未运行 runtime 测试。
diff --git a/specs/message-queue-interactions.md b/specs/message-queue-interactions.md
index 6b25e7535..f5bd884d4 100644
--- a/specs/message-queue-interactions.md
+++ b/specs/message-queue-interactions.md
@@ -26,16 +26,26 @@ the queue by hand.
durable queue identity and expected active turn. The daemon, not the renderer, chooses the
execution mechanism:
- | Active daemon/runtime | Steer behavior |
- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
- | Exact-item protocol and acknowledged native ACP Steer | Reserve the selected row as `pending_apply`, retain it through the durable handoff saga, then inject it through `steerPrompt`. |
- | Exact-item protocol without native ACP Steer | Persist and activate the selected row as the next user turn, remove it from the queue, then stop only the expected turn. |
- | Older daemon with authoritative acknowledged native ACP Steer | Preserve the legacy native Steer path. |
- | Older daemon without acknowledged native ACP Steer | Keep the established queue-head interrupt behavior; disable Steer on later rows and require a daemon update for exact selection. |
-
- No compatibility path may reorder a later item and then cancel. Selecting C from
+ | Active daemon/runtime | Steer behavior |
+ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+ | Exact-item protocol and acknowledged native ACP Steer | Reserve the selected row as `pending_apply`, retain it through the durable handoff saga, then inject it through `steerPrompt`. |
+ | Exact-item protocol without native ACP Steer | Persist and activate the selected row as the next user turn, remove it from the queue, then stop only the expected turn. |
+ | No supported `queueItemSteer` capability | Queue Steer is unavailable on every row, including the head, regardless of native ACP capability. |
+
+ Queue Steer provides no old-daemon compatibility path: no renderer-side history
+ materialization, legacy native Steer, or queue-head cancellation. The UI exposes one
+ exact-item operation and does not choose provider delivery. Selecting C from
`[A, B, C]` through the exact protocol consumes C and leaves `[A, B]` in that order.
+ `QueueSteerService` owns exact selection, validation, durable recovery evidence, fallback
+ policy, and results/receipts. `ActiveTurnSteerPort` owns live-turn ownership, native provider
+ submission, prompt handoff, and serialization with Stop. The queue operation never accesses
+ runtime maps or the provider client and receives domain results rather than phase callbacks.
+ Local ownership guards may be scoped resources; provider submission is an irreversible
+ external side effect. Only proven non-delivery is eligible for fallback, subject to operation
+ preconditions. Indeterminate delivery must propagate without replay; local failures recover
+ from durable evidence and never imply non-delivery by themselves.
+
A remote renderer must authorize the target before writing the request, using its
authenticated authoritative machine-access snapshot and failing closed if that snapshot is
unavailable. The request carries no requester identity: workspace Machine RPC cannot
@@ -90,6 +100,12 @@ reported, never silently replayed.
## Implementation evidence
+The service/port split and capability-only availability above are intended changes, not
+completed implementation. The renderer still contains old-daemon native/head paths and the
+execution service still owns queue orchestration. Removal and regression verification remain
+pending under the [Effect boundary proposal](../.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md).
+The new availability policy applies to queued-row Steer, not composer submission routing.
+
- `packages/components/src/components/sessions/session-message-submit-route.ts`
- `packages/components/src/components/sessions/session-chat-input-area.tsx`
- `packages/components/src/components/sessions/message-queue/`
diff --git a/specs/message-queue-interactions.zh.md b/specs/message-queue-interactions.zh.md
index b4935784a..9a16f8a4f 100644
--- a/specs/message-queue-interactions.zh.md
+++ b/specs/message-queue-interactions.zh.md
@@ -21,16 +21,25 @@ Translation: current
`session/queue-steer`；缺少 capability 即表示不支持。请求携带持久队列 ID 和预期活动 turn，
具体执行方式由 daemon 而非 Renderer 决定：
- | 当前 daemon/runtime | 引导行为 |
- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
- | 支持精确队列项协议，且支持 acknowledged native ACP Steer | 将目标保留为 `pending_apply`，通过持久 handoff saga 后由 `steerPrompt` 注入。 |
- | 支持精确队列项协议，但不支持 native ACP Steer | 将目标行持久化并激活为下一用户 turn，从队列删除后再只停止预期 turn。 |
- | 旧 daemon，但 authoritative capability 声明支持 acknowledged native ACP Steer | 保留旧版真正 native Steer 路径。 |
- | 旧 daemon，且不支持 acknowledged native ACP Steer | 仅保留既有队首 interrupt 行为；禁用后续行“引导”，并要求升级 daemon 才能精确选择。 |
-
- 任何兼容路径都不得先重排后续项再取消。从 `[A, B, C]` 通过精确协议选择 C 时，只消费 C，
+ | 当前 daemon/runtime | 引导行为 |
+ | -------------------------------------------------------- | ----------------------------------------------------------------------------- |
+ | 支持精确队列项协议，且支持 acknowledged native ACP Steer | 将目标保留为 `pending_apply`，通过持久 handoff saga 后由 `steerPrompt` 注入。 |
+ | 支持精确队列项协议，但不支持 native ACP Steer | 将目标行持久化并激活为下一用户 turn，从队列删除后再只停止预期 turn。 |
+ | 未声明受支持的 `queueItemSteer` capability | 所有行的队列“引导”均不可用，包括队首；不因 native ACP capability 而例外。 |
+
+ 队列“引导”不提供旧 daemon 兼容路径：不允许 renderer 写历史、legacy native Steer 或
+ 队首取消。UI 只暴露一个精确队列项 operation，不选择 provider 交付方式。
+ 从 `[A, B, C]` 通过精确协议选择 C 时，只消费 C，
剩余队列保持 `[A, B]`。
+ `QueueSteerService` 负责精确选择、验证、持久恢复证据、fallback 策略和结果/回执。
+ `ActiveTurnSteerPort` 负责 live turn ownership、native provider 提交、prompt handoff
+ 以及与 Stop 的串行化。队列 operation 不得访问 runtime map 或 provider client，接收
+ 领域结果而非 phase callback。本地 ownership guard 可作为 scope 资源；provider 提交是
+ 不可撤销的外部副作用。只有证明未交付且 operation 前提仍成立时才有资格 fallback。
+ 交付不确定须向上传递，禁止 replay；本地失败依据 durable evidence 恢复，不能仅凭本地
+ 失败推断未交付。
+
远程 Renderer 在写入请求前，必须使用其已认证的权威 machine-access 快照验证目标；快照
不可用时应 fail closed。请求不得携带请求者身份：workspace Machine RPC 无法认证调用方
声称的成员 ID，目标 daemon 也不得用它命中 owner fast path。同机 local IPC 已是可信的
@@ -74,6 +83,11 @@ Translation: current
## 实现证据
+上述 service/port 拆分与仅按 capability 开放能力是待实现的意图变更。renderer 仍包含
+旧 daemon 的 native/head 路径，execution service 仍拥有队列编排。移除旧路径与回归验证
+待按 [Effect 边界提案](../.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md)
+完成。新的可用性策略只适用于队列行“引导”，不改变 composer 提交路由。
+
- `packages/components/src/components/sessions/session-message-submit-route.ts`
- `packages/components/src/components/sessions/session-chat-input-area.tsx`
- `packages/components/src/components/sessions/message-queue/`
From 6964227412daed5ef8c905f951eaafdcb1be2236 Mon Sep 17 00:00:00 2001
From: wibus-wee <62133302+wibus-wee@users.noreply.github.com>
Date: Mon, 14 Sep 2026 16:03:35 +0800
Subject: [PATCH 10/15] docs: correct queue steer reservation ownership
contract
Model: gpt-6
---
.../2026-09-14-queue-steer-effect-boundary.md | 64 +++++++++++++++---
...26-09-14-queue-steer-effect-boundary.zh.md | 53 +++++++++++++--
specs/message-queue-interactions.md | 67 ++++++++++++++-----
specs/message-queue-interactions.zh.md | 58 ++++++++++++----
4 files changed, 196 insertions(+), 46 deletions(-)
diff --git a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md
index 9966bde2e..fd9b0f427 100644
--- a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md
+++ b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md
@@ -12,7 +12,9 @@ operation bookkeeping across `SessionExecutionService`. The proposed boundary
gives `QueueSteerService` exact selection, validation, durable recovery evidence,
fallback policy, and results; `ActiveTurnSteerPort` owns native submission and
live-turn handoff. Effect expresses local resource lifetimes and typed failure
-semantics without making provider submission reversible. Queue Steer requires a
+semantics without making provider submission reversible. Native reservation transfers
+the item out of editable Queue ownership; frozen history and queue removal must be durable
+before provider submission. Queue Steer requires a
supported `queueItemSteer` capability, with no old-daemon compatibility path.
The design is revised; implementation and behavioral verification remain pending.
@@ -118,14 +120,50 @@ Do not retry the complete delivery operation.
## Durability and capability policy
-QueueSteerService owns durable recovery evidence, including write-ahead evidence
-before entering a potentially submitting port call and durable receipts after its
-result. A crash between these boundaries remains conservatively indeterminate
-unless authoritative evidence proves otherwise. Implement the journal contract
-without phase callbacks or exposing live runtime state. Preserve recovery of the
-existing markers and fail-closed replay guarantees from the
-[original decision](../../implemented/feature/2026-09-13-queue-steer-controls.md);
-do not add a durable phase for every Effect step.
+Keeping an editable queue row after freezing its history permits a lost edit:
+another client saves changed content, native delivery executes the earlier snapshot,
+then row deletion discards the accepted edit. The current native consumption path in
+`SessionDocument.consumeMessageQueueItemAsUserTurn` retains the row, and
+`updateMessageQueueItem` does not check operation ownership. This is an ownership
+contract defect, not merely a missing cleanup step.
+
+The [Spec](../../../../specs/message-queue-interactions.md) now assigns the item to
+the daemon-owned operation when reservation succeeds. The selected sequence is:
+
+```text
+validate and claim exclusive reservation ownership
+→ durable reservation marker
+→ append frozen pending_apply history → history durable
+→ remove selected shared Queue row → removal durable
+→ write-ahead submission evidence
+→ ActiveTurnSteerPort.steer(frozen turn)
+→ durable result / receipt
+```
+
+The queue write authority must serialize reservation with ordinary edit/remove/reorder
+and promotion, including while persistence is awaited. An edit committed first is
+included or causes reservation rejection. Reservation winning first rejects later
+mutations visibly, retaining an editor's draft. A stale client must not receive a
+successful no-op save. A machine-local marker or disabling buttons in one renderer
+cannot by itself enforce this across clients; all mutation paths need the same authority.
+The implementation of that boundary remains pending, and early row removal alone does
+not establish it.
+
+QueueSteerService owns the journal and receipts. Recovery uses its machine-local marker
+and frozen history, not an editable queue row. Before history becomes durable, recovery
+reconciles the reservation as unsubmitted before returning any surviving row to editing.
+After history is durable, recovery can finish removal and recover that same turn even if
+the row is absent. A failed removal commit prevents provider submission. After write-ahead
+submission evidence, a crash remains conservatively indeterminate unless authoritative
+evidence proves otherwise. Reserved-operation retries resolve through the marker or
+receipt rather than ordinary missing-row validation.
+
+Implement these boundaries without phase callbacks or exposing live runtime state.
+Preserve recovery of existing markers and their fail-closed replay guarantees from the
+[original decision](../../implemented/feature/2026-09-13-queue-steer-controls.md), but
+supersede its requirement to retain the shared row until delivery finishes. Reconcile any
+legacy surviving row without deleting accepted edits. Do not add a durable phase for every
+Effect step. The exact ownership, ordering, and failure guarantees have one owner in the Spec.
Core Scope cleanup cannot survive process death. Stop must retain the ACP owner
until raw completion or confirmed termination; a Promise wrapper cannot cancel
@@ -154,5 +192,13 @@ failure/interruption tests must prove local guards release without relinquishing
a still-running ACP owner. Unsupported daemons must expose no usable queue Steer
action on any row and issue no legacy submission or cancellation.
+Add two-client tests for both orderings of reservation versus edit/save/remove/reorder,
+including a stale client that has not observed removal. A rejected save must retain its draft;
+an accepted edit must not disappear behind the frozen prompt. Exercise failure/crash boundaries
+before history durability, between history and removal durability, and after durable removal
+before submission. Prove provider submission waits for durable removal, ordinary promotion
+cannot consume the reserved row, and recovery succeeds with marker plus history while the row
+is absent. Existing row-retention tests must be revised to the ownership-transfer contract.
+
Business code and dependency versions are unchanged. This revised design and
Spec are not implementation evidence; no runtime tests were executed.
diff --git a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
index 87f1a58f1..8d7b8fff8 100644
--- a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
+++ b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
@@ -11,7 +11,9 @@ Translation: current
`SessionExecutionService`。拟议边界由 `QueueSteerService` 负责精确选择、验证、
持久恢复证据、fallback 策略与结果；`ActiveTurnSteerPort` 负责 native 提交和 live turn
交接。Effect 表达本地资源生命周期与类型化失败语义，不会让 provider 提交变得可撤销。
-队列 Steer 必须具备受支持的 `queueItemSteer` capability，不提供旧 daemon 兼容路径。
+Native reservation 将目标移出可编辑 Queue ownership；冻结 history 与队列删除都必须
+在 provider 提交前持久化。队列 Steer 必须具备受支持的 `queueItemSteer` capability，
+不提供旧 daemon 兼容路径。
设计已修订，实现与行为验证仍待完成。
## 源码证据
@@ -106,11 +108,43 @@ operation 的持久化边界负责 `PersistenceFailure`。提交后的本地失
## 持久化与 capability 策略
-QueueSteerService 拥有持久恢复证据：在进入可能提交的 port 调用前持久化 write-ahead
-证据，取得结果后持久化回执。若在这两个边界之间崩溃，除非权威证据证明其他结果，否则
-保守地视为交付不确定。journal 契约的实现不得引入 phase callback 或暴露 live runtime
-状态。保留[原决策](../../implemented/feature/2026-09-13-queue-steer-controls.md)中
-已有 marker 的恢复与保守重放保证；不为每个 Effect 步骤增加 durable phase。
+冻结 history 后保留可编辑 queue row 会丢失编辑：另一客户端保存新内容，native
+delivery 执行先前快照，随后删除 row 丢掉已接受的编辑。当前
+`SessionDocument.consumeMessageQueueItemAsUserTurn` 的 native 消费路径保留 row，
+而 `updateMessageQueueItem` 没有检查 operation ownership。这是 ownership 契约错误，
+不仅是缺少清理步骤。
+
+[Spec](../../../../specs/message-queue-interactions.md) 现规定 reservation 成功时，
+目标归属 daemon-owned operation。选定顺序为：
+
+```text
+验证并取得排他 reservation ownership
+→ 持久化 reservation marker
+→ 追加冻结的 pending_apply history → history 持久化
+→ 删除共享 Queue 中的所选 row → 删除持久化
+→ write-ahead submission 证据
+→ ActiveTurnSteerPort.steer(frozen turn)
+→ 持久化结果 / 回执
+```
+
+队列权威写入端必须让 reservation 与普通 edit/remove/reorder、promotion 串行化，
+包括等待持久化期间。编辑先提交则纳入快照或使 reservation 拒绝；reservation 先成功，
+后续修改须明确拒绝，并保留编辑器草稿。旧客户端不能收到实际无操作的保存成功。
+仅凭 machine-local marker 或在一个 renderer 禁用按钮无法跨客户端保证这一点；
+所有修改路径都需要同一个权威边界。该边界的实现仍待完成，提前删除 row 本身不能建立它。
+
+QueueSteerService 拥有 journal 与回执。恢复依赖 machine-local marker 和冻结 history，
+不再依赖可编辑 queue row。history 持久化前，恢复须先将 reservation 对账为未提交，
+再让残留 row 恢复可编辑。history 持久化后，即使 row 已不存在，也能完成删除并恢复
+同一个 turn。删除持久化失败则禁止提交 provider。write-ahead submission 证据写入后
+发生崩溃，除非权威证据证明其他结果，否则保守地视为交付不确定。reserved operation
+的重试通过 marker 或 receipt 解析，不走普通缺失 row 验证。
+
+实现这些边界不得引入 phase callback 或暴露 live runtime 状态。
+保留[原决策](../../implemented/feature/2026-09-13-queue-steer-controls.md)中已有
+marker 的恢复与保守重放保证，但替代其“共享 row 保留到交付完成”的要求。旧版本残留
+row 的对账不能删除已接受的编辑。不为每个 Effect 步骤增加 durable phase。
+精确 ownership、顺序与失败保证统一由 Spec 定义。
核心 Scope 清理无法跨越进程死亡。Stop 必须保留 ACP owner，直到原始调用完成或确认
终止；外部工作不配合时，Promise 包装无法取消它。引入 workflow engine 是独立架构
@@ -134,4 +168,11 @@ replay；本地失败根据 durable evidence 恢复。确定性失败/中断测
会释放，且不会放弃仍在运行的 ACP owner。不支持协议的 daemon 上，任何行都不得有
可用的队列 Steer 操作，也不得发出 legacy submission 或 cancellation。
+新增双客户端测试覆盖 reservation 与 edit/save/remove/reorder 的两种先后顺序，
+包括尚未观察到删除的旧客户端。拒绝保存须保留草稿；已接受编辑不能因冻结 prompt 而
+消失。覆盖 history 持久化前、history 与删除持久化之间、删除持久化后但提交前的失败/
+崩溃边界。证明 provider 提交等待删除持久化、普通 promotion 不会消费 reserved row，
+且 row 不存在时仍可凭 marker 与 history 恢复。现有保留 row 的测试须按 ownership
+转移契约修订。
+
业务代码与依赖版本均未修改。修订后的设计与 Spec 不代表实现证据；未运行 runtime 测试。
diff --git a/specs/message-queue-interactions.md b/specs/message-queue-interactions.md
index f5bd884d4..e42a58612 100644
--- a/specs/message-queue-interactions.md
+++ b/specs/message-queue-interactions.md
@@ -26,11 +26,11 @@ the queue by hand.
durable queue identity and expected active turn. The daemon, not the renderer, chooses the
execution mechanism:
- | Active daemon/runtime | Steer behavior |
- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
- | Exact-item protocol and acknowledged native ACP Steer | Reserve the selected row as `pending_apply`, retain it through the durable handoff saga, then inject it through `steerPrompt`. |
- | Exact-item protocol without native ACP Steer | Persist and activate the selected row as the next user turn, remove it from the queue, then stop only the expected turn. |
- | No supported `queueItemSteer` capability | Queue Steer is unavailable on every row, including the head, regardless of native ACP capability. |
+ | Active daemon/runtime | Steer behavior |
+ | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+ | Exact-item protocol and acknowledged native ACP Steer | Transfer the selected item to a daemon-owned operation, persist its `pending_apply` history and queue removal, then call native Steer. |
+ | Exact-item protocol without native ACP Steer | Persist and activate the selected row as the next user turn, remove it from the queue, then stop only the expected turn. |
+ | No supported `queueItemSteer` capability | Queue Steer is unavailable on every row, including the head, regardless of native ACP capability. |
Queue Steer provides no old-daemon compatibility path: no renderer-side history
materialization, legacy native Steer, or queue-head cancellation. The UI exposes one
@@ -56,12 +56,40 @@ the queue by hand.
invocation, never from the shared queue row. If that frozen identity is unavailable, the
daemon fails before consuming the row, submitting to the provider, or stopping the turn.
- Native handoff is a durable saga, not an atomic CRDT/provider operation. A machine-local,
- daemon-owned marker records `reserved`, write-ahead `submitting`, provider `acknowledged`,
- locally committed `applied`, or `fallback`, and keeps the selected queue row until the result
- is durable. A `reserved` entry that reached history, or any `fallback`, may become the exact
- ordinary turn;
- a reservation interrupted before history leaves the row queued. `submitting` is indeterminate
+ Successful native Steer reservation transfers the selected item's ownership from the shared
+ editable Queue to the daemon-owned Steer operation. From that point ordinary edit, remove,
+ reorder, and queue promotion cannot mutate or consume it, even if another client still
+ displays a stale row. Reservation and ordinary mutations must share an authoritative
+ ownership boundary: an edit committed first is included in the validated snapshot (or causes
+ reservation to reject); a reservation that wins first causes later mutations to reject visibly.
+ A rejected edit retains the user's draft. Neither optimistic UI success nor a client-local
+ editing lease proves that an edit was accepted by that authority.
+
+ The native submission order is:
+ 1. Validate the selected identity, content, editing ownership, and expected turn; establish
+ exclusive reservation ownership against concurrent ordinary queue mutations.
+ 2. Persist the daemon-owned reservation marker.
+ 3. Append the frozen turn as `pending_apply` and make that history durable.
+ 4. Remove the selected row from the shared Queue and make its removal durable.
+ 5. Persist write-ahead submission evidence, then invoke `ActiveTurnSteerPort.steer` with
+ the frozen turn. The port revalidates live-turn ownership before provider submission.
+
+ Any failure to persist the reservation, history, or removal forbids provider submission.
+ Removing the row before the network call is necessary but does not replace the ownership
+ boundary during steps 1–4. Native recovery uses the machine-local marker plus frozen history,
+ not an editable queue row as a retry token. A pre-history reservation interrupted by a crash
+ must be reconciled as unsubmitted before its surviving row becomes editable again; it must not
+ report a stale edit as saved or construct a turn from later queue content. Once history is
+ durable, recovery can finish removal and recover the same turn without requiring the row to
+ exist. A new missing-row request still fails; replay of the same reserved operation resolves
+ through its marker or receipt.
+
+ Native handoff remains non-atomic across storage and provider side effects. Existing
+ machine-local markers record `reserved`, write-ahead `submitting`, provider `acknowledged`,
+ locally committed `applied`, or `fallback`; their recovery must remain supported. A `reserved`
+ entry that reached history, or a `fallback`, may become the exact ordinary turn after queue
+ removal is durable. A surviving row from an older operation is reconciled under the same
+ ownership boundary, never blindly deleted over an accepted edit. `submitting` is indeterminate
and `acknowledged` may already have side effects, so neither is replayed after its prompt owner
disappears. `applied` proves local handoff and recovers as accepted while ordinary crash
handling makes an interrupted turn visible. This is the fail-closed boundary required because
@@ -71,7 +99,7 @@ the queue by hand.
history first, publish `latestUserMsgId`, and remove the row only after both writes succeed.
A retry after partial publication reuses the existing turn ID rather than duplicating history.
-- A stale or conflicting exact Steer selection is a failed no-op. If the selected queue
+- Before reservation, a stale or conflicting exact Steer selection is a failed no-op. If the selected queue
identity is missing, its editing lease is active, or the expected turn no longer owns
execution, the daemon must not submit native Steer or stop any turn. The renderer waits for
this acknowledgement and never removes or materializes an exact-protocol row itself.
@@ -85,8 +113,9 @@ the queue by hand.
activation pointer, and queue-row cleanup are durable; failed recovery remains retryable.
- The number and non-editing message body form the drag target for queue reordering.
Steer, edit, and remove remain separate controls and must not begin a drag.
-- Editing keeps its existing keyboard and focus behavior and disables reordering for
- that row until editing ends.
+- Editing of unreserved rows keeps its existing keyboard and focus behavior and disables
+ reordering for that row until editing ends. A reserved item is operation-owned, not editable
+ queue content; stale-client edit/remove/reorder requests cannot change it or succeed silently.
## Limits and review questions
@@ -100,9 +129,13 @@ reported, never silently replayed.
## Implementation evidence
-The service/port split and capability-only availability above are intended changes, not
-completed implementation. The renderer still contains old-daemon native/head paths and the
-execution service still owns queue orchestration. Removal and regression verification remain
+The service/port split, reservation ownership transfer, pre-submission durable queue removal,
+and capability-only availability above are intended changes, not completed implementation.
+The current native path retains the editable row through provider handoff; ordinary row updates
+do not enforce operation ownership, and missing-row updates can silently succeed. This permits
+an accepted edit to disappear when handoff removes the row. The renderer also still contains
+old-daemon native/head paths and the execution service owns queue orchestration. Implementation
+and two-client mutation/crash regression verification remain
pending under the [Effect boundary proposal](../.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md).
The new availability policy applies to queued-row Steer, not composer submission routing.
diff --git a/specs/message-queue-interactions.zh.md b/specs/message-queue-interactions.zh.md
index 9a16f8a4f..904403dd2 100644
--- a/specs/message-queue-interactions.zh.md
+++ b/specs/message-queue-interactions.zh.md
@@ -21,11 +21,11 @@ Translation: current
`session/queue-steer`；缺少 capability 即表示不支持。请求携带持久队列 ID 和预期活动 turn，
具体执行方式由 daemon 而非 Renderer 决定：
- | 当前 daemon/runtime | 引导行为 |
- | -------------------------------------------------------- | ----------------------------------------------------------------------------- |
- | 支持精确队列项协议，且支持 acknowledged native ACP Steer | 将目标保留为 `pending_apply`，通过持久 handoff saga 后由 `steerPrompt` 注入。 |
- | 支持精确队列项协议，但不支持 native ACP Steer | 将目标行持久化并激活为下一用户 turn，从队列删除后再只停止预期 turn。 |
- | 未声明受支持的 `queueItemSteer` capability | 所有行的队列“引导”均不可用，包括队首；不因 native ACP capability 而例外。 |
+ | 当前 daemon/runtime | 引导行为 |
+ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+ | 支持精确队列项协议，且支持 acknowledged native ACP Steer | 将目标移交 daemon-owned operation，持久化 `pending_apply` history 与队列删除后，再调用 native Steer。 |
+ | 支持精确队列项协议，但不支持 native ACP Steer | 将目标行持久化并激活为下一用户 turn，从队列删除后再只停止预期 turn。 |
+ | 未声明受支持的 `queueItemSteer` capability | 所有行的队列“引导”均不可用，包括队首；不因 native ACP capability 而例外。 |
队列“引导”不提供旧 daemon 兼容路径：不允许 renderer 写历史、legacy native Steer 或
队首取消。UI 只暴露一个精确队列项 operation，不选择 provider 交付方式。
@@ -48,11 +48,36 @@ Translation: current
Native 精确“引导”的 requester identity 必须来自已认证的活动 invocation，绝不来自共享
queue row。若该冻结身份不可用，daemon 必须在消费 row、提交 provider 或停止 turn 之前失败。
- Native handoff 是持久 saga，而不是 CRDT 写入与 provider side effect 之间不存在的原子操作。
- machine-local、由 daemon 持有的 marker 记录 `reserved`、write-ahead `submitting`、provider `acknowledged`、本地已提交
- `applied` 或 `fallback`，且在结果持久化前保留所选 queue row。已进入 history 的 `reserved` 和
- `fallback` 可转为精确普通 turn；若 reservation 在写 history 前中断，则保留 row 在队列。
- `submitting` 结果不确定，`acknowledged` 可能已有 side effect，原 prompt owner 消失后两者都
+ Native Steer reservation 成功后，所选项的 ownership 从共享可编辑 Queue 转移到
+ daemon-owned Steer operation。此后普通 edit、remove、reorder 和队列 promotion 都不得
+ 修改或消费它，即使其他客户端仍显示旧 row。reservation 与普通修改必须共享权威 ownership
+ 边界：编辑先提交则已保存内容进入验证快照（或令 reservation 拒绝）；reservation 先成功则
+ 后续修改须明确拒绝。被拒绝的编辑保留用户草稿。乐观 UI 成功或客户端本地 editing lease
+ 都不证明权威写入端已接受编辑。
+
+ Native 提交顺序为：
+ 1. 验证目标标识、内容、编辑归属和 expected turn，并针对并发普通队列修改取得排他 reservation
+ ownership。
+ 2. 持久化 daemon-owned reservation marker。
+ 3. 将冻结 turn 追加为 `pending_apply`，并确保 history 持久化。
+ 4. 从共享 Queue 删除所选 row，并确保删除持久化。
+ 5. 持久化 write-ahead submission 证据，再将冻结 turn 传给 `ActiveTurnSteerPort.steer`。
+ port 在提交 provider 前重新验证 live turn ownership。
+
+ reservation、history 或删除任一持久化失败，都禁止提交 provider。网络调用前删除 row
+ 是必要条件，但不能替代步骤 1–4 期间的 ownership 边界。Native 恢复依赖 machine-local
+ marker 与冻结 history，不再拿可编辑 queue row 当 retry token。若在 history 持久化前
+ 崩溃，须先将 reservation 对账为未提交，剩余 row 才能恢复可编辑；不得把旧客户端编辑
+ 报成保存成功，也不得从后来的 queue 内容构建 turn。history 持久化后，恢复可完成删除并
+ 恢复同一个 turn，无需 row 仍存在。新的缺失 row 请求仍失败；同一 reserved operation
+ 的重试通过 marker 或 receipt 解析。
+
+ Native handoff 在存储与 provider 副作用之间仍非原子操作。已有 machine-local marker
+ 记录 `reserved`、write-ahead `submitting`、provider `acknowledged`、本地已提交
+ `applied` 或 `fallback`，须继续支持其恢复。已进入 history 的 `reserved` 或 `fallback`
+ 可在队列删除持久化后转为精确普通 turn。旧 operation 残留的 row 须在同一 ownership
+ 边界下对账，绝不能覆盖已接受编辑而盲目删除。`submitting` 结果不确定，
+ `acknowledged` 可能已有 side effect，原 prompt owner 消失后两者都
不得重放，而应落成可见失败。`applied` 证明本地 handoff 已完成，应恢复 accepted 回执，并由
普通 crash handling 显示被中断的 turn。ACP 没有幂等提交键或交付查询，因此这里必须 fail closed。
@@ -60,7 +85,7 @@ Translation: current
`latestUserMsgId`，且仅在两项写入都成功后删除 row。部分发布后的重试应复用已有 turn ID，
不得重复追加 history。
-- 过期或冲突的精确“引导”选择必须失败且无副作用。所选 ID 已不存在、编辑 lease 仍有效，或
+- reservation 前，过期或冲突的精确“引导”选择必须失败且无副作用。所选 ID 已不存在、编辑 lease 仍有效，或
预期 turn 已不再拥有执行权时，daemon 不得提交 native Steer，也不得停止任何 turn。Renderer
等待确认，不自行移除队列项或为精确协议写历史。
- daemon 会按 session、预期 turn 和队列 ID，为最近已消费的精确请求保留有界内存 receipt；
@@ -72,7 +97,9 @@ Translation: current
失败必须保持可重试。
- 序号和非编辑状态的消息正文共同组成队列重排拖动区域。“引导”、“编辑”和“移除”是独立
控件，不能触发拖动。
-- 编辑状态保留已有键盘与焦点行为，并在编辑结束前禁用该行重排。
+- 未被 reservation 的 row 保留已有编辑键盘与焦点行为，并在编辑结束前禁用该行重排。
+ reserved 项属于 operation，不再是可编辑队列内容；旧客户端的 edit/remove/reorder
+ 请求不得修改它，也不得静默成功。
## 边界与待审事项
@@ -83,8 +110,11 @@ Translation: current
## 实现证据
-上述 service/port 拆分与仅按 capability 开放能力是待实现的意图变更。renderer 仍包含
-旧 daemon 的 native/head 路径，execution service 仍拥有队列编排。移除旧路径与回归验证
+上述 service/port 拆分、reservation ownership 转移、提交前持久化删除队列项及仅按
+capability 开放能力均是待实现的意图变更。当前 native 路径仍保留可编辑 row 直到 provider
+handoff；普通 row 更新没有 operation ownership 检查，更新缺失 row 也可能静默成功。
+因此已接受的编辑可能在 handoff 删除 row 时丢失。renderer 也仍包含旧 daemon 的
+native/head 路径，execution service 仍拥有队列编排。实现及双客户端修改/崩溃回归验证
待按 [Effect 边界提案](../.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md)
完成。新的可用性策略只适用于队列行“引导”，不改变 composer 提交路由。
From c4afc9f16dd8bb36f98a378a327d9f58404a3107 Mon Sep 17 00:00:00 2001
From: wibus-wee <62133302+wibus-wee@users.noreply.github.com>
Date: Mon, 14 Sep 2026 17:07:13 +0800
Subject: [PATCH 11/15] fix: enforce queue steer ownership with Effect
lifecycle
Separate queue delivery policy from live turn ownership, serialize revision-checked queue mutations, and persist removal before native submission. Remove legacy daemon steering paths and retain conflicting edit drafts.
Model: gpt-6
---
.agents/docs/rpc-loro-streams-rpc.md | 7 +-
.../2026-09-14-queue-steer-effect-boundary.md | 112 ++
...26-09-14-queue-steer-effect-boundary.zh.md | 102 ++
.../2026-09-14-queue-steer-effect-boundary.md | 204 ---
...26-09-14-queue-steer-effect-boundary.zh.md | 178 ---
apps/cli/src/lib/AGENTS.md | 12 +-
apps/cli/src/lib/loro/doc-user-turn.test.ts | 34 +
apps/cli/src/lib/loro/doc.ts | 121 +-
apps/cli/src/lib/message-handler.ts | 3 +
apps/cli/src/session/AGENTS.md | 10 +-
apps/cli/src/session/README.md | 13 +-
.../cli/src/session/active-turn-steer-port.ts | 57 +
apps/cli/src/session/queue-steer-service.ts | 503 +++++++
.../src/session/session-execution-service.ts | 1219 ++++++-----------
...ession-queue-steer-operation-store.test.ts | 2 +-
.../session-queue-steer-operation-store.ts | 3 +-
.../tests/session-execution-service.test.ts | 404 +++++-
locales/en.json | 2 +-
locales/zh_CN.json | 2 +-
.../sessions/message-queue/AGENTS.md | 6 +-
.../sessions/message-queue/index.ts | 5 -
.../message-queue/message-queue-display.tsx | 21 +-
.../queued-message-steer-compat.ts | 26 -
.../use-message-queue-editing.ts | 47 +-
.../sessions/session-chat-interface.tsx | 186 +--
.../components/src/hooks/use-session-doc.ts | 14 +-
packages/components/src/providers/AGENTS.md | 3 +
.../src/providers/create-workspace-runtime.ts | 19 +-
.../providers/workspace-machine-rpc-facade.ts | 37 +
.../src/providers/workspace-writer-impl.ts | 71 +-
.../src/providers/workspace-writer.ts | 11 +-
.../tests/message-queue-row-editing.test.tsx | 50 +
.../tests/queued-message-steer.test.ts | 49 -
.../workspace-machine-rpc-facade.test.ts | 58 +
.../components/tests/workspace-writer.test.ts | 37 +
packages/loro-streams-rpc/AGENTS.md | 2 +-
.../src/machine-rpc-server.ts | 15 +
packages/loro-streams-rpc/src/rpc.ts | 39 +
packages/shared/src/index.ts | 1 +
packages/shared/src/local-machine-rpc.ts | 9 +
.../src/machine-protocol-capabilities.ts | 4 +-
packages/shared/src/session-queue-mutation.ts | 50 +
.../shared/tests/local-machine-rpc.test.ts | 26 +
.../machine-protocol-capabilities.test.ts | 3 +
specs/message-queue-interactions.md | 20 +-
specs/message-queue-interactions.zh.md | 18 +-
46 files changed, 2200 insertions(+), 1615 deletions(-)
create mode 100644 .agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.md
create mode 100644 .agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
delete mode 100644 .agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md
delete mode 100644 .agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
create mode 100644 apps/cli/src/session/active-turn-steer-port.ts
create mode 100644 apps/cli/src/session/queue-steer-service.ts
delete mode 100644 packages/components/src/components/sessions/message-queue/queued-message-steer-compat.ts
delete mode 100644 packages/components/tests/queued-message-steer.test.ts
create mode 100644 packages/shared/src/session-queue-mutation.ts
diff --git a/.agents/docs/rpc-loro-streams-rpc.md b/.agents/docs/rpc-loro-streams-rpc.md
index c5df93c98..fb2625695 100644
--- a/.agents/docs/rpc-loro-streams-rpc.md
+++ b/.agents/docs/rpc-loro-streams-rpc.md
@@ -21,8 +21,11 @@ been removed.
- `README.md` — package smoke-test notes.
`session/queue-steer` is an identity-based control operation, not queue reordering. Its
-request names both the expected active turn and exact queued item, and callers require the
-negotiated `queueItemSteer` protocol capability. The CLI accepts the item only when its
+request names both the expected active turn and exact queued item, and callers require
+`queueItemSteer` v2. Its paired `session/queue-mutate` domain RPC serializes revision-checked
+edit/remove/reorder against reservation; conflicts fail visibly, without renderer direct-write
+fallback. Native submission waits for durable history and queue removal.
+The CLI accepts the item only when its
editing lease is inactive, then preserves native ACP Steer when acknowledged or creates an
ordinary follow-up before cancelling the expected turn. The ordinary path retains the queue
row until history and its activation pointer are durable. Missing, editing, and stale targets
diff --git a/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.md b/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.md
new file mode 100644
index 000000000..581a71e53
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.md
@@ -0,0 +1,112 @@
+# Effect ownership for queue Steer
+
+Status: implemented
+Translation: current
+
+[中文](2026-09-14-queue-steer-effect-boundary.zh.md)
+
+## Abstract
+
+QueueSteerService owns exact selection, validation, recovery evidence, fallback and receipts;
+ActiveTurnSteerPort retains live-turn and provider ownership. Effect 3.18.4 expresses local
+resource lifetimes and typed failures without treating provider submission as reversible.
+Native reservation makes frozen history and queue removal durable before submission;
+conflicting stale edits fail visibly and retain their drafts. Queue Steer requires
+queueItemSteer v2, without old-daemon compatibility. Indeterminate delivery never replays;
+real process-crash and installed-app verification remain outside the completed checks.
+
+## Source evidence
+
+The [workspace catalog](../../../../pnpm-workspace.yaml) pins `effect: 3.18.4`,
+and [CLI dependencies](../../../../apps/cli/package.json) consume `catalog:`.
+[SessionExecutionService](../../../../apps/cli/src/session/session-execution-service.ts)
+already uses `Effect.gen` and `Effect.acquireRelease` for turn ownership and
+finalization. The implementation extends that existing approach.
+
+The installed package has source but no `AGENTS.md`. The official v3 checkout has
+[agent instructions](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/AGENTS.md)
+and a [documentation entry](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/docs/index.md).
+Upstream v4 examples using `Context.Service` or `Effect.catch` must not be copied
+into this v3 application. CLI instructions reference `context/cli-effect-ts.md`,
+which is absent from this checkout.
+
+The installed implementations of `acquireUseRelease` in `src/internal/core.ts`,
+`acquireRelease` in `src/internal/fiberRuntime.ts`, `tryPromise` in
+`src/internal/core-effect.ts`, and the `ManagedRuntime` API were inspected.
+The corresponding [3.18.4 source](https://github.com/Effect-TS/effect/tree/ede2ea11c2abe7038bac3c83fb7b5eef101858d2/packages/effect/src)
+is the API authority. Upstream v3
+[resource tests](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/acquire-release.test.ts)
+and [interruption tests](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/interruption.test.ts)
+were read as supplementary evidence, not run or assumed identical to the pinned release.
+
+## Boundaries and implementation
+
+| Owner | Responsibility |
+| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| UI | Pass session, exact queue item and expected turn; no native/fallback policy. |
+| [QueueSteerService](../../../../apps/cli/src/session/queue-steer-service.ts) | Exact selection, validation, durable marker, recovery, fallback and bounded receipts. |
+| [ActiveTurnSteerPort](../../../../apps/cli/src/session/active-turn-steer-port.ts) | Live ownership, native submission, prompt handoff, exact Stop and local guards. |
+| SessionExecutionService | Implement the port; compose Context.Tag/Layer and execute domain operations on its per-session queue. |
+| SessionDocument | Compare row revisions and mutate synchronously; write history only through shared HistoryWriter. |
+
+The queue service never reads runtime maps, agentClient, promptInFlight, invocation or successor,
+and receives no onSubmitting/onAcknowledged/onApplied/onUndelivered callbacks.
+Provider requester identity comes from the active invocation, not the shared queue author.
+Ordinary turn and composer routing remain unchanged.
+
+## Resources and failures
+
+Rewrite/ownership guards and the adapter's local ACK gate belong to Scope through
+Effect.acquireRelease. Interruption is masked between submission and ACK cleanup registration
+so local cleanup ownership cannot be abandoned. Stop still cancels ACP, not its owner fiber.
+Scope neither reverses external submission nor runs after process death.
+
+| Category | Behavior |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ProviderRejected, pre-submission StaleTurn | Only proven non-delivery and eligible preconditions allow ordinary dispatch recovery. Missing, editing or stale selection before reservation remains a no-op. |
+| ProviderDeliveryUnknown | Return the error without fallback or replay, including ownership loss or handoff failure after submission. |
+| PersistenceFailure | Local preparation/persistence failure; retain durable evidence, never infer non-delivery from a local failure. |
+
+A crash after write-ahead submission evidence but before local preparation finishes remains
+conservatively indeterminate. Do not introduce a phase per Effect step or retry the whole operation.
+
+## Authoritative mutation and recovery
+
+Early removal alone cannot prevent another client saving during the history persistence await.
+queueItemSteer therefore advances to v2: edit/remove/reorder use the narrow
+`session/queue-mutate` domain RPC, sharing reservation's serialization and rewrite conflict guard.
+Update/remove carry canonical row revisions; reorder carries the original ID snapshot.
+Conflicts and missing rows fail explicitly; failed RPC never falls back to direct writes.
+Enqueue, ordinary sends and other UI data remain renderer-authored, without a generic
+write-intent mirror. Old daemons do not expose Queue Steer.
+
+Native order is reservation marker → pending_apply history durable → queue removal durable
+→ submitting marker → native port → durable receipt. Every pre-submit barrier gates provider calls.
+Recovery uses marker and frozen history, without requiring a surviving row. Existing markers
+remain readable. A legacy row without a revision may be removed only when its frozen content
+is provably unchanged and it is not being edited; otherwise preserve it for reconciliation.
+
+Reserved/fallback recover the same ordinary turn; submitting/acknowledged never replay;
+applied recovers an accepted receipt. Ordinary cancel-and-dispatch retains its history/activation
+publication order and in-memory receipts. The [Spec](../../../../specs/message-queue-interactions.md)
+owns the full contract and remains draft. This supersedes the
+[original decision](../feature/2026-09-13-queue-steer-controls.md)'s editable-row retention and
+old-daemon compatibility policies.
+
+The editor stays mounted after the last row disappears, shows the conflict, and retains its
+unsaved draft until explicitly dismissed. Direct CRDT writes from old software are not v2
+authority acceptance; this is not compatibility with arbitrary old renderers.
+
+## Verification and limits
+
+Existing suites cover exact C preserving A/B, provider rejection and uncertainty, Stop/late ACK,
+consecutive handoffs, receipts/restart, and reservation versus edit/remove/reorder on a real LoroDoc.
+Explicit promise gates prove durable removal before submission, zero submissions after
+reservation/history/removal/submission-marker persistence failure, marker-plus-history recovery,
+and local guard release. Components verify displaced-draft retention; shared negotiation rejects v1.
+No race assertion depends on sleeps or real network scheduling.
+
+Direct CLI/components typechecks and targeted tests were run. Root pnpm check / pnpm format
+cannot start because corepack is absent; installed pnpm runs targeted checks and Prettier instead.
+No real-provider, full desktop end-to-end, process kill/restart, or arbitrary mixed-old-client
+verification was performed.
diff --git a/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.zh.md b/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
new file mode 100644
index 000000000..b02559755
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
@@ -0,0 +1,102 @@
+# 队列 Steer 的 Effect 归属边界
+
+Status: implemented
+Translation: current
+
+[English](2026-09-14-queue-steer-effect-boundary.md)
+
+## 摘要
+
+队列 Steer 由 `QueueSteerService` 负责精确选择、验证、恢复证据、fallback 与回执，
+`ActiveTurnSteerPort` 保留 live turn 和 provider ownership。Effect 3.18.4
+表达本地资源生命周期与类型化失败，不把 provider 提交包装成可撤销资源。
+Native reservation 后先持久化冻结 history 和队列删除，再提交 provider；旧客户端草稿
+冲突会明确失败并保留。队列 Steer 仅支持 queueItemSteer v2，没有旧 daemon 兼容路径。
+不确定交付禁止重放；真实多进程崩溃和已安装应用的人工验证仍未覆盖。
+
+## 源码证据
+
+[workspace catalog](../../../../pnpm-workspace.yaml) 固定 `effect: 3.18.4`，
+[CLI 依赖](../../../../apps/cli/package.json) 通过 `catalog:` 使用它。
+[SessionExecutionService](../../../../apps/cli/src/session/session-execution-service.ts)
+已经用 `Effect.gen`、`Effect.acquireRelease` 表达 turn ownership 与 finalization，
+本实现延续现有方式。
+
+安装包有源码但没有 `AGENTS.md`。官方 v3 checkout 包含
+[agent 规则](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/AGENTS.md)
+与[文档入口](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/docs/index.md)。
+不能把使用 `Context.Service` 或 `Effect.catch` 的上游 v4 示例复制到本项目的 v3。
+CLI 规则引用的 `context/cli-effect-ts.md` 在当前 checkout 缺失。
+
+已检查安装包 `src/internal/core.ts` 的 `acquireUseRelease`、
+`src/internal/fiberRuntime.ts` 的 `acquireRelease`、
+`src/internal/core-effect.ts` 的 `tryPromise`，以及 `ManagedRuntime` API。
+对应的 [3.18.4 源码](https://github.com/Effect-TS/effect/tree/ede2ea11c2abe7038bac3c83fb7b5eef101858d2/packages/effect/src)
+是 API 依据。另已阅读上游 v3 的
+[资源测试](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/acquire-release.test.ts)
+与[中断测试](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/interruption.test.ts)
+作为补充证据；未运行它们，也未假定它们与固定版本完全相同。
+
+## 边界与实现
+
+| 归属 | 责任 |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| UI | 每行仅传 session、queue item 和 expected turn；不选择 native/fallback。 |
+| [QueueSteerService](../../../../apps/cli/src/session/queue-steer-service.ts) | 精确选择、验证、持久 marker、恢复、fallback 和有界回执。 |
+| [ActiveTurnSteerPort](../../../../apps/cli/src/session/active-turn-steer-port.ts) | live ownership、native submission、prompt handoff、精确 Stop 与本地 guard。 |
+| SessionExecutionService | 实现 port；组合 Context.Tag/Layer，并在 per-session queue 执行领域 operation。 |
+| SessionDocument | 同步比较 row revision 后修改；history 只走共享 HistoryWriter。 |
+
+Queue 服务不读取 runtime map、agentClient、promptInFlight、invocation 或 successor，
+也不使用 onSubmitting/onAcknowledged/onApplied/onUndelivered 回调。Provider requester
+来自活动 invocation，不相信队列作者。既有普通 turn 与 composer 路由不变。
+
+## 资源和失败
+
+rewrite/ownership guard 和 adapter 本地 ACK gate 用 Effect.acquireRelease 归属 Scope。
+提交到 ACK cleanup 注册之间屏蔽 fiber interruption，避免释放本地 handle 的责任丢失；
+Stop 仍取消 ACP，而非其 owner fiber。Scope 既不能撤销外部提交，也不能跨进程死亡执行。
+
+| 类别 | 行为 |
+| ---------------------------------- | ----------------------------------------------------------------------------------------- |
+| ProviderRejected、提交前 StaleTurn | 只有确定未交付且前提允许才恢复普通 dispatch；reservation 前缺失、编辑中或过期仍无副作用。 |
+| ProviderDeliveryUnknown | 向上返回错误，不进入 fallback、不重放。包括提交后失去 ownership 或 handoff 失败。 |
+| PersistenceFailure | 本地准备/持久化失败；保留 durable evidence，不能从本地失败推导未交付。 |
+
+Native submission 写前证据之后、本地准备尚未完成的 crash 仍保守地是不确定交付。
+不为每个 Effect 步骤再加 phase，也不重试整个 operation。
+
+## 权威写入与恢复
+
+仅提前删除 row 无法防止 history 持久化等待期间另一个客户端保存编辑。因此
+queueItemSteer 升为 v2：renderer 对支持者的 edit/remove/reorder 通过窄领域 RPC
+`session/queue-mutate` 到 daemon，与 reservation 共用串行入口和 rewrite conflict guard。
+更新/删除带 canonical row revision，重排带原始 ID 快照；冲突和缺失明确失败。
+RPC 失败绝不退回直接写入。enqueue、普通发送和其他 UI 数据仍由 renderer 写入，
+没有恢复通用 write-intent mirror。旧 daemon 不开放队列 Steer。
+
+Native 顺序是 reservation marker → pending_apply history durable → queue removal durable
+→ submitting marker → native port → durable receipt。任一提交前 barrier 失败禁止 provider 调用。
+恢复使用 marker 和冻结 history；不要求原 row 存在。旧 marker 仍可读；若残留 row 无 revision，
+只有可证明与冻结内容一致且不在编辑中才删除，否则保留并等待对账。不能通过恢复丢掉已接受编辑。
+
+`reserved`/`fallback` 可恢复同一个普通 turn；`submitting`/`acknowledged` 不重放；
+`applied` 恢复 accepted 回执。普通 cancel-and-dispatch 保留既有 history/activation
+发布顺序与内存回执。完整契约由 [Spec](../../../../specs/message-queue-interactions.zh.md) 拥有；
+它仍是 draft。本决策替代[原记录](../feature/2026-09-13-queue-steer-controls.zh.md)的
+共享 row 保留到交付完成及旧 daemon 兼容策略。
+
+编辑器在最后一行消失后仍保持挂载，显示冲突提示并保留未保存草稿，直到用户明确关闭。
+旧软件直接写 CRDT 不等于 v2 authority 接受保存；不能声称兼容任意旧 renderer。
+
+## 验证与限制
+
+已有 suites 覆盖精确 C 保留 A/B、provider 拒绝与不确定失败、Stop/late ACK、连续 handoff、
+receipt/restart，以及真实 LoroDoc 上的 reservation 与 edit/remove/reorder 冲突。
+显式 promise gate 验证删除持久化先于 provider，以及 reservation/history/removal/submission-marker
+持久化失败时零提交、marker 加 history 的恢复和本地 guard 释放。组件覆盖 row 消失后的草稿保留，
+共享协议拒绝 v1。测试不使用睡眠或真实网络来决定竞态。
+
+直接 CLI、components 类型检查与目标测试已运行；根级 pnpm check / pnpm format
+因缺少 corepack 无法启动，改用已安装 pnpm 运行目标检查和 Prettier。
+没有真实 provider、完整桌面端到端、进程 kill/restart 或任意旧客户端混跑的验证。
diff --git a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md
deleted file mode 100644
index fd9b0f427..000000000
--- a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md
+++ /dev/null
@@ -1,204 +0,0 @@
-# Effect ownership for queue Steer
-
-Status: proposed
-Translation: current
-
-[中文](2026-09-14-queue-steer-effect-boundary.zh.md)
-
-## Abstract
-
-Queue Steer currently distributes delivery decisions across the renderer and
-operation bookkeeping across `SessionExecutionService`. The proposed boundary
-gives `QueueSteerService` exact selection, validation, durable recovery evidence,
-fallback policy, and results; `ActiveTurnSteerPort` owns native submission and
-live-turn handoff. Effect expresses local resource lifetimes and typed failure
-semantics without making provider submission reversible. Native reservation transfers
-the item out of editable Queue ownership; frozen history and queue removal must be durable
-before provider submission. Queue Steer requires a
-supported `queueItemSteer` capability, with no old-daemon compatibility path.
-The design is revised; implementation and behavioral verification remain pending.
-
-## Source evidence
-
-The [workspace catalog](../../../../pnpm-workspace.yaml) pins `effect: 3.18.4`,
-and [CLI dependencies](../../../../apps/cli/package.json) consume `catalog:`.
-[SessionExecutionService](../../../../apps/cli/src/session/session-execution-service.ts)
-already uses `Effect.gen` and `Effect.acquireRelease` for turn ownership and
-finalization. The proposal extends that existing approach.
-
-The installed package has source but no `AGENTS.md`. The official v3 checkout has
-[agent instructions](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/AGENTS.md)
-and a [documentation entry](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/docs/index.md).
-Upstream v4 examples using `Context.Service` or `Effect.catch` must not be copied
-into this v3 application. CLI instructions reference `context/cli-effect-ts.md`,
-which is absent from this checkout.
-
-The installed implementations of `acquireUseRelease` in `src/internal/core.ts`,
-`acquireRelease` in `src/internal/fiberRuntime.ts`, `tryPromise` in
-`src/internal/core-effect.ts`, and the `ManagedRuntime` API were inspected.
-The corresponding [3.18.4 source](https://github.com/Effect-TS/effect/tree/ede2ea11c2abe7038bac3c83fb7b5eef101858d2/packages/effect/src)
-is the API authority. Upstream v3
-[resource tests](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/acquire-release.test.ts)
-and [interruption tests](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/interruption.test.ts)
-were read as supplementary evidence, not run or assumed identical to the pinned release.
-
-## Responsibilities
-
-| Owner | Responsibility |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| UI | Pass `{ sessionId, queueItemId, expectedTurnId }` for the selected row; display the result. |
-| `QueueSteerService` | Exact queue-item selection, validation, durable recovery evidence, fallback policy, result and receipt. |
-| `ActiveTurnSteerPort` | Live-turn ownership, provider native submission, prompt handoff, and serialization with Stop and other active-turn operations. |
-| Queue storage | Existing history and activation publication responsibilities. |
-| Integration boundary | Provide v3 `Context.Tag` services through `Layer`; execute the composed operation and map its result to the response contract. |
-
-The active-turn implementation stays with the execution owner. QueueSteerService
-must not access `runtime.session.agentClient`, runtime maps, `promptInFlight`,
-`successor`, or `invocation`. The port derives the frozen requester identity
-from the active invocation and validates the expected turn under its own
-serialization boundary; caller validation never replaces that check.
-
-The native operation exposes a domain result, conceptually:
-
-```ts
-interface ActiveTurnSteerPort {
- steer(input: {
- sessionId: SessionId;
- expectedTurnId: string;
- turn: SteerTurn;
- }): Effect.Effect;
-}
-```
-
-`SteerTurn` is validated immutable turn data, not a runtime handle.
-`NativeSteerApplied` proves successful local handoff, not prompt completion.
-`StaleTurn` proves rejection before submission. Lost ownership after submission
-cannot be reported as that safe rejection.
-
-This is the native operation's contract, not an exhaustive interface for every
-execution operation. Native-support discovery and expected-turn cancellation
-also stay behind execution-owned operations. QueueSteerService chooses the policy
-without inspecting the provider client. Never expose `onSubmitting`,
-`onAcknowledged`, `onApplied`, or `onUndelivered` callbacks to advance a queue
-journal. The new service must not be the existing runtime-dependent code moved
-to another file.
-
-## Resource and failure model
-
-`Effect` describes a lazy computation with explicit expected failures
-and dependencies. Use `Effect.gen` to compose operations, with typed recovery
-handlers at the owner of the policy. A single `Effect.tryPromise` around the
-existing async workflow would not change lifecycle ownership.
-
-Rewrite leases and local live-turn ownership/serialization guards belong to
-`Scope`. Provider submission is an irreversible external side effect, not a
-resource that can be released. The sequence is acquire local ownership, submit
-the provider side effect, then release local ownership when its contract allows.
-Finalizers prevent local ownership leaks; they do not prove non-execution.
-An existing adapter acknowledgment handle is only a local synchronization
-resource and stays internal to the port.
-
-The expected error model has three categories:
-
-| Category | Evidence and examples | Recovery policy |
-| ---------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Safe rejection | Provider did not execute: `ProviderRejected`, pre-submission `StaleTurn`. | Fallback/retry is eligible only if operation preconditions still hold. Stale, missing, or editing selections remain failed no-ops; they must not stop a turn. |
-| Indeterminate delivery | `ProviderDeliveryUnknown`: submission may have executed, including acknowledgment or handoff uncertainty. | Propagate the failure; no fallback handler and no replay. |
-| Local failure | `PersistenceFailure`, validation or lease acquisition failure. | Recover from durable evidence; a local error alone never establishes non-delivery. |
-
-Use distinct v3 `Data.TaggedError` classes for `ProviderRejected`,
-`ProviderDeliveryUnknown`, and `PersistenceFailure`. The native port classifies
-delivery evidence; the operation's persistence boundary owns `PersistenceFailure`.
-A local failure after submission must preserve possible delivery and cannot be
-reclassified as `ProviderRejected`.
-
-The policy handler is `Effect.catchTag("ProviderRejected", fallbackToDispatch)`.
-There is no corresponding fallback handler for `ProviderDeliveryUnknown`.
-Defects and interruption remain distinguishable through `Cause`/`Exit`;
-neither a timeout nor an interrupted Promise establishes provider non-execution.
-Do not retry the complete delivery operation.
-
-## Durability and capability policy
-
-Keeping an editable queue row after freezing its history permits a lost edit:
-another client saves changed content, native delivery executes the earlier snapshot,
-then row deletion discards the accepted edit. The current native consumption path in
-`SessionDocument.consumeMessageQueueItemAsUserTurn` retains the row, and
-`updateMessageQueueItem` does not check operation ownership. This is an ownership
-contract defect, not merely a missing cleanup step.
-
-The [Spec](../../../../specs/message-queue-interactions.md) now assigns the item to
-the daemon-owned operation when reservation succeeds. The selected sequence is:
-
-```text
-validate and claim exclusive reservation ownership
-→ durable reservation marker
-→ append frozen pending_apply history → history durable
-→ remove selected shared Queue row → removal durable
-→ write-ahead submission evidence
-→ ActiveTurnSteerPort.steer(frozen turn)
-→ durable result / receipt
-```
-
-The queue write authority must serialize reservation with ordinary edit/remove/reorder
-and promotion, including while persistence is awaited. An edit committed first is
-included or causes reservation rejection. Reservation winning first rejects later
-mutations visibly, retaining an editor's draft. A stale client must not receive a
-successful no-op save. A machine-local marker or disabling buttons in one renderer
-cannot by itself enforce this across clients; all mutation paths need the same authority.
-The implementation of that boundary remains pending, and early row removal alone does
-not establish it.
-
-QueueSteerService owns the journal and receipts. Recovery uses its machine-local marker
-and frozen history, not an editable queue row. Before history becomes durable, recovery
-reconciles the reservation as unsubmitted before returning any surviving row to editing.
-After history is durable, recovery can finish removal and recover that same turn even if
-the row is absent. A failed removal commit prevents provider submission. After write-ahead
-submission evidence, a crash remains conservatively indeterminate unless authoritative
-evidence proves otherwise. Reserved-operation retries resolve through the marker or
-receipt rather than ordinary missing-row validation.
-
-Implement these boundaries without phase callbacks or exposing live runtime state.
-Preserve recovery of existing markers and their fail-closed replay guarantees from the
-[original decision](../../implemented/feature/2026-09-13-queue-steer-controls.md), but
-supersede its requirement to retain the shared row until delivery finishes. Reconcile any
-legacy surviving row without deleting accepted edits. Do not add a durable phase for every
-Effect step. The exact ownership, ordering, and failure guarantees have one owner in the Spec.
-
-Core Scope cleanup cannot survive process death. Stop must retain the ACP owner
-until raw completion or confirmed termination; a Promise wrapper cannot cancel
-external work without its cooperation. A workflow engine is a separate
-architectural decision, not required for these two delivery paths.
-
-Queue Steer has no old-daemon compatibility path. Without an advertised supported
-`queueItemSteer` version, every row's Steer action is unavailable, including the
-queue head. Do not fall back to renderer history materialization, legacy native
-Steer, or queue-head cancel. On supported daemons every row passes its own queue
-identity; the daemon chooses native delivery or cancel-and-dispatch.
-
-This supersedes the original decision's old-daemon compatibility policy for
-queue Steer only. Composer submission behavior is outside this change.
-The draft [interaction Spec](../../../../specs/message-queue-interactions.md)
-records the revised intent; the renderer still contains the old paths.
-
-## Verification still required
-
-Retain observable coverage for selecting C while preserving A/B, missing/editing
-rows, stale expected turns, native acceptance/refusal, Stop racing acknowledgment,
-failed persistence, and response-loss/restart recovery. Verify each error category:
-only eligible safe rejections dispatch fallback; indeterminate outcomes never
-replay; local failures recover according to durable evidence. Deterministic
-failure/interruption tests must prove local guards release without relinquishing
-a still-running ACP owner. Unsupported daemons must expose no usable queue Steer
-action on any row and issue no legacy submission or cancellation.
-
-Add two-client tests for both orderings of reservation versus edit/save/remove/reorder,
-including a stale client that has not observed removal. A rejected save must retain its draft;
-an accepted edit must not disappear behind the frozen prompt. Exercise failure/crash boundaries
-before history durability, between history and removal durability, and after durable removal
-before submission. Prove provider submission waits for durable removal, ordinary promotion
-cannot consume the reserved row, and recovery succeeds with marker plus history while the row
-is absent. Existing row-retention tests must be revised to the ownership-transfer contract.
-
-Business code and dependency versions are unchanged. This revised design and
-Spec are not implementation evidence; no runtime tests were executed.
diff --git a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md b/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
deleted file mode 100644
index 8d7b8fff8..000000000
--- a/.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
+++ /dev/null
@@ -1,178 +0,0 @@
-# 队列 Steer 的 Effect 归属边界
-
-Status: proposed
-Translation: current
-
-[English](2026-09-14-queue-steer-effect-boundary.md)
-
-## 摘要
-
-当前队列 Steer 的交付选择分散在 renderer，operation 记录则集中在
-`SessionExecutionService`。拟议边界由 `QueueSteerService` 负责精确选择、验证、
-持久恢复证据、fallback 策略与结果；`ActiveTurnSteerPort` 负责 native 提交和 live turn
-交接。Effect 表达本地资源生命周期与类型化失败语义，不会让 provider 提交变得可撤销。
-Native reservation 将目标移出可编辑 Queue ownership；冻结 history 与队列删除都必须
-在 provider 提交前持久化。队列 Steer 必须具备受支持的 `queueItemSteer` capability，
-不提供旧 daemon 兼容路径。
-设计已修订，实现与行为验证仍待完成。
-
-## 源码证据
-
-[workspace catalog](../../../../pnpm-workspace.yaml) 固定 `effect: 3.18.4`，
-[CLI 依赖](../../../../apps/cli/package.json) 通过 `catalog:` 使用它。
-[SessionExecutionService](../../../../apps/cli/src/session/session-execution-service.ts)
-已经用 `Effect.gen`、`Effect.acquireRelease` 表达 turn ownership 与 finalization，
-本提案延续现有方式。
-
-安装包有源码但没有 `AGENTS.md`。官方 v3 checkout 包含
-[agent 规则](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/AGENTS.md)
-与[文档入口](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/docs/index.md)。
-不能把使用 `Context.Service` 或 `Effect.catch` 的上游 v4 示例复制到本项目的 v3。
-CLI 规则引用的 `context/cli-effect-ts.md` 在当前 checkout 缺失。
-
-已检查安装包 `src/internal/core.ts` 的 `acquireUseRelease`、
-`src/internal/fiberRuntime.ts` 的 `acquireRelease`、
-`src/internal/core-effect.ts` 的 `tryPromise`，以及 `ManagedRuntime` API。
-对应的 [3.18.4 源码](https://github.com/Effect-TS/effect/tree/ede2ea11c2abe7038bac3c83fb7b5eef101858d2/packages/effect/src)
-是 API 依据。另已阅读上游 v3 的
-[资源测试](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/acquire-release.test.ts)
-与[中断测试](https://github.com/Effect-TS/effect/blob/1af4232fea7bc613e1dc68db9bec7b1f596d9e68/packages/effect/test/Effect/interruption.test.ts)
-作为补充证据；未运行它们，也未假定它们与固定版本完全相同。
-
-## 职责边界
-
-| 归属 | 责任 |
-| --------------------- | -------------------------------------------------------------------------------------------------------------- |
-| UI | 为所选行传入 `{ sessionId, queueItemId, expectedTurnId }`，展示结果。 |
-| `QueueSteerService` | 精确队列项选择、验证、持久恢复证据、fallback 策略、结果与回执。 |
-| `ActiveTurnSteerPort` | live turn ownership、provider native submission、prompt handoff，以及与 Stop 和其他 active turn 操作的串行化。 |
-| 队列存储 | 现有 history 与 activation 发布责任。 |
-| 集成边界 | 通过 `Layer` 提供 v3 `Context.Tag` 服务，执行组合后的 operation，将结果映射到响应协议。 |
-
-active turn 实现留在 execution owner。QueueSteerService 不得访问
-`runtime.session.agentClient`、runtime map、`promptInFlight`、`successor` 或
-`invocation`。port 从活动 invocation 派生冻结的 requester identity，并在自己的串行边界
-内验证 expected turn；调用方验证不能替代这个检查。
-
-native operation 暴露领域结果，概念契约如下：
-
-```ts
-interface ActiveTurnSteerPort {
- steer(input: {
- sessionId: SessionId;
- expectedTurnId: string;
- turn: SteerTurn;
- }): Effect.Effect;
-}
-```
-
-`SteerTurn` 是经过验证的不可变 turn 数据，不是 runtime handle。
-`NativeSteerApplied` 证明本地 handoff 成功，不代表 prompt 已完成。
-`StaleTurn` 证明在提交前拒绝；提交后失去 ownership 不能报告为这种安全拒绝。
-
-这是 native operation 的契约，不是全部 execution operation 的完整接口。native 支持
-查询和 expected-turn cancellation 也由 execution owner 的操作封装。
-QueueSteerService 选择策略，无需检查 provider client。禁止暴露
-`onSubmitting`、`onAcknowledged`、`onApplied`、`onUndelivered` 回调来推进
-queue journal。新服务不能只是把现有依赖 runtime 的代码换个文件。
-
-## 资源与失败模型
-
-`Effect` 描述惰性计算，显式声明预期失败与依赖。用 `Effect.gen`
-组合 operation，在策略所属层以类型化 handler 恢复。仅把现有 async workflow 包进
-一个 `Effect.tryPromise` 不会改变生命周期归属。
-
-rewrite lease 与本地 live-turn ownership/serialization guard 归属 `Scope`。
-provider submission 是不可撤销的外部副作用，不属于可 release 的资源。顺序是获取本地
-ownership、提交 provider 副作用，再在契约允许时释放本地 ownership。finalizer 防止
-本地 ownership 泄漏，不证明 provider 没执行。现有 adapter acknowledgment handle
-也仅是本地同步资源，留在 port 内部。
-
-预期错误模型分为三类：
-
-| 类别 | 证据与示例 | 恢复策略 |
-| ---------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| Safe rejection | 确定 provider 没执行：`ProviderRejected`、提交前的 `StaleTurn`。 | 仅在 operation 前提仍成立时才有资格 fallback/retry。过期、缺失或编辑中的选择仍是失败且无副作用，不得停止 turn。 |
-| Indeterminate delivery | `ProviderDeliveryUnknown`：提交可能已执行，包括确认或 handoff 不确定。 | 向上传递失败，不设 fallback handler，禁止 replay。 |
-| Local failure | `PersistenceFailure`、验证或 lease 获取失败。 | 根据 durable evidence 恢复；本地错误本身不证明未交付。 |
-
-使用独立的 v3 `Data.TaggedError` 类表达 `ProviderRejected`、
-`ProviderDeliveryUnknown` 与 `PersistenceFailure`。native port 对交付证据分类，
-operation 的持久化边界负责 `PersistenceFailure`。提交后的本地失败必须保留可能已交付
-这一事实，不能改标成 `ProviderRejected`。
-
-策略 handler 是 `Effect.catchTag("ProviderRejected", fallbackToDispatch)`。
-`ProviderDeliveryUnknown` 没有对应的 fallback handler。defect 与 interruption
-仍通过 `Cause`/`Exit` 区分；timeout 或 Promise 中断都不能证明 provider 没执行。
-不得重试整个交付 operation。
-
-## 持久化与 capability 策略
-
-冻结 history 后保留可编辑 queue row 会丢失编辑：另一客户端保存新内容，native
-delivery 执行先前快照，随后删除 row 丢掉已接受的编辑。当前
-`SessionDocument.consumeMessageQueueItemAsUserTurn` 的 native 消费路径保留 row，
-而 `updateMessageQueueItem` 没有检查 operation ownership。这是 ownership 契约错误，
-不仅是缺少清理步骤。
-
-[Spec](../../../../specs/message-queue-interactions.md) 现规定 reservation 成功时，
-目标归属 daemon-owned operation。选定顺序为：
-
-```text
-验证并取得排他 reservation ownership
-→ 持久化 reservation marker
-→ 追加冻结的 pending_apply history → history 持久化
-→ 删除共享 Queue 中的所选 row → 删除持久化
-→ write-ahead submission 证据
-→ ActiveTurnSteerPort.steer(frozen turn)
-→ 持久化结果 / 回执
-```
-
-队列权威写入端必须让 reservation 与普通 edit/remove/reorder、promotion 串行化，
-包括等待持久化期间。编辑先提交则纳入快照或使 reservation 拒绝；reservation 先成功，
-后续修改须明确拒绝，并保留编辑器草稿。旧客户端不能收到实际无操作的保存成功。
-仅凭 machine-local marker 或在一个 renderer 禁用按钮无法跨客户端保证这一点；
-所有修改路径都需要同一个权威边界。该边界的实现仍待完成，提前删除 row 本身不能建立它。
-
-QueueSteerService 拥有 journal 与回执。恢复依赖 machine-local marker 和冻结 history，
-不再依赖可编辑 queue row。history 持久化前，恢复须先将 reservation 对账为未提交，
-再让残留 row 恢复可编辑。history 持久化后，即使 row 已不存在，也能完成删除并恢复
-同一个 turn。删除持久化失败则禁止提交 provider。write-ahead submission 证据写入后
-发生崩溃，除非权威证据证明其他结果，否则保守地视为交付不确定。reserved operation
-的重试通过 marker 或 receipt 解析，不走普通缺失 row 验证。
-
-实现这些边界不得引入 phase callback 或暴露 live runtime 状态。
-保留[原决策](../../implemented/feature/2026-09-13-queue-steer-controls.md)中已有
-marker 的恢复与保守重放保证，但替代其“共享 row 保留到交付完成”的要求。旧版本残留
-row 的对账不能删除已接受的编辑。不为每个 Effect 步骤增加 durable phase。
-精确 ownership、顺序与失败保证统一由 Spec 定义。
-
-核心 Scope 清理无法跨越进程死亡。Stop 必须保留 ACP owner，直到原始调用完成或确认
-终止；外部工作不配合时，Promise 包装无法取消它。引入 workflow engine 是独立架构
-决策，不是这两条交付链的必需条件。
-
-队列 Steer 不兼容旧 daemon。未声明受支持的 `queueItemSteer` 版本时，所有行的
-Steer 都不可用，包括队首。不得退回 renderer 写历史、legacy native Steer 或队首
-cancel。支持该协议的 daemon 上，每一行传自己的队列标识，由 daemon 选择 native
-delivery 或 cancel-and-dispatch。
-
-这仅替代原决策中队列 Steer 的旧 daemon 兼容策略，composer 提交行为不在本次变更内。
-draft [交互 Spec](../../../../specs/message-queue-interactions.md) 记录修订后的意图；
-renderer 当前仍包含旧路径。
-
-## 待完成的验证
-
-保留选择 C 后 A/B 顺序不变、队列项缺失或编辑中、expected turn 过期、native
-接受/拒绝、Stop 与 acknowledgment 竞态、持久化失败及响应丢失/重启恢复的行为覆盖。
-验证三类错误：只有满足前提的安全拒绝才进入 fallback dispatch；交付不确定绝不
-replay；本地失败根据 durable evidence 恢复。确定性失败/中断测试须证明本地 guard
-会释放，且不会放弃仍在运行的 ACP owner。不支持协议的 daemon 上，任何行都不得有
-可用的队列 Steer 操作，也不得发出 legacy submission 或 cancellation。
-
-新增双客户端测试覆盖 reservation 与 edit/save/remove/reorder 的两种先后顺序，
-包括尚未观察到删除的旧客户端。拒绝保存须保留草稿；已接受编辑不能因冻结 prompt 而
-消失。覆盖 history 持久化前、history 与删除持久化之间、删除持久化后但提交前的失败/
-崩溃边界。证明 provider 提交等待删除持久化、普通 promotion 不会消费 reserved row，
-且 row 不存在时仍可凭 marker 与 history 恢复。现有保留 row 的测试须按 ownership
-转移契约修订。
-
-业务代码与依赖版本均未修改。修订后的设计与 Spec 不代表实现证据；未运行 runtime 测试。
diff --git a/apps/cli/src/lib/AGENTS.md b/apps/cli/src/lib/AGENTS.md
index c722c2151..7a41f9466 100644
--- a/apps/cli/src/lib/AGENTS.md
+++ b/apps/cli/src/lib/AGENTS.md
@@ -33,13 +33,11 @@ end-to-end map. The WS/DO control-plane path is DEPRECATED; do not add to it.
deliberately short, so a queued detach/revoke stays prompt. Backfill enable/disable
flips its authorization generation inside the queued body (S5: a revoked workspace
must never keep backfill enabled).
-- **Dual-author (no write intents)**: the renderer direct-authors user/UI durable
- writes against its own repo over its own Streams connection; the CLI authors only
- agent-produced data. The v4-v6 write-intent envelope (`WorkspaceWriteIntentAuthor`,
- `intent`/`intent-ack` frames, CLI preview-comment mirror) is REMOVED; never
- reintroduce a proxy-authoring path (invariants in `specs/local-first-two-plane.md`).
- Local dispatch triggers off the renderer-authored `latestUserMsgId` doc-meta write
- plus the local Machine RPC fast path.
+- Renderer user/UI writes use its own repo; never restore generic v4-v6 write intents
+ or CLI preview-comment mirrors. The narrow exception is `session/queue-mutate`
+ on queueItemSteer v2: edit/remove/reorder require daemon ownership and revision checks
+ shared with reservation/promotion. Queue enqueue and ordinary sends remain renderer-authored.
+ Local dispatch watches `latestUserMsgId` plus the Machine RPC fast path.
## Local Loro data plane
diff --git a/apps/cli/src/lib/loro/doc-user-turn.test.ts b/apps/cli/src/lib/loro/doc-user-turn.test.ts
index c9fc6fda7..83f383b3c 100644
--- a/apps/cli/src/lib/loro/doc-user-turn.test.ts
+++ b/apps/cli/src/lib/loro/doc-user-turn.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it, vi } from 'vitest';
import {
getServerNow,
+ queueItemRevision,
type MessageQueueItem,
type SessionHistoryInput,
type SessionId,
@@ -63,6 +64,39 @@ const createUserTurn = (id: string): SessionHistoryInput => ({
});
describe('SessionDocument.consumeMessageQueueItemAsUserTurn', () => {
+ it('rejects stale edits, missing rows and stale reorder snapshots without losing accepted content', async () => {
+ const { doc } = createSessionDocument({ upsertDocMeta: async () => {} });
+ const rows = await seedMessageQueue(
+ doc,
+ ['A', 'B', 'C'].map((task) => ({
+ task,
+ userId: 'user-1',
+ timestamp: '2026-09-14T00:00:00.000Z',
+ }))
+ );
+ const selected = rows[2]!;
+ const update = {
+ kind: 'update' as const,
+ queueItemId: selected.$cid,
+ expectedRevision: queueItemRevision(selected),
+ patch: { task: 'Roll back instead' },
+ };
+ await doc.mutateMessageQueue(update);
+ await expect(
+ doc.mutateMessageQueue({ ...update, patch: { task: 'Stale edit' } })
+ ).rejects.toThrow('changed');
+ expect((await doc.getMessageQueue())[2]?.task).toBe('Roll back instead');
+ await doc.removeMessageQueueItem(selected.$cid);
+ await expect(doc.mutateMessageQueue(update)).rejects.toThrow('no longer');
+ await expect(
+ doc.mutateMessageQueue({
+ kind: 'reorder',
+ expectedItemIds: rows.map((row) => row.$cid),
+ orderedItemIds: rows.map((row) => row.$cid).reverse(),
+ })
+ ).rejects.toThrow('changed');
+ expect((await doc.getMessageQueue()).map((row) => row.task)).toEqual(['A', 'B']);
+ });
it('consumes the named later row after activation without reordering the survivors', async () => {
const upsertDocMeta = vi.fn(async () => {});
const { doc } = createSessionDocument({ upsertDocMeta });
diff --git a/apps/cli/src/lib/loro/doc.ts b/apps/cli/src/lib/loro/doc.ts
index f3b33dca1..968ac49cf 100644
--- a/apps/cli/src/lib/loro/doc.ts
+++ b/apps/cli/src/lib/loro/doc.ts
@@ -1,3 +1,4 @@
+import { queueItemRevision, ACPSessionConfigSchema, type SessionQueueMutation } from '@lody/shared';
import { createSessionAgentWrites, type SessionAgentWrites } from './session-agent-writes';
import { readSessionHistory } from '@lody/shared/session-data';
import { readLatestTurn } from '@lody/shared/session-data';
@@ -2776,6 +2777,71 @@ export class SessionDocument implements LoroDocument {
+ if (!this.mirror) throw new Error('SessionDocument not initialized');
+ this.mirror.setState((prev) => {
+ const queue = (prev.mq ?? []) as MessageQueueItem[];
+ let next: MessageQueueItem[];
+ if (mutation.kind === 'reorder') {
+ const ids = queue.map((item) => item.$cid);
+ if (
+ queueItemRevision(ids) !== queueItemRevision(mutation.expectedItemIds) ||
+ new Set(mutation.orderedItemIds).size !== ids.length ||
+ mutation.orderedItemIds.some((id) => !ids.includes(id))
+ ) {
+ throw new Error('The queue changed. Refresh before reordering.');
+ }
+ if (queue.some(hasActiveMessageQueueEditingLease))
+ throw new Error('A queue item is being edited.');
+ next = mutation.orderedItemIds.map((id) => queue.find((item) => item.$cid === id)!);
+ } else {
+ const row = queue.find((item) => item.$cid === mutation.queueItemId);
+ if (!row)
+ throw new Error(
+ 'This message is no longer in the editable queue. Your draft was not saved.'
+ );
+ if (queueItemRevision(row) !== mutation.expectedRevision) {
+ throw new Error('This queued message changed. Your draft was not saved.');
+ }
+ if (mutation.kind === 'remove') {
+ next = queue.filter((item) => item !== row);
+ } else {
+ const patch = mutation.patch;
+ const mutable = new Set(['task', 'isEditing', 'editingStartedAt', 'acpSessionConfig']);
+ for (const [key, value] of Object.entries(patch)) {
+ if (
+ !mutable.has(key) &&
+ queueItemRevision(value) !==
+ queueItemRevision((row as unknown as Record)[key])
+ ) {
+ throw new Error('Queue message identity cannot be changed.');
+ }
+ }
+ if (patch.task !== undefined && typeof patch.task !== 'string')
+ throw new Error('Invalid queued message text.');
+ if (patch.isEditing !== undefined && typeof patch.isEditing !== 'boolean')
+ throw new Error('Invalid editing state.');
+ if (
+ patch.editingStartedAt !== undefined &&
+ (typeof patch.editingStartedAt !== 'number' || !Number.isFinite(patch.editingStartedAt))
+ ) {
+ throw new Error('Invalid editing lease.');
+ }
+ if (patch.acpSessionConfig !== undefined)
+ ACPSessionConfigSchema.partial().parse(patch.acpSessionConfig);
+ next = queue.map((item) =>
+ item === row ? ({ ...row, ...patch, $cid: row.$cid } as MessageQueueItem) : item
+ );
+ }
+ }
+ // @ts-ignore - the mirror exposes a readonly snapshot but owns this mutation
+ prev.mq = next;
+ return prev;
+ });
+ await this.repo.upsertDocMeta(this.roomId, { messageQueueUpdatedAt: getServerNow() });
+ }
+
async removeMessageQueueItem(cid: string): Promise {
if (!this.mirror) {
throw new Error('SessionDocument not initialized');
@@ -2795,7 +2861,7 @@ export class SessionDocument implements LoroDocument): Promise {
- if (!this.mirror) {
- throw new Error('SessionDocument not initialized');
- }
- this.mirror.setState((prev) => {
- const mq = (prev.mq ?? []) as MessageQueueItem[];
- // @ts-ignore - mq is read-only in type but writable at runtime
- prev.mq = mq.map((item: MessageQueueItem) =>
- item.$cid === cid ? ({ ...item, ...patch, $cid: item.$cid } as MessageQueueItem) : item
- );
- return prev;
- });
- }
-
- /**
- * Reorder the message queue to the given `$cid` order. `orderedCids` is the full
- * resulting order from the renderer (`session-mq-reorder`); items whose `$cid`
- * is absent from the list are dropped to the end in their existing relative
- * order (defensive — the renderer always sends the complete set).
- */
- async reorderMessageQueue(orderedCids: readonly string[]): Promise {
- if (!this.mirror) {
- throw new Error('SessionDocument not initialized');
- }
- this.mirror.setState((prev) => {
- const mq = (prev.mq ?? []) as MessageQueueItem[];
- const byCid = new Map(mq.map((item) => [item.$cid, item] as const));
- const ordered: MessageQueueItem[] = [];
- for (const cid of orderedCids) {
- const item = byCid.get(cid);
- if (item) {
- ordered.push(item);
- byCid.delete(cid);
- }
- }
- for (const item of mq) {
- if (item.$cid !== undefined && byCid.has(item.$cid)) {
- ordered.push(item);
- }
- }
- // @ts-ignore - mq is read-only in type but writable at runtime
- prev.mq = ordered;
- return prev;
- });
- }
-
async destroy(options: { preserveStatus?: boolean } = {}) {
if (!this.mirror) {
return;
diff --git a/apps/cli/src/lib/message-handler.ts b/apps/cli/src/lib/message-handler.ts
index 74444cef2..00c33a931 100644
--- a/apps/cli/src/lib/message-handler.ts
+++ b/apps/cli/src/lib/message-handler.ts
@@ -3285,6 +3285,7 @@ export class MessageHandler {
};
},
steerSession: async (args) => await this.steerSessionWithAccessCheck(args),
+ mutateQueuedMessage: async (args) => await this.executionService.mutateQueuedMessage(args),
steerQueuedMessage: async (args) => await this.executionService.steerQueuedMessage(args),
controlSessionGoal: async (args) => await this.controlSessionGoalWithAccessCheck(args),
terminateSession: async ({ sessionId }) => await this.terminateAcpSession(sessionId),
@@ -6326,6 +6327,8 @@ export class MessageHandler {
sessionId: request.params.sessionId as SessionId,
});
}
+ case 'session/queue-mutate':
+ return await this.executionService.mutateQueuedMessage(request.params);
case 'session/queue-steer': {
return await this.executionService.steerQueuedMessage({
...request.params,
diff --git a/apps/cli/src/session/AGENTS.md b/apps/cli/src/session/AGENTS.md
index be5f4ddb6..c52767ca2 100644
--- a/apps/cli/src/session/AGENTS.md
+++ b/apps/cli/src/session/AGENTS.md
@@ -25,8 +25,8 @@ Contract: specs/session-orchestration.md.
## Dispatch
-- Queue promotion keeps frozen fields. Exact Steer respects edit leases/native support;
- missing/stale targets never stop.
+- QueueSteerService owns selection/recovery; ActiveTurnSteerPort owns execution.
+ No runtime handles or phase callbacks. Missing/stale targets never stop.
- Absent session meta is "unknown", not foreign: hold the TTL-bounded RPC stash until meta lands;
drop it only on a definitive verdict.
- Subscribe to RPC offers BEFORE awaiting Doc Room join/sync and never dispatch from the RPC
@@ -56,9 +56,9 @@ Contract: specs/session-orchestration.md.
tombstone; CLI dispatch producers keep their own marker policy.
- Ordinary turn execution writes only `processingUserMsgId` and `lastHandledUserMsgId`; no start
or terminal path may read-await-rewrite the other slots.
-- Never steer after Stop; late ACK cancels entry. Native queue Steer keeps row + machine-local
- phase. Restart dispatches reserved/fallback, fails submitting/acknowledged without replay, and
- receipts applied. Cache after recovery. Requeue unaccepted via pointer; skip active/handled.
+- Never steer after Stop; late ACK is indeterminate. Reserve against queue mutations/promotion;
+ persist marker, frozen history and removal BEFORE native submission. Scope owns local guards,
+ not provider effects. Only proven non-delivery may requeue; unknown delivery never replays.
- Resume must REOPEN the in-progress assistant entry, clearing
`finished`/`endedAt`/`permissionWaitMs` there only; never write `finished=false` from teardown.
- Keep JSON-RPC/transport matching in `acp-error-classification.ts`: disposed/stale `-32603` is
diff --git a/apps/cli/src/session/README.md b/apps/cli/src/session/README.md
index 04bc2b4bc..9e982560f 100644
--- a/apps/cli/src/session/README.md
+++ b/apps/cli/src/session/README.md
@@ -11,6 +11,13 @@ CLI/MCP orchestration contract is specs/session-orchestration.md.
## Files
+| Boundary | Entry | Ownership |
+| --------------- | ----------------------------------------------------- | ----------------------------------------------------------------------- |
+| Dispatch | [SessionDispatchWatcher](session-dispatch-watcher.ts) | Observe durable activation and claim ordinary turns. |
+| Queue operation | [QueueSteerService](queue-steer-service.ts) | Exact selection, reservation, delivery policy and recovery evidence. |
+| Live execution | [ActiveTurnSteerPort](active-turn-steer-port.ts) | Native submission and handoff within SessionExecutionService ownership. |
+| Storage | [SessionDocument](../lib/loro/doc.ts) | Revision-checked queue mutations and shared history writes. |
+
- `session-dispatch-watcher.ts` — the current dispatch entry: watches
`repo.watch('doc-metadata')` plus a per-session mirror subscribe and dispatches when
`latestUserMsgId` differs from `lastHandledUserMsgId`. Also accepts `session/dispatch-turn`
@@ -24,9 +31,9 @@ CLI/MCP orchestration contract is specs/session-orchestration.md.
- `turn-history-gate.ts` — ordering barrier for RPC fast-path turns. Created in
message-handler's `beginConversationTurn`, stored/disposed via `SessionTransientStore` turn
state; it creates the assistant entry when it opens.
-- `session-execution-service.ts` — runs one turn end-to-end and owns exact-item queue
- Steer serialization: validate the active turn, queued item, and editing lease, then
- choose native `steerPrompt` or exact cancel-and-dispatch. It also owns ACP prompt, turn ids,
+- `session-execution-service.ts` — runs one turn end-to-end, implements ActiveTurnSteerPort
+ and serializes queue operations without owning their delivery policy or journal.
+ It owns ACP prompt, turn ids,
lifecycle/error handling, GitHub/local project setup, and post-turn diffStats.
- `acp-error-classification.ts` — JSON-RPC/transport error string matching for the above.
- `session-manager.ts` / `session.ts` / `session-sandbox.ts` / `terminal-manager.ts` —
diff --git a/apps/cli/src/session/active-turn-steer-port.ts b/apps/cli/src/session/active-turn-steer-port.ts
new file mode 100644
index 000000000..09f7d470f
--- /dev/null
+++ b/apps/cli/src/session/active-turn-steer-port.ts
@@ -0,0 +1,57 @@
+import { Context, Data, Effect, type Scope } from 'effect';
+import type { SessionId, SessionTurnInputConfig, SessionSteerResponse } from '@lody/shared';
+
+export type SteerTurn = {
+ id: string;
+ userId: string;
+ timestamp: string;
+ inputConfig: SessionTurnInputConfig;
+};
+
+export class StaleTurn extends Data.TaggedError('StaleTurn')<{
+ disposition: 'no-active-turn' | 'stale-turn' | 'busy';
+ message: string;
+}> {}
+
+/** Only a proven refusal before injection permits ordinary dispatch. */
+export class ProviderRejected extends Data.TaggedError('ProviderRejected')<{
+ disposition: Exclude;
+ message: string;
+}> {}
+
+export class ProviderDeliveryUnknown extends Data.TaggedError('ProviderDeliveryUnknown')<{
+ message: string;
+ cause?: unknown;
+}> {}
+
+export class PersistenceFailure extends Data.TaggedError('PersistenceFailure')<{
+ message: string;
+ cause: unknown;
+}> {}
+
+export type NativeSteerFailure =
+ | StaleTurn
+ | ProviderRejected
+ | ProviderDeliveryUnknown
+ | PersistenceFailure;
+export type NativeSteerInput = {
+ sessionId: SessionId;
+ expectedTurnId: string;
+ turn: SteerTurn;
+};
+
+/** Operations run inside the execution owner's per-session serialization boundary. */
+export class ActiveTurnSteerPort extends Context.Tag('lody/ActiveTurnSteerPort')<
+ ActiveTurnSteerPort,
+ {
+ guard(sessionId: SessionId): Effect.Effect;
+ inspect(
+ sessionId: SessionId,
+ expectedTurnId: string
+ ): Effect.Effect<{ native: boolean; requesterUserId: string }, StaleTurn | ProviderRejected>;
+ steer(input: NativeSteerInput): Effect.Effect<{ userTurnId: string }, NativeSteerFailure>;
+ cancel(sessionId: SessionId, expectedTurnId: string): Effect.Effect;
+ ownsPrompt(sessionId: SessionId, expectedTurnId: string): boolean;
+ activeUserTurnId(sessionId: SessionId): string | undefined;
+ }
+>() {}
diff --git a/apps/cli/src/session/queue-steer-service.ts b/apps/cli/src/session/queue-steer-service.ts
new file mode 100644
index 000000000..c22c1c7c9
--- /dev/null
+++ b/apps/cli/src/session/queue-steer-service.ts
@@ -0,0 +1,503 @@
+import { Context, Effect, Layer } from 'effect';
+import {
+ getServerNow,
+ normalizeSessionTurnInputConfig,
+ queueItemRevision,
+ resolveSessionHistoryStatus,
+ type SessionId,
+ type SessionQueueSteerResponse,
+ type SessionQueueMutation,
+ type SessionQueueMutationResponse,
+} from '@lody/shared';
+import { readSessionHistory } from '@lody/shared/session-data';
+import { hasActiveMessageQueueEditingLease, type SessionDocument } from '@/lib/loro/doc';
+import { formatErrorMessage } from '@/utils/format-error';
+import { ActiveTurnSteerPort, PersistenceFailure } from './active-turn-steer-port';
+import { buildQueuedMessageUserTurn } from './queued-message-turn';
+import {
+ isQueueSteerMarkerOwnedBy,
+ type QueueSteerOperationMarker,
+} from './session-queue-steer-operation-store';
+import type { SessionExecutionServiceDeps } from './session-execution-service';
+
+type Request = { sessionId: SessionId; expectedTurnId: string; queueItemId: string };
+type Marker = QueueSteerOperationMarker;
+type Recovery = SessionQueueSteerResponse | 'deferred' | null;
+type Deps = Pick<
+ SessionExecutionServiceDeps,
+ | 'workspaceId'
+ | 'machineId'
+ | 'workspaceDocument'
+ | 'queueSteerOperationStore'
+ | 'recordChatFailure'
+ | 'logger'
+> & {
+ requeue(
+ sessionId: SessionId,
+ userTurnId: string
+ ): Promise<'requeued' | 'not-requeueable' | 'requeue-failed'>;
+ failTurn(sessionId: SessionId, doc: SessionDocument, userTurnId: string): Promise;
+};
+
+const persist = (run: () => Promise ) =>
+ Effect.tryPromise({
+ try: run,
+ catch: (cause) => new PersistenceFailure({ cause, message: formatErrorMessage(cause) }),
+ });
+
+const respond = (
+ request: Pick,
+ disposition: SessionQueueSteerResponse['disposition'],
+ details: { userTurnId?: string; error?: string } = {}
+): SessionQueueSteerResponse => ({
+ type: 'session/queue-steer_response',
+ sessionId: request.sessionId,
+ queueItemId: request.queueItemId,
+ accepted: disposition === 'accepted',
+ disposition,
+ ...details,
+});
+
+/** Callers serialize these effects with the execution owner's session mutation queue. */
+export class QueueSteerService extends Context.Tag('lody/QueueSteerService')<
+ QueueSteerService,
+ {
+ steerQueueItem(request: Request): Effect.Effect;
+ recover(
+ sessionId: SessionId,
+ doc: SessionDocument
+ ): Effect.Effect;
+ mutate(request: SessionQueueMutation): Effect.Effect;
+ }
+>() {
+ static layer(deps: Deps) {
+ return Layer.effect(QueueSteerService, QueueSteerService.make(deps));
+ }
+
+ static make(deps: Deps) {
+ return Effect.gen(function* () {
+ const active = yield* ActiveTurnSteerPort;
+ const receipts = new Map();
+ const remember = (key: string, response: SessionQueueSteerResponse) => {
+ receipts.delete(key);
+ receipts.set(key, response);
+ if (receipts.size > 512) {
+ const oldest = receipts.keys().next().value;
+ if (oldest !== undefined) receipts.delete(oldest);
+ }
+ return response;
+ };
+ const owned = (marker: Marker) =>
+ isQueueSteerMarkerOwnedBy(marker, deps.workspaceId, deps.machineId);
+ const flush = () =>
+ persist(() => deps.workspaceDocument.persistPendingChanges('queue-steer-commit'));
+ const write = (
+ sessionId: SessionId,
+ marker: Omit
+ ) => {
+ const durable: Marker = {
+ ...marker,
+ sessionId,
+ workspaceId: deps.workspaceId,
+ machineId: deps.machineId,
+ updatedAt: getServerNow(),
+ };
+ return persist(() => deps.queueSteerOperationStore.record(durable)).pipe(
+ Effect.as(durable)
+ );
+ };
+ const receipt = (sessionId: SessionId, marker: Marker) =>
+ marker.completedAt && marker.response
+ ? respond({ sessionId, queueItemId: marker.queueItemId }, marker.response.disposition, {
+ userTurnId: marker.response.userTurnId,
+ error: marker.response.error,
+ })
+ : null;
+ const complete = Effect.fn('QueueSteer.complete')(function* (
+ sessionId: SessionId,
+ marker: Marker,
+ response: SessionQueueSteerResponse
+ ) {
+ yield* write(sessionId, {
+ ...marker,
+ completedAt: getServerNow(),
+ response: {
+ disposition: response.disposition,
+ userTurnId: response.userTurnId,
+ error: response.error,
+ },
+ });
+ return remember(marker.operationKey, response);
+ });
+
+ // A surviving legacy row may contain an edit accepted after its history was frozen.
+ // Preserve it and defer rather than silently deleting somebody else's work.
+ const removeReservedRow = Effect.fn('QueueSteer.removeReservedRow')(function* (
+ doc: SessionDocument,
+ marker: Marker
+ ) {
+ const row = (yield* persist(() => doc.getMessageQueue())).find(
+ (item) => item.$cid === marker.queueItemId
+ );
+ if (row) {
+ let same = marker.queueRevision === queueItemRevision(row);
+ if (!marker.queueRevision && !hasActiveMessageQueueEditingLease(row)) {
+ const meta = yield* persist(() => doc.getMetaState());
+ const frozen = readSessionHistory(doc.sessionData.history).find(
+ (entry) => entry.id === marker.userTurnId
+ );
+ const candidate = meta ? buildQueuedMessageUserTurn(row, meta) : null;
+ same =
+ !!candidate &&
+ !!frozen &&
+ candidate.id === frozen.id &&
+ candidate.timestamp === frozen.timestamp &&
+ queueItemRevision(candidate.items) === queueItemRevision(frozen.items) &&
+ queueItemRevision(normalizeSessionTurnInputConfig(candidate.inputConfig)) ===
+ queueItemRevision(normalizeSessionTurnInputConfig(frozen.inputConfig));
+ }
+ if (!same || hasActiveMessageQueueEditingLease(row)) {
+ return yield* new PersistenceFailure({
+ cause: undefined,
+ message:
+ 'The reserved queue row changed. Its edited content was preserved; delivery requires reconciliation.',
+ });
+ }
+ yield* persist(() => doc.removeMessageQueueItem(marker.queueItemId));
+ }
+ yield* flush();
+ });
+
+ const fallback = Effect.fn('QueueSteer.fallback')(function* (
+ sessionId: SessionId,
+ doc: SessionDocument,
+ marker: Marker,
+ response: SessionQueueSteerResponse
+ ) {
+ const durable = yield* write(sessionId, {
+ ...marker,
+ phase: 'fallback',
+ completedAt: undefined,
+ response: {
+ disposition: response.disposition,
+ userTurnId: response.userTurnId,
+ error: response.error,
+ },
+ });
+ yield* removeReservedRow(doc, durable);
+ const result = yield* persist(() => deps.requeue(sessionId, marker.userTurnId));
+ if (result === 'requeue-failed') {
+ return yield* new PersistenceFailure({
+ cause: undefined,
+ message: 'Failed to recover the reserved turn for dispatch.',
+ });
+ }
+ yield* flush();
+ return yield* complete(sessionId, durable, response);
+ });
+
+ const recoverMarker = Effect.fn('QueueSteer.recoverMarker')(function* (
+ sessionId: SessionId,
+ doc: SessionDocument,
+ marker: Marker
+ ) {
+ const previous = receipt(sessionId, marker);
+ if (previous) return remember(marker.operationKey, previous);
+ if (!owned(marker)) return 'deferred';
+ if (
+ (marker.phase === 'submitting' || marker.phase === 'acknowledged') &&
+ active.ownsPrompt(sessionId, marker.expectedTurnId)
+ )
+ return 'deferred';
+ yield* persist(async () => {
+ await doc.waitUntilSynced?.();
+ });
+ const entry = readSessionHistory(doc.sessionData.history).find(
+ (item) => item.role === 'user' && item.id === marker.userTurnId
+ );
+ const request = { sessionId, queueItemId: marker.queueItemId };
+ if (!entry) {
+ if (marker.phase !== 'reserved') return 'deferred';
+ return yield* complete(
+ sessionId,
+ marker,
+ respond(request, 'error', {
+ userTurnId: marker.userTurnId,
+ error: 'Reservation ended before history was persisted. The message remains queued.',
+ })
+ );
+ }
+ if (marker.phase === 'reserved' || marker.phase === 'fallback') {
+ return yield* fallback(
+ sessionId,
+ doc,
+ marker,
+ marker.response
+ ? respond(request, marker.response.disposition, marker.response)
+ : respond(request, 'error', {
+ userTurnId: marker.userTurnId,
+ error: 'The daemon restarted before submission; the reserved turn was queued.',
+ })
+ );
+ }
+ const applied =
+ marker.phase === 'applied' ||
+ active.activeUserTurnId(sessionId) === marker.userTurnId ||
+ resolveSessionHistoryStatus(entry) === 'handled';
+ const status = resolveSessionHistoryStatus(entry);
+ if (
+ active.activeUserTurnId(sessionId) !== marker.userTurnId &&
+ status !== 'handled' &&
+ status !== 'failed' &&
+ status !== 'canceled'
+ ) {
+ yield* persist(() => deps.failTurn(sessionId, doc, marker.userTurnId));
+ yield* persist(() =>
+ deps.recordChatFailure(
+ doc,
+ 'agent_disconnected',
+ applied
+ ? 'The daemon restarted after Steer handoff. The provider call was not replayed.'
+ : 'Steer delivery could not be confirmed after restart. The provider call was not replayed.'
+ )
+ );
+ }
+ yield* removeReservedRow(doc, marker);
+ return yield* complete(
+ sessionId,
+ applied ? { ...marker, phase: 'applied' } : marker,
+ respond(request, applied ? 'accepted' : 'error', {
+ userTurnId: marker.userTurnId,
+ ...(applied
+ ? {}
+ : { error: 'Native Steer delivery is indeterminate; it was not replayed.' }),
+ })
+ );
+ });
+
+ const recover = (sessionId: SessionId, doc: SessionDocument) =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const guarded = yield* Effect.either(active.guard(sessionId));
+ if (guarded._tag === 'Left') return 'deferred' as const;
+ const marker = yield* persist(() => deps.queueSteerOperationStore.read(sessionId));
+ return marker ? yield* recoverMarker(sessionId, doc, marker) : null;
+ })
+ );
+
+ const steerQueueItem = (request: Request) =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const { sessionId, expectedTurnId, queueItemId } = request;
+ const operationKey = JSON.stringify([sessionId, expectedTurnId, queueItemId]);
+ const cached = receipts.get(operationKey);
+ if (cached) return cached;
+ yield* active.guard(sessionId);
+ const doc = yield* persist(() =>
+ deps.workspaceDocument.getOrCreateSessionDoc(sessionId)
+ );
+ const meta = yield* persist(() => doc.getMetaState());
+ if (!meta)
+ return respond(request, 'error', { error: 'Session metadata is unavailable.' });
+ const previous = yield* persist(() => deps.queueSteerOperationStore.read(sessionId));
+ if (previous) {
+ if (!owned(previous)) return respond(request, 'busy');
+ const previousReceipt = receipt(sessionId, previous);
+ if (previous.operationKey === operationKey) {
+ if (previousReceipt) return remember(operationKey, previousReceipt);
+ const recovered = yield* recoverMarker(sessionId, doc, previous);
+ return recovered && recovered !== 'deferred'
+ ? recovered
+ : respond(request, 'error', {
+ error: 'The previous delivery is still indeterminate.',
+ });
+ }
+ if (!previousReceipt)
+ return respond(request, 'busy', {
+ error: 'Another queue operation is being recovered.',
+ });
+ }
+ const target = yield* active.inspect(sessionId, expectedTurnId);
+ const row = (yield* persist(() => doc.getMessageQueue())).find(
+ (item) => item.$cid === queueItemId
+ );
+ if (!row) return respond(request, 'queue-item-missing');
+ if (hasActiveMessageQueueEditingLease(row))
+ return respond(request, 'queue-item-editing');
+ const entry = buildQueuedMessageUserTurn(row, meta, {
+ status: target.native ? 'pending_apply' : 'pending',
+ });
+ if (!entry) return respond(request, 'invalid-queue-item');
+ if (!target.native) {
+ const consumed = yield* persist(() =>
+ doc.consumeMessageQueueItemAsUserTurn(queueItemId, () => entry)
+ );
+ if (consumed.type !== 'consumed')
+ return respond(
+ request,
+ consumed.type === 'editing'
+ ? 'queue-item-editing'
+ : consumed.type === 'missing'
+ ? 'queue-item-missing'
+ : 'invalid-queue-item'
+ );
+ yield* flush();
+ const result = yield* active.cancel(sessionId, expectedTurnId).pipe(
+ Effect.as(respond(request, 'accepted', { userTurnId: entry.id })),
+ Effect.catchTag('ProviderRejected', (error) =>
+ Effect.succeed(
+ respond(request, 'error', { userTurnId: entry.id, error: error.message })
+ )
+ )
+ );
+ return remember(operationKey, result);
+ }
+ const inputConfig = normalizeSessionTurnInputConfig(entry.inputConfig);
+ if (!inputConfig || !entry.timestamp?.trim())
+ return respond(request, 'invalid-queue-item');
+ const marker = yield* write(sessionId, {
+ version: 2,
+ operationKey,
+ queueItemId,
+ expectedTurnId,
+ userTurnId: entry.id,
+ queueRevision: queueItemRevision(row),
+ phase: 'reserved',
+ });
+ const consumed = yield* persist(() =>
+ doc.consumeMessageQueueItemAsUserTurn(
+ queueItemId,
+ (item) =>
+ queueItemRevision(item) === marker.queueRevision
+ ? { ...entry, userId: target.requesterUserId }
+ : null,
+ { publishDispatch: false }
+ )
+ );
+ if (consumed.type !== 'consumed') {
+ return yield* complete(
+ sessionId,
+ marker,
+ respond(
+ request,
+ consumed.type === 'editing'
+ ? 'queue-item-editing'
+ : consumed.type === 'missing'
+ ? 'queue-item-missing'
+ : 'invalid-queue-item'
+ )
+ );
+ }
+ yield* flush();
+ yield* removeReservedRow(doc, marker);
+ const submitting = yield* write(sessionId, { ...marker, phase: 'submitting' });
+ return yield* active
+ .steer({
+ sessionId,
+ expectedTurnId,
+ turn: {
+ id: entry.id,
+ userId: target.requesterUserId,
+ timestamp: entry.timestamp,
+ inputConfig,
+ },
+ })
+ .pipe(
+ Effect.flatMap(() =>
+ flush().pipe(
+ Effect.flatMap(() => write(sessionId, { ...marker, phase: 'applied' })),
+ Effect.flatMap((applied) =>
+ complete(
+ sessionId,
+ applied,
+ respond(request, 'accepted', { userTurnId: entry.id })
+ )
+ )
+ )
+ ),
+ Effect.catchTag('ProviderRejected', (error) =>
+ fallback(
+ sessionId,
+ doc,
+ submitting,
+ respond(request, error.disposition, {
+ userTurnId: entry.id,
+ error: error.message,
+ })
+ )
+ ),
+ // Pre-submission ownership loss never cancels a newer active turn.
+ Effect.catchTag('StaleTurn', (error) =>
+ fallback(
+ sessionId,
+ doc,
+ submitting,
+ respond(request, error.disposition, {
+ userTurnId: entry.id,
+ error: error.message,
+ })
+ )
+ )
+ );
+ }).pipe(
+ Effect.catchTags({
+ StaleTurn: (error) =>
+ Effect.succeed(respond(request, error.disposition, { error: error.message })),
+ ProviderRejected: (error) =>
+ Effect.succeed(respond(request, error.disposition, { error: error.message })),
+ ProviderDeliveryUnknown: (error) =>
+ Effect.succeed(respond(request, 'error', { error: error.message })),
+ PersistenceFailure: (error) =>
+ Effect.succeed(respond(request, 'error', { error: error.message })),
+ })
+ )
+ );
+
+ const mutate = (request: SessionQueueMutation) =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ yield* active.guard(request.sessionId);
+ const doc = yield* persist(() =>
+ deps.workspaceDocument.getOrCreateSessionDoc(request.sessionId)
+ );
+ const meta = yield* persist(() => doc.getMetaState());
+ if (meta?.machineId !== deps.machineId) {
+ return {
+ type: 'session/queue-mutate_response' as const,
+ success: false,
+ error: 'This daemon does not own the queue.',
+ };
+ }
+ const marker = yield* persist(() =>
+ deps.queueSteerOperationStore.read(request.sessionId)
+ );
+ if (
+ marker &&
+ !marker.completedAt &&
+ (request.mutation.kind === 'reorder' ||
+ request.mutation.queueItemId === marker.queueItemId)
+ ) {
+ return {
+ type: 'session/queue-mutate_response' as const,
+ success: false,
+ error: 'A queue item is reserved for Steer. Retry after recovery.',
+ };
+ }
+ yield* persist(() => doc.mutateMessageQueue(request.mutation));
+ yield* flush();
+ return { type: 'session/queue-mutate_response' as const, success: true };
+ }).pipe(
+ Effect.catchAll((error) =>
+ Effect.succeed({
+ type: 'session/queue-mutate_response' as const,
+ success: false,
+ error: error.message,
+ })
+ )
+ )
+ );
+
+ return { steerQueueItem, recover, mutate };
+ });
+ }
+}
diff --git a/apps/cli/src/session/session-execution-service.ts b/apps/cli/src/session/session-execution-service.ts
index 3e6e4c0ca..acac76ab7 100644
--- a/apps/cli/src/session/session-execution-service.ts
+++ b/apps/cli/src/session/session-execution-service.ts
@@ -34,7 +34,6 @@ import {
type ProjectRef,
resolveBaseBranchPreference,
resolveProjectGitHubRepo,
- resolveSessionHistoryStatus,
getSessionRoomId,
getServerNow,
SessionCreateRequestValidated,
@@ -60,13 +59,23 @@ import {
hasBuiltinRuntimeOverrideValues,
getManagedBuiltinRuntimeByAgentType,
getManagedBuiltinRuntimeByRuntimeName,
- normalizeSessionTurnInputConfig,
serializeCustomAcpLaunchSpec,
} from '@lody/shared';
import type { ContentBlock } from '@agentclientprotocol/sdk';
import { randomUUID } from 'node:crypto';
import type { ModelInfo } from '@lody/shared';
-import { Cause, Data, Effect, Exit, Fiber, type Scope } from 'effect';
+import { Cause, Context, Data, Effect, Exit, Fiber, Layer, type Scope } from 'effect';
+import {
+ ActiveTurnSteerPort,
+ PersistenceFailure,
+ ProviderRejected,
+ ProviderDeliveryUnknown,
+ StaleTurn,
+ type NativeSteerInput,
+ type NativeSteerFailure,
+} from './active-turn-steer-port';
+import { QueueSteerService } from './queue-steer-service';
+import type { SessionQueueMutation } from '@lody/shared';
import {
captureGitWorkingTreeDiffBaseline,
getCurrentCommitHash,
@@ -108,7 +117,7 @@ import type { SessionActivePresencePhase } from '@/lib/loro/session-active-prese
import type { SessionConfig } from './types';
import type { ISession, SessionManager } from './session-manager';
import type { LoroDocumentManager, SessionDocument } from '@/lib/loro/doc';
-import { hasActiveMessageQueueEditingLease, subscribeSessionChanges } from '@/lib/loro/doc';
+import { subscribeSessionChanges } from '@/lib/loro/doc';
import { buildPrompt, normalizeSessionInputBlocks } from './session-execution-helpers';
import type { MemoryPressureEvictionResult } from '@/lib/session-gc-manager';
import {
@@ -116,10 +125,8 @@ import {
resolveResumableAcpSessionId,
} from './session-dispatch-logic';
import { resolveSessionLaunchConfig } from './session-launch-config-resolver';
-import { buildQueuedMessageUserTurn } from './queued-message-turn';
import {
isQueueSteerMarkerOwnedBy,
- type QueueSteerOperationMarker,
type QueueSteerOperationStore,
} from './session-queue-steer-operation-store';
import type { MachineAccessVerification } from './session-access-retry';
@@ -734,9 +741,6 @@ type TurnAnalyticsState = {
hasReplayPrompt: boolean;
};
-const QUEUE_STEER_RECEIPT_LIMIT = 512;
-type QueueSteerOperation = QueueSteerOperationMarker;
-
export class SessionExecutionService {
private readonly canceledTurnBySession = new Map();
private readonly currentTurnBySession = new Map();
@@ -751,8 +755,7 @@ export class SessionExecutionService {
// application never race the boundary. No global concurrency cap (Infinity):
// this is pure per-session serialization, matching the old hand-rolled lock.
private readonly steerMutationQueue = new ConcurrentQueue(Number.POSITIVE_INFINITY);
- /** Bounded receipts make a response-loss retry observationally idempotent. */
- private readonly queueSteerReceipts = new Map();
+ private readonly queueSteer: Context.Tag.Service;
// Analytics-only state (spec §5b). Tracks per-turn timing + the last status
// we reported so status_changed can carry from→to + dwell time. Never read by
// product logic; kept here so capture stays side-effect-only.
@@ -774,71 +777,83 @@ export class SessionExecutionService {
constructor(private readonly deps: SessionExecutionServiceDeps) {
this.acpAuthenticationManager = new AcpAuthenticationManager(deps.logger);
- }
-
- private rememberQueueSteerReceipt(
- operationKey: string,
- response: SessionQueueSteerResponse
- ): SessionQueueSteerResponse {
- this.queueSteerReceipts.delete(operationKey);
- this.queueSteerReceipts.set(operationKey, response);
- while (this.queueSteerReceipts.size > QUEUE_STEER_RECEIPT_LIMIT) {
- const oldest = this.queueSteerReceipts.keys().next().value;
- if (oldest === undefined) break;
- this.queueSteerReceipts.delete(oldest);
- }
- return response;
- }
-
- private async writeQueueSteerOperation(
- sessionId: SessionId,
- operation: Omit
- ): Promise {
- const durable = {
- ...operation,
- workspaceId: this.deps.workspaceId,
- machineId: this.deps.machineId,
- sessionId,
- updatedAt: getServerNow(),
- } satisfies QueueSteerOperation;
- await this.deps.queueSteerOperationStore.record(durable);
- return durable;
- }
-
- private async clearQueueSteerOperation(sessionId: SessionId): Promise {
- await this.deps.queueSteerOperationStore.clear(sessionId);
- }
-
- private queueSteerResponseFromOperation(
- sessionId: SessionId,
- operation: QueueSteerOperation
- ): SessionQueueSteerResponse | null {
- if (!operation.completedAt || !operation.response) return null;
- return {
- type: 'session/queue-steer_response',
- sessionId,
- queueItemId: operation.queueItemId,
- accepted: operation.response.disposition === 'accepted',
- disposition: operation.response.disposition,
- ...(operation.response.userTurnId ? { userTurnId: operation.response.userTurnId } : {}),
- ...(operation.response.error ? { error: operation.response.error } : {}),
- };
- }
-
- private async completeQueueSteerOperation(
- sessionId: SessionId,
- operation: QueueSteerOperation,
- response: SessionQueueSteerResponse
- ): Promise {
- return await this.writeQueueSteerOperation(sessionId, {
- ...operation,
- response: {
- disposition: response.disposition,
- ...(response.userTurnId ? { userTurnId: response.userTurnId } : {}),
- ...(response.error ? { error: response.error } : {}),
+ const self = this;
+ const active = ActiveTurnSteerPort.of({
+ guard: (sessionId) =>
+ Effect.acquireRelease(
+ Effect.sync(() => self.tryAcquireSessionRewriteConflictLease(sessionId)).pipe(
+ Effect.flatMap((release) =>
+ release
+ ? Effect.succeed(release)
+ : Effect.fail(
+ new StaleTurn({
+ disposition: 'busy',
+ message: 'The session history is being replaced.',
+ })
+ )
+ )
+ ),
+ (release) => Effect.sync(release)
+ ).pipe(Effect.asVoid),
+ inspect: (sessionId, expectedTurnId) =>
+ Effect.gen(function* () {
+ const runtime = self.turnRuntimeBySession.get(sessionId);
+ if (!runtime?.session || !runtime.promptInFlight || runtime.cancelRequested) {
+ return yield* new StaleTurn({
+ disposition: 'no-active-turn',
+ message: 'No active prompt owns this turn.',
+ });
+ }
+ if (runtime.turnId !== expectedTurnId) {
+ return yield* new StaleTurn({
+ disposition: 'stale-turn',
+ message: 'The active turn changed.',
+ });
+ }
+ const native = Boolean(
+ runtime.session.acpSessionId &&
+ runtime.session.agentClient?.getAcknowledgedSteerCapability()
+ );
+ const requesterUserId = runtime.invocation?.requesterUserId?.trim() ?? '';
+ if (native && !requesterUserId) {
+ return yield* new ProviderRejected({
+ disposition: 'error',
+ message: 'Active invocation identity is unavailable for native queue Steer.',
+ });
+ }
+ return { native, requesterUserId };
+ }),
+ steer: (input) => self.nativeSteerEffect(input),
+ cancel: (sessionId, expectedTurnId) =>
+ Effect.tryPromise({
+ try: async () => {
+ const response = await self.cancelSession({
+ type: 'session/cancel',
+ sessionId,
+ turnId: expectedTurnId,
+ machineId: deps.machineId,
+ workspaceId: deps.workspaceId,
+ });
+ if (!response.success)
+ throw new Error(response.error ?? 'The active turn could not be stopped.');
+ },
+ catch: (cause) =>
+ new ProviderRejected({ disposition: 'error', message: formatErrorMessage(cause) }),
+ }),
+ ownsPrompt: (sessionId, expectedTurnId) => {
+ const runtime = self.turnRuntimeBySession.get(sessionId);
+ return runtime?.turnId === expectedTurnId && runtime.promptInFlight;
},
- completedAt: getServerNow(),
+ activeUserTurnId: (sessionId) => self.getActiveUserTurnId(sessionId),
});
+ const queueLayer = QueueSteerService.layer({
+ ...deps,
+ requeue: (sessionId, userTurnId) =>
+ self.requeueUndeliveredSteer(sessionId, userTurnId, { canWriteHistory: true }),
+ failTurn: (sessionId, doc, userTurnId) =>
+ self.setTerminalUserTurnStatus(sessionId, doc, userTurnId, 'failed'),
+ }).pipe(Layer.provide(Layer.succeed(ActiveTurnSteerPort, active)));
+ this.queueSteer = Effect.runSync(QueueSteerService.pipe(Effect.provide(queueLayer)));
}
private createPromptHandoffRun(options: {
@@ -1477,792 +1492,350 @@ export class SessionExecutionService {
expectedTurnId: string;
queueItemId: string;
}): Promise {
- const operationKey = JSON.stringify([
- options.sessionId,
- options.expectedTurnId,
- options.queueItemId,
- ]);
- const respond = (
- disposition: SessionQueueSteerResponse['disposition'],
- details?: { userTurnId?: string; error?: string }
- ): SessionQueueSteerResponse => ({
- type: 'session/queue-steer_response',
- sessionId: options.sessionId,
- queueItemId: options.queueItemId,
- accepted: disposition === 'accepted',
- disposition,
- ...(details?.userTurnId ? { userTurnId: details.userTurnId } : {}),
- ...(details?.error ? { error: details.error } : {}),
- });
-
- return await this.steerMutationQueue.enqueue(options.sessionId, async () => {
- const previousReceipt = this.queueSteerReceipts.get(operationKey);
- if (previousReceipt) return previousReceipt;
+ return this.steerMutationQueue.enqueue(options.sessionId, () =>
+ Effect.runPromise(this.queueSteer.steerQueueItem(options))
+ );
+ }
- const releaseConflict = this.tryAcquireSessionRewriteConflictLease(options.sessionId);
- if (!releaseConflict) {
- return respond('busy', { error: 'The session history is being replaced.' });
- }
- let receiptEligible = false;
- let ownsDurableOperation = false;
- const finish = (response: SessionQueueSteerResponse): SessionQueueSteerResponse =>
- receiptEligible ? this.rememberQueueSteerReceipt(operationKey, response) : response;
- try {
- const sessionDoc = await this.deps.workspaceDocument.getOrCreateSessionDoc(
- options.sessionId
- );
- const meta = await sessionDoc.getMetaState();
- if (!meta) {
- return respond('error', { error: 'Session metadata is unavailable.' });
- }
+ async mutateQueuedMessage(request: SessionQueueMutation) {
+ return this.steerMutationQueue.enqueue(request.sessionId, () =>
+ Effect.runPromise(this.queueSteer.mutate(request))
+ );
+ }
- const previousOperation = await this.deps.queueSteerOperationStore.read(options.sessionId);
- if (previousOperation) {
- if (
- !isQueueSteerMarkerOwnedBy(
- previousOperation,
- this.deps.workspaceId,
- this.deps.machineId
- )
- ) {
- return respond('busy', { error: 'A queue Steer marker belongs to another owner.' });
- }
- const durableReceipt = this.queueSteerResponseFromOperation(
- options.sessionId,
- previousOperation
- );
- if (durableReceipt && previousOperation.operationKey === operationKey) {
- return this.rememberQueueSteerReceipt(operationKey, durableReceipt);
- }
- // A completed marker is the crash-safe receipt for the immediately
- // preceding operation. A new exact request may replace it.
- if (!durableReceipt && previousOperation.operationKey !== operationKey) {
- return respond('busy', { error: 'Another queued Steer is being recovered.' });
- }
- if (!durableReceipt) {
- const recovery = await this.recoverQueueSteerOperationLocked(
- options.sessionId,
- sessionDoc,
- previousOperation
- );
- if (recovery === 'deferred') {
- return respond('error', {
- userTurnId: previousOperation.userTurnId,
- error: 'The previous native Steer delivery is still indeterminate.',
- });
+ private async steerSessionLocked(options: {
+ sessionId: SessionId;
+ expectedTurnId: string;
+ userTurnId: string;
+ userId: string;
+ timestamp: string;
+ inputConfig: SessionTurnInputConfig;
+ }): Promise {
+ const self = this;
+ return Effect.runPromise(
+ this.nativeSteerEffect({
+ sessionId: options.sessionId,
+ expectedTurnId: options.expectedTurnId,
+ turn: {
+ id: options.userTurnId,
+ userId: options.userId,
+ timestamp: options.timestamp,
+ inputConfig: options.inputConfig,
+ },
+ }).pipe(
+ Effect.map(
+ (): SessionSteerResponse => ({
+ type: 'session/steer_response',
+ sessionId: options.sessionId,
+ userTurnId: options.userTurnId,
+ applied: true,
+ disposition: 'applied',
+ })
+ ),
+ Effect.catchAll((error) =>
+ Effect.gen(function* () {
+ if (error._tag === 'ProviderRejected' || error._tag === 'StaleTurn') {
+ yield* Effect.promise(() =>
+ self.requeueUndeliveredSteer(options.sessionId, options.userTurnId, {
+ canWriteHistory: true,
+ })
+ );
}
- return this.rememberQueueSteerReceipt(operationKey, recovery);
- }
- }
+ return {
+ type: 'session/steer_response' as const,
+ sessionId: options.sessionId,
+ userTurnId: options.userTurnId,
+ applied: false,
+ disposition:
+ error._tag === 'ProviderRejected' || error._tag === 'StaleTurn'
+ ? error.disposition
+ : ('error' as const),
+ error: error.message,
+ };
+ })
+ )
+ )
+ );
+ }
- const runtime = this.turnRuntimeBySession.get(options.sessionId);
- if (!runtime || !runtime.session || !runtime.promptInFlight || runtime.cancelRequested) {
- return respond('no-active-turn');
+ private nativeSteerEffect(
+ input: NativeSteerInput
+ ): Effect.Effect<{ userTurnId: string }, NativeSteerFailure> {
+ const self = this;
+ const options = {
+ ...input,
+ userTurnId: input.turn.id,
+ userId: input.turn.userId,
+ inputConfig: input.turn.inputConfig,
+ timestamp: input.turn.timestamp,
+ };
+ const prepare = (run: () => Promise ) =>
+ Effect.tryPromise({
+ try: run,
+ catch: (cause) => new PersistenceFailure({ cause, message: formatErrorMessage(cause) }),
+ });
+ return Effect.scoped(
+ Effect.gen(function* () {
+ const runtime = self.turnRuntimeBySession.get(options.sessionId);
+ if (!runtime?.session || !runtime.promptInFlight || runtime.cancelRequested) {
+ return yield* new StaleTurn({
+ disposition: 'no-active-turn',
+ message: 'No active prompt owns this turn.',
+ });
}
if (runtime.turnId !== options.expectedTurnId) {
- return respond('stale-turn');
- }
-
- const currentRuntime = this.turnRuntimeBySession.get(options.sessionId);
- if (
- currentRuntime !== runtime ||
- runtime.turnId !== options.expectedTurnId ||
- !runtime.promptInFlight ||
- runtime.cancelRequested
- ) {
- return respond('stale-turn');
- }
-
- const agentClient = runtime.session.agentClient;
- const useNativeSteer = Boolean(
- agentClient &&
- runtime.session.acpSessionId &&
- agentClient.getAcknowledgedSteerCapability()
- );
- const authenticatedRequesterUserId = runtime.invocation?.requesterUserId?.trim() ?? '';
- if (useNativeSteer && !authenticatedRequesterUserId) {
- return respond('error', {
- error: 'Active invocation identity is unavailable for native queue Steer.',
+ return yield* new StaleTurn({
+ disposition: 'stale-turn',
+ message: 'The active turn changed.',
});
}
-
- let nativeOperation: QueueSteerOperation | undefined;
- if (useNativeSteer) {
- const queuedItem = (await sessionDoc.getMessageQueue()).find(
- (item) => item.$cid === options.queueItemId
- );
- if (!queuedItem) return respond('queue-item-missing');
- const prepared = buildQueuedMessageUserTurn(queuedItem, meta, {
- status: 'pending_apply',
- });
- if (!prepared) return respond('invalid-queue-item');
- ownsDurableOperation = true;
- nativeOperation = await this.writeQueueSteerOperation(options.sessionId, {
- version: 1,
- operationKey,
- queueItemId: options.queueItemId,
- expectedTurnId: options.expectedTurnId,
- userTurnId: prepared.id,
- phase: 'reserved',
+ if (runtime.userTurnId === options.userTurnId) return { userTurnId: options.userTurnId };
+ const session = runtime.session;
+ const { agentClient, acpSessionId } = session;
+ const capability = agentClient?.getAcknowledgedSteerCapability();
+ if (!agentClient || !acpSessionId || !capability) {
+ return yield* new ProviderRejected({
+ disposition: 'unsupported',
+ message: 'Native Steer is unavailable.',
});
}
-
- // Queue order and immediate steering are separate mutations. Consume the
- // selected identity directly; A/B keep their relative order when C wins.
- // Native steer keeps the row as its durable retry record until handoff.
- const consumed = await sessionDoc.consumeMessageQueueItemAsUserTurn(
- options.queueItemId,
- (item) => {
- const queuedTurn = buildQueuedMessageUserTurn(item, meta, {
- status: useNativeSteer ? 'pending_apply' : 'pending',
+ if (capability.configPolicy === 'active') {
+ const mismatch = agentClient.findSteerConfigMismatch(options.inputConfig);
+ if (mismatch)
+ return yield* new ProviderRejected({
+ disposition: 'unsupported',
+ message: `Active turn configuration differs: ${mismatch}`,
});
- if (!queuedTurn || !useNativeSteer) return queuedTurn;
- if (nativeOperation && queuedTurn.id !== nativeOperation.userTurnId) return null;
- return { ...queuedTurn, userId: authenticatedRequesterUserId };
- },
- { publishDispatch: !useNativeSteer }
- );
- if (consumed.type === 'missing') {
- if (ownsDurableOperation) await this.clearQueueSteerOperation(options.sessionId);
- return respond('queue-item-missing');
}
- if (consumed.type === 'editing') {
- if (ownsDurableOperation) await this.clearQueueSteerOperation(options.sessionId);
- return respond('queue-item-editing');
- }
- if (consumed.type === 'invalid') {
- if (ownsDurableOperation) await this.clearQueueSteerOperation(options.sessionId);
- return respond('invalid-queue-item');
- }
- const entry = consumed.entry;
-
- if (useNativeSteer) {
- await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
- const inputConfig = normalizeSessionTurnInputConfig(entry.inputConfig);
- const timestamp = entry.timestamp?.trim();
- if (!inputConfig || !timestamp) {
- const invalid = respond('invalid-queue-item', {
- userTurnId: entry.id,
- error: 'The queued message cannot be converted to a steer turn.',
- });
- nativeOperation = await this.recoverQueueSteerAsDispatch(
- options.sessionId,
- sessionDoc,
- nativeOperation!,
- {
- disposition: invalid.disposition,
- userTurnId: invalid.userTurnId,
- error: invalid.error,
- }
- );
- nativeOperation = await this.completeQueueSteerOperation(
- options.sessionId,
- nativeOperation,
- invalid
- );
- receiptEligible = true;
- return finish(invalid);
- }
- let durableRejection = false;
- const nativeResult = await this.steerSessionLocked({
- sessionId: options.sessionId,
- expectedTurnId: options.expectedTurnId,
- userTurnId: entry.id,
- userId: authenticatedRequesterUserId,
- timestamp,
- inputConfig,
- onSubmitting: async () => {
- nativeOperation = await this.writeQueueSteerOperation(options.sessionId, {
- ...nativeOperation!,
- phase: 'submitting',
- });
- },
- onAcknowledged: async () => {
- nativeOperation = await this.writeQueueSteerOperation(options.sessionId, {
- ...nativeOperation!,
- phase: 'acknowledged',
+ const validateOwner = () =>
+ Effect.gen(function* () {
+ if (
+ self.turnRuntimeBySession.get(options.sessionId) !== runtime ||
+ runtime.turnId !== options.expectedTurnId
+ ) {
+ return yield* new StaleTurn({
+ disposition: 'stale-turn',
+ message: 'The active turn changed.',
});
- },
- onApplied: async () => {
- await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
- nativeOperation = await this.writeQueueSteerOperation(options.sessionId, {
- ...nativeOperation!,
- phase: 'applied',
+ }
+ if (!runtime.promptInFlight || runtime.cancelRequested) {
+ return yield* new StaleTurn({
+ disposition: 'no-active-turn',
+ message: 'The active turn is stopping.',
});
- },
- onUndelivered: async (disposition, error) => {
- nativeOperation = await this.recoverQueueSteerAsDispatch(
- options.sessionId,
- sessionDoc,
- nativeOperation!,
- {
- disposition,
- userTurnId: entry.id,
- ...(error ? { error } : {}),
- }
- );
- durableRejection = true;
- },
+ }
});
- const rejectedDisposition =
- nativeResult.disposition === 'applied' ? 'error' : nativeResult.disposition;
- if (nativeResult.applied) {
- await sessionDoc.removeMessageQueueItem(options.queueItemId);
- await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
- const accepted = respond('accepted', { userTurnId: entry.id });
- nativeOperation = await this.completeQueueSteerOperation(
- options.sessionId,
- nativeOperation!,
- accepted
- );
- receiptEligible = true;
- } else if (durableRejection) {
- const rejected = respond(rejectedDisposition, {
- userTurnId: entry.id,
- error: nativeResult.error,
- });
- nativeOperation = await this.completeQueueSteerOperation(
- options.sessionId,
- nativeOperation!,
- rejected
- );
- receiptEligible = true;
- }
- return finish(
- nativeResult.applied
- ? respond('accepted', { userTurnId: entry.id })
- : respond(rejectedDisposition, {
- userTurnId: entry.id,
- error: nativeResult.error,
- })
- );
- }
-
- receiptEligible = true;
-
- const cancellation = await this.cancelSession({
- type: 'session/cancel',
- sessionId: options.sessionId,
- machineId: this.deps.machineId,
- workspaceId: this.deps.workspaceId,
- turnId: options.expectedTurnId,
- });
- if (!cancellation.success) {
- return finish(
- respond('error', {
- userTurnId: entry.id,
- error: cancellation.error ?? 'The active turn could not be stopped.',
- })
- );
- }
- return finish(respond('accepted', { userTurnId: entry.id }));
- } catch (error) {
- return finish(respond('error', { error: formatErrorMessage(error) }));
- } finally {
- releaseConflict();
- }
- });
- }
-
- private async steerSessionLocked(options: {
- sessionId: SessionId;
- expectedTurnId: string;
- userTurnId: string;
- userId: string;
- timestamp: string;
- inputConfig: SessionTurnInputConfig;
- onSubmitting?: () => Promise;
- onAcknowledged?: () => Promise;
- onApplied?: () => Promise;
- onUndelivered?: (
- disposition: Exclude,
- error?: string
- ) => Promise;
- }): Promise {
- const reject = (
- disposition: Exclude,
- error?: string
- ): SessionSteerResponse => ({
- type: 'session/steer_response',
- sessionId: options.sessionId,
- userTurnId: options.userTurnId,
- applied: false,
- disposition,
- ...(error ? { error } : {}),
- });
- /**
- * The agent never took this prompt, so the user turn is still ours to run.
- * Only for rejections that provably happened before (or instead of) provider
- * submission — after submission the provider may already have committed the
- * steer, and re-sending would duplicate it.
- */
- const rejectUndelivered = async (
- disposition: Exclude,
- error?: string
- ): Promise => {
- recoveryAttempted = true;
- if (options.onUndelivered) {
- await options.onUndelivered(disposition, error);
- } else {
- await this.requeueUndeliveredSteer(options.sessionId, options.userTurnId, {
- canWriteHistory: true,
- });
- }
- return reject(disposition, error);
- };
- let recoveryAttempted = false;
- const runtime = this.turnRuntimeBySession.get(options.sessionId);
- if (!runtime || !runtime.session) {
- return await rejectUndelivered('no-active-turn');
- }
- if (runtime.turnId !== options.expectedTurnId) {
- return await rejectUndelivered('stale-turn');
- }
- if (!runtime.promptInFlight || runtime.cancelRequested) {
- return await rejectUndelivered('no-active-turn');
- }
- if (runtime.userTurnId === options.userTurnId) {
- return {
- type: 'session/steer_response',
- sessionId: options.sessionId,
- userTurnId: options.userTurnId,
- applied: true,
- disposition: 'applied',
- };
- }
- const { agentClient, acpSessionId } = runtime.session;
- const steerCapability = agentClient?.getAcknowledgedSteerCapability();
- if (!agentClient || !acpSessionId || !steerCapability) {
- return await rejectUndelivered('unsupported');
- }
- if (steerCapability.configPolicy === 'active') {
- const mismatch = agentClient.findSteerConfigMismatch(options.inputConfig);
- if (mismatch) {
- return await rejectUndelivered(
- 'unsupported',
- `Active turn configuration differs: ${mismatch}`
+ const sessionDoc = yield* prepare(() =>
+ self.deps.workspaceDocument.getOrCreateSessionDoc(options.sessionId)
);
- }
- }
- const rejectBeforeProviderSubmission = async (): Promise => {
- if (
- this.turnRuntimeBySession.get(options.sessionId) !== runtime ||
- runtime.turnId !== options.expectedTurnId
- ) {
- return await rejectUndelivered('stale-turn');
- }
- // No provider request has been submitted yet, so this guide is still
- // ours to run as an ordinary follow-up turn.
- if (!runtime.promptInFlight || runtime.cancelRequested) {
- return await rejectUndelivered('no-active-turn');
- }
- return null;
- };
-
- // Everything up to `steerPrompt` returning is provably undelivered; after
- // that only the agent's own inject-or-refuse verdict can say so.
- let submittedToAgent = false;
- try {
- const sessionDoc = await this.deps.workspaceDocument.getOrCreateSessionDoc(options.sessionId);
- const inputBlocks = normalizeSessionInputBlocks(
- options.inputConfig.inputBlocks,
- options.inputConfig.prompt ?? ''
- );
- const promptBlocks = await this.deps.buildAcpPromptBlocks({
- workspaceId: this.deps.workspaceId,
- sessionId: options.sessionId,
- inputBlocks,
- issuePRMentions: options.inputConfig.issuePRMentions,
- });
- const preConfigRejection = await rejectBeforeProviderSubmission();
- if (preConfigRejection) {
- return preConfigRejection;
- }
- if (steerCapability.configPolicy === 'apply') {
- await this.deps.applyAcpModeAndModel(runtime.session, options.inputConfig, {
- sessionDoc,
- basedOnUserTurnId: options.userTurnId,
- });
- }
-
- const preSubmitRejection = await rejectBeforeProviderSubmission();
- if (preSubmitRejection) {
- return preSubmitRejection;
- }
- const ownedPromptRun = runtime.activePromptRun;
- if (runtime.cancelRequested || !ownedPromptRun || ownedPromptRun.turnId !== runtime.turnId) {
- return await rejectUndelivered(
- 'busy',
- 'Prompt owner is cancelling or transitioning between logical turns'
+ const inputBlocks = normalizeSessionInputBlocks(
+ options.inputConfig.inputBlocks,
+ options.inputConfig.prompt ?? ''
);
- }
-
- const previousTurnId = runtime.turnId;
- const previousUserTurnId = runtime.userTurnId;
- await options.onSubmitting?.();
- const steerRun = agentClient.steerPrompt(acpSessionId, promptBlocks);
- submittedToAgent = true;
- const application = await steerRun.applied;
- try {
- try {
- await options.onAcknowledged?.();
- } catch (error) {
- this.deps.logger.error(
- `[${options.sessionId}] Failed to persist accepted steer ${options.userTurnId}: ${formatErrorMessage(error)}`
+ const promptBlocks = yield* prepare(() =>
+ self.deps.buildAcpPromptBlocks({
+ workspaceId: self.deps.workspaceId,
+ sessionId: options.sessionId,
+ inputBlocks,
+ issuePRMentions: options.inputConfig.issuePRMentions,
+ })
+ );
+ yield* validateOwner();
+ if (capability.configPolicy === 'apply') {
+ yield* prepare(() =>
+ self.deps.applyAcpModeAndModel(session, options.inputConfig, {
+ sessionDoc,
+ basedOnUserTurnId: options.userTurnId,
+ })
);
}
+ yield* validateOwner();
+ const ownedPromptRun = runtime.activePromptRun;
+ if (!ownedPromptRun || ownedPromptRun.turnId !== runtime.turnId) {
+ return yield* new StaleTurn({
+ disposition: 'busy',
+ message: 'Prompt ownership is transitioning.',
+ });
+ }
+ const previousTurnId = runtime.turnId;
+ const previousUserTurnId = runtime.userTurnId;
+ // Do not allow interruption between submission and registration of the local ACK cleanup.
+ const steerRun = yield* Effect.uninterruptible(
+ Effect.gen(function* () {
+ const run = yield* Effect.try({
+ try: () => agentClient.steerPrompt(acpSessionId, promptBlocks),
+ catch: (cause) =>
+ new ProviderRejected({
+ disposition:
+ cause instanceof AgentSteerNotDeliveredError ? 'no-active-turn' : 'error',
+ message: formatErrorMessage(cause),
+ }),
+ });
+ // This handle releases only the adapter's local ACK gate; submission is not a resource.
+ yield* Effect.acquireRelease(
+ Effect.tryPromise({
+ try: () => run.applied,
+ catch: (cause) =>
+ cause instanceof AgentSteerNotDeliveredError
+ ? new ProviderRejected({
+ disposition: 'no-active-turn',
+ message: formatErrorMessage(cause),
+ })
+ : new ProviderDeliveryUnknown({ cause, message: formatErrorMessage(cause) }),
+ }),
+ (application) => Effect.sync(() => application.release())
+ );
+ return run;
+ })
+ );
if (
runtime.cancelRequested ||
- this.turnRuntimeBySession.get(options.sessionId) !== runtime ||
+ self.turnRuntimeBySession.get(options.sessionId) !== runtime ||
!runtime.promptInFlight ||
runtime.turnId !== previousTurnId ||
runtime.activePromptRun !== ownedPromptRun
) {
- // Provider acceptance forbids replay; Stop keeps the source cancellation owner.
if (runtime.cancelRequested) {
- await this.setTerminalUserTurnStatus(
- options.sessionId,
- sessionDoc,
- options.userTurnId,
- 'canceled'
- );
+ yield* Effect.tryPromise({
+ try: () =>
+ self.setTerminalUserTurnStatus(
+ options.sessionId,
+ sessionDoc,
+ options.userTurnId,
+ 'canceled'
+ ),
+ catch: (cause) =>
+ new ProviderDeliveryUnknown({ cause, message: formatErrorMessage(cause) }),
+ });
}
- return reject(
- 'stale-turn',
- 'Steer application arrived after cancellation or ownership changed'
- );
- }
-
- // The provider has accepted this steer and may execute tools before
- // history/finalization catches up. Switch causal identity first.
- runtime.invocation = {
- sourceTurnId: options.userTurnId,
- requesterUserId: options.userId,
- inputConfig: options.inputConfig,
- };
- // Provider acceptance hands the original dispatch forward. A later
- // user-owned steer turn must not cancel or reopen that responsibility.
- await this.settleVisibleTurn(runtime, 'handled', { force: true });
-
- try {
- await this.finalizeYieldedTurnOutput(runtime, options.sessionId, previousTurnId);
- } catch (error) {
- this.deps.logger.error(
- `[${options.sessionId}] Failed to seal applied steer source ${previousTurnId}: ${formatErrorMessage(error)}`
- );
- }
- try {
- await this.transitionDispatchOwnership({
- sessionId: options.sessionId,
- sessionDoc,
- previousUserTurnId,
- nextUserTurnId: options.userTurnId,
+ return yield* new ProviderDeliveryUnknown({
+ message: 'Steer application arrived after cancellation or ownership changed.',
});
- } catch (error) {
- this.deps.logger.error(
- `[${options.sessionId}] Failed to persist applied steer ownership for ${options.userTurnId}: ${formatErrorMessage(error)}`
- );
- if (options.onApplied) throw error;
}
- const nextTurnId = this.deps.beginConversationTurn(options.sessionId, options.userTurnId, {
- dispatchSource: 'rpc',
- sessionDoc,
- });
- try {
- await this.deps.createAssistantEntryForTurn(
- options.sessionId,
- sessionDoc,
- nextTurnId,
- agentClient.currentModel,
- options.userTurnId
- );
- } catch (error) {
- this.deps.logger.error(
- `[${options.sessionId}] Failed to create assistant entry for applied steer ${nextTurnId}: ${formatErrorMessage(error)}`
- );
- }
- this.deps.activateConversationTurnForACPUpdates(options.sessionId, nextTurnId);
- const nextPromptRun = this.createPromptHandoffRun({
- turnId: nextTurnId,
- promptPromise: steerRun.completion,
- });
- void ownedPromptRun.promptOutcome.then((outcome) => {
- if (outcome.status === 'rejected') {
- this.deps.logger.debug(
- `[${options.sessionId}] Yielded prompt ${ownedPromptRun.turnId} failed after ownership moved forward: ${formatErrorMessage(outcome.error)}`
+ yield* Effect.tryPromise({
+ try: async () => {
+ // The provider has accepted this steer and may execute tools before
+ // history/finalization catches up. Switch causal identity first.
+ runtime.invocation = {
+ sourceTurnId: options.userTurnId,
+ requesterUserId: options.userId,
+ inputConfig: options.inputConfig,
+ };
+ // Provider acceptance hands the original dispatch forward. A later
+ // user-owned steer turn must not cancel or reopen that responsibility.
+ await self.settleVisibleTurn(runtime, 'handled', { force: true });
+
+ try {
+ await self.finalizeYieldedTurnOutput(runtime, options.sessionId, previousTurnId);
+ } catch (error) {
+ self.deps.logger.error(
+ `[${options.sessionId}] Failed to seal applied steer source ${previousTurnId}: ${formatErrorMessage(error)}`
+ );
+ }
+ try {
+ await self.transitionDispatchOwnership({
+ sessionId: options.sessionId,
+ sessionDoc,
+ previousUserTurnId,
+ nextUserTurnId: options.userTurnId,
+ });
+ } catch (error) {
+ self.deps.logger.error(
+ `[${options.sessionId}] Failed to persist applied steer ownership for ${options.userTurnId}: ${formatErrorMessage(error)}`
+ );
+ throw error;
+ }
+ const nextTurnId = self.deps.beginConversationTurn(
+ options.sessionId,
+ options.userTurnId,
+ {
+ dispatchSource: 'rpc',
+ sessionDoc,
+ }
);
- }
+ try {
+ await self.deps.createAssistantEntryForTurn(
+ options.sessionId,
+ sessionDoc,
+ nextTurnId,
+ agentClient.currentModel,
+ options.userTurnId
+ );
+ } catch (error) {
+ self.deps.logger.error(
+ `[${options.sessionId}] Failed to create assistant entry for applied steer ${nextTurnId}: ${formatErrorMessage(error)}`
+ );
+ }
+ self.deps.activateConversationTurnForACPUpdates(options.sessionId, nextTurnId);
+ const nextPromptRun = self.createPromptHandoffRun({
+ turnId: nextTurnId,
+ promptPromise: steerRun.completion,
+ });
+ void ownedPromptRun.promptOutcome.then((outcome) => {
+ if (outcome.status === 'rejected') {
+ self.deps.logger.debug(
+ `[${options.sessionId}] Yielded prompt ${ownedPromptRun.turnId} failed after ownership moved forward: ${formatErrorMessage(outcome.error)}`
+ );
+ }
+ });
+ ownedPromptRun.successor = nextPromptRun;
+ runtime.activePromptRun = nextPromptRun;
+ runtime.turnId = nextTurnId;
+ runtime.userTurnId = options.userTurnId;
+ self.markCurrentTurn(options.sessionId, nextTurnId);
+ ownedPromptRun.signalSuccessor();
+ },
+ catch: (cause) =>
+ new ProviderDeliveryUnknown({ cause, message: formatErrorMessage(cause) }),
});
- ownedPromptRun.successor = nextPromptRun;
- runtime.activePromptRun = nextPromptRun;
- runtime.turnId = nextTurnId;
- runtime.userTurnId = options.userTurnId;
- this.markCurrentTurn(options.sessionId, nextTurnId);
- ownedPromptRun.signalSuccessor();
- await options.onApplied?.();
- return {
- type: 'session/steer_response',
- sessionId: options.sessionId,
- userTurnId: options.userTurnId,
- applied: true,
- disposition: 'applied',
- };
- } finally {
- application.release();
- }
- } catch (error) {
- if (recoveryAttempted) {
- throw error;
- }
- const notDelivered = !submittedToAgent || error instanceof AgentSteerNotDeliveredError;
- if (!notDelivered) {
- return reject('error', formatErrorMessage(error));
- }
- // `no-active-turn` for the agent's own refusal: it is the disposition
- // steer-aware clients already treat as "re-send this turn normally", so
- // an older client recovers the message too.
- return await rejectUndelivered(
- error instanceof AgentSteerNotDeliveredError ? 'no-active-turn' : 'error',
- formatErrorMessage(error)
- );
- }
- }
-
- /**
- * Reconcile a durable native queue-Steer saga after daemon restart or a
- * failed recovery write. Provider calls are never replayed: only a reserved
- * or already-fallback operation is provably safe to publish as an ordinary
- * turn. A submitting/acknowledged operation becomes a visible failure once
- * its original prompt owner is gone because ACP has no query/idempotency
- * contract that could distinguish "not sent" from "already injected". An
- * applied operation has already committed local ownership and is only cleaned
- * up; its accepted receipt survives a lost response and daemon restart.
- */
- async recoverPendingQueueSteer(
- sessionId: SessionId,
- sessionDoc: SessionDocument
- ): Promise {
- return await this.steerMutationQueue.enqueue(sessionId, async () => {
- const releaseConflict = this.tryAcquireSessionRewriteConflictLease(sessionId);
- if (!releaseConflict) return 'deferred';
- try {
- const operation = await this.deps.queueSteerOperationStore.read(sessionId);
- if (!operation) return null;
- if (!isQueueSteerMarkerOwnedBy(operation, this.deps.workspaceId, this.deps.machineId)) {
- return 'deferred';
- }
- return await this.recoverQueueSteerOperationLocked(sessionId, sessionDoc, operation);
- } finally {
- releaseConflict();
- }
- });
- }
-
- async recoverPendingQueueSteers(): Promise {
- let operations: QueueSteerOperation[];
- try {
- operations = await this.deps.queueSteerOperationStore.list();
- } catch (error) {
- this.deps.logger.error(
- `[queue-steer] Failed to list recovery markers: ${formatErrorMessage(error)}`
- );
- return;
- }
- for (const operation of operations) {
- if (
- operation.completedAt ||
- !isQueueSteerMarkerOwnedBy(operation, this.deps.workspaceId, this.deps.machineId)
- ) {
- continue;
- }
- try {
- const sessionId = operation.sessionId as SessionId;
- const sessionDoc = await this.deps.workspaceDocument.getOrCreateSessionDoc(sessionId);
- await this.recoverPendingQueueSteer(sessionId, sessionDoc);
- } catch (error) {
- this.deps.logger.error(
- `[${operation.sessionId}] Failed to recover queued Steer ${operation.operationKey}: ${formatErrorMessage(error)}`
- );
- }
- }
+ return { userTurnId: options.userTurnId };
+ })
+ );
}
- private async recoverQueueSteerOperationLocked(
- sessionId: SessionId,
- sessionDoc: SessionDocument,
- operation: QueueSteerOperation
- ): Promise {
- const durableReceipt = this.queueSteerResponseFromOperation(sessionId, operation);
- if (durableReceipt) return durableReceipt;
- const runtime = this.turnRuntimeBySession.get(sessionId);
- if (
- (operation.phase === 'submitting' || operation.phase === 'acknowledged') &&
- runtime?.turnId === operation.expectedTurnId &&
- runtime.promptInFlight
- ) {
- return 'deferred';
- }
-
- await sessionDoc.waitUntilSynced?.();
- const history = readSessionHistory(sessionDoc.sessionData.history);
- const entry = history.find(
- (candidate) => candidate.role === 'user' && candidate.id === operation.userTurnId
+ async recoverPendingQueueSteer(sessionId: SessionId, sessionDoc: SessionDocument) {
+ return this.steerMutationQueue.enqueue(sessionId, () =>
+ Effect.runPromise(this.queueSteer.recover(sessionId, sessionDoc))
);
- if (!entry) {
- if (operation.phase === 'reserved') {
- // The index is written before queue consumption. No history entry means
- // the crash happened before reservation crossed the history boundary.
- const response = {
- type: 'session/queue-steer_response',
- sessionId,
- queueItemId: operation.queueItemId,
- accepted: false,
- disposition: 'error',
- userTurnId: operation.userTurnId,
- error: 'The daemon restarted before the queued Steer reservation completed.',
- } satisfies SessionQueueSteerResponse;
- await this.completeQueueSteerOperation(sessionId, operation, response);
- return response;
- }
- this.deps.logger.error(
- `[${sessionId}] Queue Steer ${operation.operationKey} is ${operation.phase} but its history entry is unavailable`
- );
- return 'deferred';
- }
-
- if (operation.phase === 'reserved' || operation.phase === 'fallback') {
- const fallbackResponse = operation.response ?? {
- disposition: 'error' as const,
- userTurnId: operation.userTurnId,
- error: 'The daemon restarted before native Steer submission; the turn was queued instead.',
- };
- const fallbackOperation = await this.recoverQueueSteerAsDispatch(
- sessionId,
- sessionDoc,
- operation,
- fallbackResponse
- );
- const response = {
- type: 'session/queue-steer_response',
- sessionId,
- queueItemId: operation.queueItemId,
- accepted: false,
- ...fallbackResponse,
- } satisfies SessionQueueSteerResponse;
- await this.completeQueueSteerOperation(sessionId, fallbackOperation, response);
- return response;
- }
-
- const historyStatus = resolveSessionHistoryStatus(entry);
- if (operation.phase === 'applied' || runtime?.userTurnId === operation.userTurnId) {
- if (
- runtime?.userTurnId !== operation.userTurnId &&
- historyStatus !== 'handled' &&
- historyStatus !== 'failed' &&
- historyStatus !== 'canceled'
- ) {
- await this.setTerminalUserTurnStatus(sessionId, sessionDoc, operation.userTurnId, 'failed');
- await this.deps.recordChatFailure(
- sessionDoc,
- 'agent_disconnected',
- 'The daemon restarted after this Steer was applied. The provider call was not replayed.'
- );
- }
- await sessionDoc.removeMessageQueueItem(operation.queueItemId);
- await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
- const response = {
- type: 'session/queue-steer_response',
- sessionId,
- queueItemId: operation.queueItemId,
- accepted: true,
- disposition: 'accepted',
- userTurnId: operation.userTurnId,
- } satisfies SessionQueueSteerResponse;
- await this.completeQueueSteerOperation(
- sessionId,
- { ...operation, phase: 'applied' },
- response
- );
- return response;
- }
-
- if (historyStatus === 'handled') {
- await sessionDoc.removeMessageQueueItem(operation.queueItemId);
- await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
- const response = {
- type: 'session/queue-steer_response',
- sessionId,
- queueItemId: operation.queueItemId,
- accepted: true,
- disposition: 'accepted',
- userTurnId: operation.userTurnId,
- } satisfies SessionQueueSteerResponse;
- await this.completeQueueSteerOperation(
- sessionId,
- { ...operation, phase: 'applied' },
- response
- );
- return response;
- }
-
- if (historyStatus !== 'failed' && historyStatus !== 'canceled') {
- await this.setTerminalUserTurnStatus(sessionId, sessionDoc, operation.userTurnId, 'failed');
- await this.deps.recordChatFailure(
- sessionDoc,
- 'agent_disconnected',
- operation.phase === 'acknowledged'
- ? 'The daemon restarted after the agent acknowledged this Steer but before local handoff completed. It was not replayed because that could execute it twice.'
- : 'The daemon restarted while delivering this Steer. Delivery could not be confirmed, so it was not replayed.'
- );
- }
- await sessionDoc.removeMessageQueueItem(operation.queueItemId);
- await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
- const response = {
- type: 'session/queue-steer_response',
- sessionId,
- queueItemId: operation.queueItemId,
- accepted: false,
- disposition: 'error',
- userTurnId: operation.userTurnId,
- error:
- operation.phase === 'acknowledged'
- ? 'The agent acknowledged this Steer before the daemon restarted, but local handoff did not complete; it was not replayed.'
- : 'Native Steer delivery became indeterminate when the daemon restarted; it was not replayed.',
- } satisfies SessionQueueSteerResponse;
- await this.completeQueueSteerOperation(sessionId, operation, response);
- return response;
}
- private async recoverQueueSteerAsDispatch(
- sessionId: SessionId,
- sessionDoc: SessionDocument,
- operation: QueueSteerOperation,
- response: NonNullable
- ): Promise {
- const queueItem = (await sessionDoc.getMessageQueue()).find(
- (item) => item.$cid === operation.queueItemId
+ async recoverPendingQueueSteers(): Promise {
+ const self = this;
+ await Effect.runPromise(
+ Effect.tryPromise(() => this.deps.queueSteerOperationStore.list()).pipe(
+ Effect.flatMap((markers) =>
+ Effect.forEach(
+ markers.filter(
+ (marker) =>
+ !marker.completedAt &&
+ isQueueSteerMarkerOwnedBy(marker, self.deps.workspaceId, self.deps.machineId)
+ ),
+ (marker) =>
+ Effect.tryPromise(async () => {
+ const sessionId = marker.sessionId as SessionId;
+ const doc = await self.deps.workspaceDocument.getOrCreateSessionDoc(sessionId);
+ await self.recoverPendingQueueSteer(sessionId, doc);
+ }).pipe(
+ Effect.catchAll((error) =>
+ Effect.sync(() =>
+ self.deps.logger.error(
+ `[${marker.sessionId}] Queue Steer recovery failed: ${formatErrorMessage(error)}`
+ )
+ )
+ )
+ ),
+ { discard: true }
+ )
+ ),
+ Effect.catchAll((error) =>
+ Effect.sync(() =>
+ self.deps.logger.error(
+ `[queue-steer] Failed to list recovery markers: ${formatErrorMessage(error)}`
+ )
+ )
+ )
+ )
);
- if (queueItem && hasActiveMessageQueueEditingLease(queueItem)) {
- throw new Error(`Queued Steer ${operation.userTurnId} is being edited`);
- }
- let fallbackOperation = operation;
- if (operation.phase !== 'fallback' || operation.response !== response) {
- fallbackOperation = await this.writeQueueSteerOperation(sessionId, {
- ...operation,
- phase: 'fallback',
- response,
- completedAt: undefined,
- });
- }
- const recovery = await this.requeueUndeliveredSteer(sessionId, operation.userTurnId, {
- canWriteHistory: true,
- });
- if (recovery === 'requeue-failed') {
- throw new Error(`Failed to durably recover queued Steer ${operation.userTurnId}`);
- }
- await sessionDoc.removeMessageQueueItem(operation.queueItemId);
- await this.deps.workspaceDocument.persistPendingChanges('queue-steer-commit');
- return fallbackOperation;
}
/**
diff --git a/apps/cli/src/session/session-queue-steer-operation-store.test.ts b/apps/cli/src/session/session-queue-steer-operation-store.test.ts
index 02beac641..50aa01ea8 100644
--- a/apps/cli/src/session/session-queue-steer-operation-store.test.ts
+++ b/apps/cli/src/session/session-queue-steer-operation-store.test.ts
@@ -67,7 +67,7 @@ describe('file queue Steer operation store', () => {
await store.record(marker);
const root = path.join(tempHome, '.lody', 'session-queue-steer-operations');
await writeFile(path.join(root, 'corrupt.json'), 'not json', 'utf8');
- await writeFile(path.join(root, 'future.json'), JSON.stringify({ ...marker, version: 2 }));
+ await writeFile(path.join(root, 'future.json'), JSON.stringify({ ...marker, version: 999 }));
await expect(store.list()).resolves.toEqual([marker]);
});
});
diff --git a/apps/cli/src/session/session-queue-steer-operation-store.ts b/apps/cli/src/session/session-queue-steer-operation-store.ts
index 98936ad92..d8513efea 100644
--- a/apps/cli/src/session/session-queue-steer-operation-store.ts
+++ b/apps/cli/src/session/session-queue-steer-operation-store.ts
@@ -33,7 +33,7 @@ const QueueSteerResponseSchema = z
const QueueSteerOperationMarkerSchema = z
.object({
- version: z.literal(1),
+ version: z.union([z.literal(1), z.literal(2)]),
workspaceId: z.string().min(1),
machineId: z.string().min(1),
sessionId: z.string().min(1),
@@ -41,6 +41,7 @@ const QueueSteerOperationMarkerSchema = z
queueItemId: z.string().min(1),
expectedTurnId: z.string().min(1),
userTurnId: z.string().min(1),
+ queueRevision: z.string().min(1).optional(),
phase: z.enum(['reserved', 'submitting', 'acknowledged', 'applied', 'fallback']),
response: QueueSteerResponseSchema.optional(),
completedAt: z.number().finite().optional(),
diff --git a/apps/cli/tests/session-execution-service.test.ts b/apps/cli/tests/session-execution-service.test.ts
index 6928ab5c6..d249e5522 100644
--- a/apps/cli/tests/session-execution-service.test.ts
+++ b/apps/cli/tests/session-execution-service.test.ts
@@ -1,3 +1,6 @@
+import { queueItemRevision } from '@lody/shared';
+import { SessionDocument } from '../src/lib/loro/doc';
+import { composeTestSessionDoc } from './session-doc-fixture';
import { withHistoryPort } from './history-port-fixture';
import { describe, expect, it, vi } from 'vitest';
import fs from 'node:fs';
@@ -246,6 +249,336 @@ const createBaseDeps = (
};
describe('SessionExecutionService', () => {
+ const ownedQueue = async () => {
+ const sessionId = 'session-owned-queue' as SessionId;
+ let meta = {
+ id: sessionId,
+ userId: 'owner-user',
+ machineId: 'machine-1',
+ cliType: 'builtin',
+ agentType: 'codex',
+ } as SessionMeta;
+ const repo = {
+ getDocMeta: async () => ({ meta }),
+ upsertDocMeta: async (_room: string, patch: Partial) => {
+ meta = { ...meta, ...patch };
+ },
+ };
+ const doc = new SessionDocument(repo as never, sessionId, async () => {}, createSilentLogger());
+ composeTestSessionDoc(doc);
+ vi.spyOn(doc, 'waitUntilSynced').mockResolvedValue(undefined);
+ for (const task of ['A', 'B', 'C'])
+ await doc.pushMessageQueue({
+ task,
+ userId: 'queue-author',
+ userTurnId: 'user:' + task,
+ timestamp: '2026-09-14T00:00:00.000Z',
+ acpSessionConfig: { prompt: task, cliType: 'builtin', agentType: 'codex' },
+ });
+ const rows = await doc.getMessageQueue();
+ const flush = vi.fn(async (_reason: string) => {});
+ const evidence: string[] = [];
+ const steerPrompt = vi.fn(() => {
+ evidence.push('submitted');
+ return {
+ applied: Promise.reject<{ release: () => void }>(new Error('delivery unknown')),
+ completion: Promise.resolve(),
+ };
+ });
+ const deps = createBaseDeps({
+ workspaceDocument: {
+ repo,
+ getOrCreateSessionDoc: async () => doc,
+ persistPendingChanges: flush,
+ } as never,
+ buildAcpPromptBlocks: async ({ inputBlocks }) => inputBlocks as ContentBlock[],
+ });
+ const service = new SessionExecutionService(deps);
+ const runtime = {
+ sessionId,
+ turnId: 'assistant:active',
+ userTurnId: 'user:active',
+ promptInFlight: true,
+ cancelRequested: false,
+ activePromptRun: {
+ turnId: 'assistant:active',
+ promptOutcome: Promise.resolve({ status: 'fulfilled' as const }),
+ signalSuccessor: () => {},
+ },
+ invocation: { requesterUserId: 'authenticated-user', inputConfig: { prompt: 'active' } },
+ session: {
+ acpSessionId: 'acp-owned',
+ agentClient: {
+ getAcknowledgedSteerCapability: () => ({ provider: 'codex', configPolicy: 'active' }),
+ findSteerConfigMismatch: () => null,
+ steerPrompt,
+ },
+ },
+ };
+ (
+ service as unknown as { turnRuntimeBySession: Map }
+ ).turnRuntimeBySession.set(sessionId, runtime);
+ return {
+ service,
+ doc,
+ rows,
+ deps,
+ flush,
+ steerPrompt,
+ evidence,
+ runtime,
+ request: { sessionId, expectedTurnId: runtime.turnId, queueItemId: rows[2]!.$cid },
+ };
+ };
+
+ it.each(['update', 'remove', 'reorder'] as const)(
+ 'rejects a stale second-client %s after reservation, with removal durable before submission',
+ async (kind) => {
+ const h = await ownedQueue();
+ const entered = createDeferred();
+ const release = createDeferred();
+ let commits = 0;
+ h.flush.mockImplementation(async () => {
+ commits++;
+ if (commits === 1) {
+ expect((await h.doc.sessionData.history.readAll()).at(-1)).toMatchObject({
+ id: 'user:C',
+ status: 'pending_apply',
+ userId: 'authenticated-user',
+ });
+ entered.resolve();
+ await release.promise;
+ }
+ if (commits === 2) {
+ expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(['A', 'B']);
+ h.evidence.push('removal-durable');
+ }
+ });
+ const steering = h.service.steerQueuedMessage(h.request);
+ await entered.promise;
+ expect(h.service.tryAcquireSessionRewriteConflictLease(h.request.sessionId)).toBeNull();
+ const mutation =
+ kind === 'reorder'
+ ? {
+ kind,
+ orderedItemIds: h.rows.map((row) => row.$cid).reverse(),
+ expectedItemIds: h.rows.map((row) => row.$cid),
+ }
+ : {
+ kind,
+ queueItemId: h.request.queueItemId,
+ expectedRevision: queueItemRevision(h.rows[2]),
+ ...(kind === 'update' ? { patch: { task: 'Roll back instead' } } : {}),
+ };
+ const editing = h.service.mutateQueuedMessage({
+ sessionId: h.request.sessionId,
+ mutation,
+ } as never);
+ release.resolve();
+ await expect(steering).resolves.toMatchObject({ accepted: false, disposition: 'error' });
+ await expect(editing).resolves.toMatchObject({ success: false });
+ expect(h.evidence).toEqual(['removal-durable', 'submitted']);
+ expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(['A', 'B']);
+ // A retry cannot turn unknown external delivery into ordinary dispatch.
+ await h.service.steerQueuedMessage(h.request);
+ expect(h.evidence).toEqual(['removal-durable', 'submitted']);
+ const releaseOwnership = h.service.tryAcquireSessionRewriteConflictLease(h.request.sessionId);
+ expect(releaseOwnership).not.toBeNull();
+ releaseOwnership?.();
+ }
+ );
+
+ it('commits a native handoff and returns its durable receipt after restart', async () => {
+ const h = await ownedQueue();
+ let released = false;
+ h.steerPrompt.mockImplementation(() => ({
+ applied: Promise.resolve({
+ release: () => {
+ released = true;
+ },
+ }),
+ completion: Promise.resolve(),
+ }));
+ await expect(h.service.steerQueuedMessage(h.request)).resolves.toMatchObject({
+ accepted: true,
+ userTurnId: 'user:C',
+ });
+ expect(released).toBe(true);
+ expect(h.runtime.userTurnId).toBe('user:C');
+ expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(['A', 'B']);
+ await expect(h.deps.queueSteerOperationStore.read(h.request.sessionId)).resolves.toMatchObject({
+ phase: 'applied',
+ response: { disposition: 'accepted', userTurnId: 'user:C' },
+ });
+ const restarted = new SessionExecutionService(h.deps);
+ await expect(restarted.steerQueuedMessage(h.request)).resolves.toMatchObject({
+ accepted: true,
+ userTurnId: 'user:C',
+ });
+ });
+
+ it('preserves an accepted edit on a surviving legacy reservation instead of deleting it', async () => {
+ const h = await ownedQueue();
+ await h.doc.consumeMessageQueueItemAsUserTurn(
+ h.request.queueItemId,
+ () => ({
+ id: 'user:C',
+ userId: 'authenticated-user',
+ timestamp: '2026-09-14T00:00:00.000Z',
+ role: 'user',
+ status: 'pending_apply',
+ read: false,
+ items: [{ type: 'text', text: 'C' }],
+ inputConfig: { prompt: 'C', cliType: 'builtin', agentType: 'codex' },
+ }),
+ { publishDispatch: false }
+ );
+ await h.deps.queueSteerOperationStore.record({
+ version: 1,
+ workspaceId: 'workspace-1',
+ machineId: 'machine-1',
+ sessionId: h.request.sessionId,
+ operationKey: 'legacy',
+ queueItemId: h.request.queueItemId,
+ userTurnId: 'user:C',
+ expectedTurnId: h.request.expectedTurnId,
+ phase: 'reserved',
+ updatedAt: 1,
+ });
+ await h.doc.mutateMessageQueue({
+ kind: 'update',
+ queueItemId: h.request.queueItemId,
+ expectedRevision: queueItemRevision(h.rows[2]),
+ patch: {
+ task: 'Rollback',
+ acpSessionConfig: { prompt: 'Rollback', cliType: 'builtin', agentType: 'codex' },
+ },
+ });
+ const restarted = new SessionExecutionService(h.deps);
+ await expect(restarted.recoverPendingQueueSteer(h.request.sessionId, h.doc)).rejects.toThrow(
+ 'preserved'
+ );
+ expect((await h.doc.getMessageQueue())[2]?.task).toBe('Rollback');
+ expect(h.evidence).toEqual([]);
+ });
+
+ it('freezes an edit committed before reservation, not the stale renderer text', async () => {
+ const h = await ownedQueue();
+ await expect(
+ h.service.mutateQueuedMessage({
+ sessionId: h.request.sessionId,
+ mutation: {
+ kind: 'update',
+ queueItemId: h.request.queueItemId,
+ expectedRevision: queueItemRevision(h.rows[2]),
+ patch: {
+ task: 'Roll back instead',
+ acpSessionConfig: {
+ prompt: 'Roll back instead',
+ cliType: 'builtin',
+ agentType: 'codex',
+ },
+ },
+ },
+ })
+ ).resolves.toMatchObject({ success: true });
+ await h.service.steerQueuedMessage(h.request);
+ const entry = (await h.doc.sessionData.history.readAll()).find(
+ (candidate) => candidate.id === 'user:C'
+ );
+ expect(entry).toMatchObject({ inputConfig: { prompt: 'Roll back instead' } });
+ expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(['A', 'B']);
+ });
+
+ it.each(['remove', 'reorder'] as const)(
+ 'honors a %s committed before reservation',
+ async (kind) => {
+ const h = await ownedQueue();
+ const mutation =
+ kind === 'remove'
+ ? {
+ kind,
+ queueItemId: h.request.queueItemId,
+ expectedRevision: queueItemRevision(h.rows[2]),
+ }
+ : {
+ kind,
+ orderedItemIds: h.rows.map((row) => row.$cid).reverse(),
+ expectedItemIds: h.rows.map((row) => row.$cid),
+ };
+ await expect(
+ h.service.mutateQueuedMessage({ sessionId: h.request.sessionId, mutation })
+ ).resolves.toMatchObject({ success: true });
+ const result = await h.service.steerQueuedMessage(h.request);
+ if (kind === 'remove') {
+ expect(result.disposition).toBe('queue-item-missing');
+ expect(h.evidence).toEqual([]);
+ }
+ expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(
+ kind === 'remove' ? ['A', 'B'] : ['B', 'A']
+ );
+ }
+ );
+
+ it('rejects queue writes sent to a daemon other than the session owner', async () => {
+ const h = await ownedQueue();
+ const meta = await h.doc.getMetaState();
+ vi.spyOn(h.doc, 'getMetaState').mockResolvedValue({
+ ...meta,
+ machineId: 'another-machine',
+ } as SessionMeta);
+ await expect(
+ h.service.mutateQueuedMessage({
+ sessionId: h.request.sessionId,
+ mutation: {
+ kind: 'remove',
+ queueItemId: h.request.queueItemId,
+ expectedRevision: queueItemRevision(h.rows[2]),
+ },
+ })
+ ).resolves.toMatchObject({ success: false, error: 'This daemon does not own the queue.' });
+ expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(['A', 'B', 'C']);
+ });
+
+ it.each(['reservation', 'history', 'removal', 'submission-marker'] as const)(
+ 'does not submit after a %s persistence failure and recovers without a shared row',
+ async (stage) => {
+ const h = await ownedQueue();
+ let count = 0;
+ const record = h.deps.queueSteerOperationStore.record.bind(h.deps.queueSteerOperationStore);
+ vi.spyOn(h.deps.queueSteerOperationStore, 'record').mockImplementation(async (marker) => {
+ if (
+ (stage === 'reservation' && marker.phase === 'reserved') ||
+ (stage === 'submission-marker' && marker.phase === 'submitting')
+ )
+ throw new Error('disk unavailable');
+ await record(marker);
+ });
+ h.flush.mockImplementation(async () => {
+ count++;
+ if ((stage === 'history' && count === 1) || (stage === 'removal' && count === 2))
+ throw new Error('disk unavailable');
+ });
+ await expect(h.service.steerQueuedMessage(h.request)).resolves.toMatchObject({
+ accepted: false,
+ error: 'disk unavailable',
+ });
+ expect(h.evidence).toEqual([]);
+ const release = h.service.tryAcquireSessionRewriteConflictLease(h.request.sessionId);
+ expect(release).not.toBeNull();
+ release?.();
+ if (stage !== 'reservation') {
+ const restarted = new SessionExecutionService(h.deps);
+ await restarted.recoverPendingQueueSteer(h.request.sessionId, h.doc);
+ expect(
+ (await h.doc.sessionData.history.readAll()).find((entry) => entry.id === 'user:C')?.status
+ ).toMatch(/^(pending|seen)$/);
+ expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(['A', 'B']);
+ expect(h.evidence).toEqual([]);
+ }
+ }
+ );
+
it('cancels only the named native child and rejects a stale parent turn', async () => {
const runningChildren = new Set(['child-1', 'child-2']);
const sessionManager = {
@@ -300,6 +633,7 @@ describe('SessionExecutionService', () => {
);
const history: SessionHistoryInput[] = [];
const sessionDoc = {
+ getMessageQueue: async () => queue,
getMetaState: vi.fn(async () => ({
id: sessionId,
userId: 'owner-user',
@@ -384,6 +718,7 @@ describe('SessionExecutionService', () => {
cliType: 'builtin',
agentType: 'codex',
})),
+ getMessageQueue: async () => [],
consumeMessageQueueItemAsUserTurn: vi.fn(async () => ({ type: 'missing' as const })),
};
const deps = createBaseDeps({
@@ -445,6 +780,16 @@ describe('SessionExecutionService', () => {
.mockResolvedValue({ type: 'consumed' as const, entry });
const sessionDoc = {
getMetaState: vi.fn(async () => ({ id: sessionId })),
+ getMessageQueue: async () => [
+ {
+ $cid: 'C',
+ task: 'task C',
+ userId: 'owner-user',
+ userTurnId: 'user:C',
+ timestamp: '2026-09-13T00:00:00.000Z',
+ acpSessionConfig: { prompt: 'task C' },
+ },
+ ],
consumeMessageQueueItemAsUserTurn,
};
const service = new SessionExecutionService(
@@ -504,6 +849,17 @@ describe('SessionExecutionService', () => {
cliType: 'builtin',
agentType: 'codex',
})),
+ getMessageQueue: async () =>
+ [
+ {
+ $cid: 'C',
+ task: 'task C',
+ userId: 'owner-user',
+ userTurnId: 'user:C',
+ timestamp: '2026-09-13T00:00:00.000Z',
+ acpSessionConfig: { prompt: 'task C' },
+ },
+ ].map((item) => ({ ...item, isEditing: true, editingStartedAt: Number.MAX_SAFE_INTEGER })),
consumeMessageQueueItemAsUserTurn: vi.fn(async () => ({ type: 'editing' as const })),
};
const service = new SessionExecutionService(
@@ -551,6 +907,16 @@ describe('SessionExecutionService', () => {
};
const sessionDoc = {
getMetaState: vi.fn(async () => ({ id: sessionId })),
+ getMessageQueue: async () => [
+ {
+ $cid: 'C',
+ task: 'task C',
+ userId: 'owner-user',
+ userTurnId: 'user:C',
+ timestamp: '2026-09-13T00:00:00.000Z',
+ acpSessionConfig: { prompt: 'task C' },
+ },
+ ],
consumeMessageQueueItemAsUserTurn: vi.fn(async () => ({
type: 'consumed' as const,
entry,
@@ -685,7 +1051,7 @@ describe('SessionExecutionService', () => {
const persistPendingChanges = vi.fn(async (reason: string) => {
if (reason !== 'queue-steer-commit') return;
queueSteerPersistenceCount += 1;
- if (queueSteerPersistenceCount === 2) {
+ if (queueSteerPersistenceCount === 4) {
throw new Error('queue Steer persistence unavailable');
}
});
@@ -758,17 +1124,14 @@ describe('SessionExecutionService', () => {
await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
accepted: false,
disposition: 'error',
- error: expect.stringContaining('Failed to durably recover'),
+ error: expect.stringContaining('Failed to recover'),
});
await expect(queueSteerOperationStore.read(sessionId)).resolves.toMatchObject({
phase: 'fallback',
completedAt: undefined,
});
expect(history).toEqual([expect.objectContaining({ id: 'user:C', status: 'pending' })]);
- expect(queue).toHaveLength(1);
- expect(
- (service as unknown as { queueSteerReceipts: Map }).queueSteerReceipts.size
- ).toBe(0);
+ expect(queue).toEqual([]);
await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
accepted: false,
@@ -779,9 +1142,6 @@ describe('SessionExecutionService', () => {
phase: 'fallback',
completedAt: undefined,
});
- expect(
- (service as unknown as { queueSteerReceipts: Map }).queueSteerReceipts.size
- ).toBe(0);
await expect(service.steerQueuedMessage(request)).resolves.toMatchObject({
accepted: false,
@@ -795,7 +1155,7 @@ describe('SessionExecutionService', () => {
completedAt: expect.any(Number),
response: { disposition: 'no-active-turn', error: 'provider refused' },
});
- expect(upsertDocMeta.mock.calls.filter(([, patch]) => patch.latestUserMsgId)).toHaveLength(3);
+ expect(meta.latestUserMsgId).toBe('user:C');
const restartedService = new SessionExecutionService(deps);
await expect(restartedService.steerQueuedMessage(request)).resolves.toMatchObject({
@@ -803,7 +1163,7 @@ describe('SessionExecutionService', () => {
disposition: 'no-active-turn',
error: 'provider refused',
});
- expect(upsertDocMeta.mock.calls.filter(([, patch]) => patch.latestUserMsgId)).toHaveLength(3);
+ expect(meta.latestUserMsgId).toBe('user:C');
});
it.each(['submitting', 'acknowledged', 'applied'] as const)(
@@ -811,7 +1171,8 @@ describe('SessionExecutionService', () => {
async (phase) => {
const sessionId = `session-native-steer-crash-${phase}` as SessionId;
const operation = {
- version: 1 as const,
+ version: 2 as const,
+ queueRevision: queueItemRevision({ $cid: 'C' }),
workspaceId: 'workspace-1',
machineId: 'machine-1',
sessionId,
@@ -883,18 +1244,14 @@ describe('SessionExecutionService', () => {
expect(deps.recordChatFailure).toHaveBeenCalledWith(
sessionDoc,
'agent_disconnected',
- expect.stringContaining(phase === 'applied' ? 'was applied' : 'not replayed')
+ expect.stringContaining('not replayed')
);
}
);
it('recovers a crash after native reservation by dispatching that exact row', async () => {
const sessionId = 'session-native-steer-crash-reserved' as SessionId;
- let queue = [
- { $cid: 'A' },
- { $cid: 'B' },
- { $cid: 'C', isEditing: true, editingStartedAt: Number.MAX_SAFE_INTEGER },
- ];
+ let queue = [{ $cid: 'A' }, { $cid: 'B' }, { $cid: 'C' }];
let history: SessionHistoryInput[] = [
{
id: 'user:C',
@@ -935,6 +1292,7 @@ describe('SessionExecutionService', () => {
workspaceId: 'workspace-1',
machineId: 'machine-1',
sessionId,
+ queueRevision: queueItemRevision({ $cid: 'C' }),
operationKey: 'operation-reserved',
queueItemId: 'C',
expectedTurnId: 'assistant:old',
@@ -953,14 +1311,6 @@ describe('SessionExecutionService', () => {
);
await service.recoverPendingQueueSteers();
- expect(queue.map((item) => item.$cid)).toEqual(['A', 'B', 'C']);
- const editingMarker = await queueSteerOperationStore.read(sessionId);
- expect(editingMarker).toMatchObject({ phase: 'reserved' });
- expect(editingMarker?.completedAt).toBeUndefined();
-
- queue = queue.map((item) => (item.$cid === 'C' ? { ...item, isEditing: false } : item));
- await service.recoverPendingQueueSteers();
-
expect(history).toEqual([expect.objectContaining({ id: 'user:C', status: 'pending' })]);
expect(queue).toEqual([{ $cid: 'A' }, { $cid: 'B' }]);
expect(meta).toMatchObject({ latestUserMsgId: 'user:C' });
@@ -6372,7 +6722,7 @@ describe('SessionExecutionService', () => {
steerApplied.resolve({ release: () => steerReleased.resolve() });
await expect(steering).resolves.toMatchObject({
applied: false,
- disposition: 'stale-turn',
+ disposition: 'error',
});
await steerReleased.promise;
expect(onTurnSettled).not.toHaveBeenCalled();
diff --git a/locales/en.json b/locales/en.json
index aa14124ba..76d99cdda 100644
--- a/locales/en.json
+++ b/locales/en.json
@@ -1795,7 +1795,7 @@
"sessions.messageQueue.saveEdit": "Save changes (Enter)",
"sessions.messageQueue.title": "Queued messages",
"sessions.messageQueue.upNext": "Up next",
- "sessions.messageQueue.updateAgentForLaterSteer": "Update the local agent to steer a later queued message",
+ "sessions.messageQueue.draftDisplaced": "This message left the queue. Your unsaved draft is kept below; copy it before dismissing.",
"sessions.messageStatus.deliverNow": "Deliver now",
"sessions.messageStatus.deliverNowFailed": "Failed to deliver the message - please try again",
"sessions.messageStatus.notDelivered": "Not delivered",
diff --git a/locales/zh_CN.json b/locales/zh_CN.json
index fbfb2e4e5..630f009a2 100644
--- a/locales/zh_CN.json
+++ b/locales/zh_CN.json
@@ -1795,7 +1795,7 @@
"sessions.messageQueue.saveEdit": "保存修改（回车）",
"sessions.messageQueue.title": "排队中的消息",
"sessions.messageQueue.upNext": "接下来",
- "sessions.messageQueue.updateAgentForLaterSteer": "更新本地 Agent 后才能引导后续排队消息",
+ "sessions.messageQueue.draftDisplaced": "这条消息已离开队列。未保存的草稿仍保留在下方，请在关闭前复制。",
"sessions.messageStatus.deliverNow": "重新发送",
"sessions.messageStatus.deliverNowFailed": "送达失败，请重试",
"sessions.messageStatus.notDelivered": "未送达",
diff --git a/packages/components/src/components/sessions/message-queue/AGENTS.md b/packages/components/src/components/sessions/message-queue/AGENTS.md
index 2428e91f1..b444364fd 100644
--- a/packages/components/src/components/sessions/message-queue/AGENTS.md
+++ b/packages/components/src/components/sessions/message-queue/AGENTS.md
@@ -11,9 +11,9 @@ queued-turn list (`message-queue-display.tsx`, `message-queue-row.tsx`,
Exact-item Steer requires the negotiated `queueItemSteer` daemon protocol; missing means
unsupported. The daemon chooses acknowledged native Steer or exact cancel-and-dispatch.
-For older daemons, an authoritative `acknowledgedSteer` capability must retain the legacy
-native path; otherwise only queue-head interrupt stays enabled. Never reorder a later row
-to emulate Steer. A missing, stale, or actively edited exact target must leave the current
+No supported version means no Steer on any row, including the head; no legacy native/cancel path.
+Daemon-reserved rows reject edits/removal/reordering; retain a rejected edit's local draft even
+when the last row disappears. Never reorder to emulate Steer. A missing, stale, or edited target leaves the current
turn running. A row's number and message body are one drag activator; its actions stay out.
The queue intentionally stays OUT of the composer info bar
diff --git a/packages/components/src/components/sessions/message-queue/index.ts b/packages/components/src/components/sessions/message-queue/index.ts
index bc994ea31..078978312 100644
--- a/packages/components/src/components/sessions/message-queue/index.ts
+++ b/packages/components/src/components/sessions/message-queue/index.ts
@@ -4,11 +4,6 @@ export { MessageQueueRow } from './message-queue-row';
export type { MessageQueueRowProps } from './message-queue-row';
export { QueuedImagePreview } from './queued-image-preview';
export type { QueuedImageBlock } from './queued-image-preview';
-export {
- resolveQueuedMessageSteerRoute,
- shouldUseLegacyNativeQueueSteer,
- type QueuedMessageSteerRoute,
-} from './queued-message-steer-compat';
export {
useMessageQueueEditing,
getEditableTaskText,
diff --git a/packages/components/src/components/sessions/message-queue/message-queue-display.tsx b/packages/components/src/components/sessions/message-queue/message-queue-display.tsx
index 2e1255060..94e92a4c4 100644
--- a/packages/components/src/components/sessions/message-queue/message-queue-display.tsx
+++ b/packages/components/src/components/sessions/message-queue/message-queue-display.tsx
@@ -63,6 +63,11 @@ export function MessageQueueDisplay({
const [overflow, setOverflow] = useState(NO_SCROLL_EDGE_OVERFLOW);
const editing = useMessageQueueEditing(items, { onEditStart, onEditCancel, onEditSave });
+ const displacedDraft =
+ editing.editingItem && !items.some((item) => item.$cid === editing.editingCid)
+ ? editing.editingItem
+ : null;
+ const visibleItems = displacedDraft ? [...items, displacedDraft] : items;
const itemIds = useMemo(() => items.map((item) => item.$cid), [items]);
const canReorder = items.length > 1;
@@ -107,7 +112,7 @@ export function MessageQueueDisplay({
[onReorder]
);
- if (items.length === 0) {
+ if (items.length === 0 && !displacedDraft) {
return null;
}
@@ -146,13 +151,21 @@ export function MessageQueueDisplay({
WebkitMaskImage: fadeMask,
}}
>
+ {displacedDraft && (
+
+ {t(
+ 'sessions.messageQueue.draftDisplaced',
+ 'This message left the queue. Your unsaved draft is kept below; copy it before dismissing.'
+ )}
+
+ )}
- {items.map((item, index) => {
+ {visibleItems.map((item, index) => {
const isEditing = editing.editingCid === item.$cid;
return (
0}
steerDisabledReason={steerDisabledReason}
- canReorder={canReorder}
+ canReorder={canReorder && !displacedDraft}
isEditing={isEditing}
editValue={isEditing ? editing.editValue : ''}
isPending={editing.pendingCid === item.$cid}
diff --git a/packages/components/src/components/sessions/message-queue/queued-message-steer-compat.ts b/packages/components/src/components/sessions/message-queue/queued-message-steer-compat.ts
deleted file mode 100644
index a926a0136..000000000
--- a/packages/components/src/components/sessions/message-queue/queued-message-steer-compat.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import type { AcpCapabilityAuthority, AcpCapabilityCacheEntry } from '@lody/shared';
-
-/**
- * Older daemons have no exact-item queue RPC. Only their acknowledged ACP
- * capability can preserve true in-prompt steering; an absent or provisional
- * cache entry must not be guessed into support.
- */
-export function shouldUseLegacyNativeQueueSteer(
- authority: AcpCapabilityAuthority,
- capability: Pick | undefined
-): boolean {
- return authority === 'authoritative' && capability?.acknowledgedSteer === true;
-}
-
-export type QueuedMessageSteerRoute = 'exact-daemon' | 'legacy-native' | 'legacy-head';
-
-export function resolveQueuedMessageSteerRoute(options: {
- supportsExactDaemonProtocol: boolean;
- authority: AcpCapabilityAuthority;
- capability: Pick | undefined;
-}): QueuedMessageSteerRoute {
- if (options.supportsExactDaemonProtocol) return 'exact-daemon';
- return shouldUseLegacyNativeQueueSteer(options.authority, options.capability)
- ? 'legacy-native'
- : 'legacy-head';
-}
diff --git a/packages/components/src/components/sessions/message-queue/use-message-queue-editing.ts b/packages/components/src/components/sessions/message-queue/use-message-queue-editing.ts
index 90256c4bb..005415e18 100644
--- a/packages/components/src/components/sessions/message-queue/use-message-queue-editing.ts
+++ b/packages/components/src/components/sessions/message-queue/use-message-queue-editing.ts
@@ -19,6 +19,7 @@ export type MessageQueueEditingCallbacks = {
export type MessageQueueEditing = {
editingCid: string | null;
+ editingItem: MessageQueueItem | null;
editValue: string;
pendingCid: string | null;
setEditValue: (value: string) => void;
@@ -33,6 +34,7 @@ export function useMessageQueueEditing(
): MessageQueueEditing {
const { onEditStart, onEditCancel, onEditSave } = callbacks;
const [editingCid, setEditingCid] = useState(null);
+ const [editingItem, setEditingItem] = useState(null);
const [editValue, setEditValue] = useState('');
const [pendingCid, setPendingCid] = useState(null);
@@ -40,6 +42,7 @@ export function useMessageQueueEditing(
const itemsRef = useRef(items);
const editingCidRef = useRef(null);
const onEditCancelRef = useRef(onEditCancel);
+ const dismissedLeaseRef = useRef<{ cid: string; startedAt?: number } | null>(null);
useEffect(() => {
itemsRef.current = items;
@@ -55,31 +58,34 @@ export function useMessageQueueEditing(
useEffect(() => {
return () => {
const cid = editingCidRef.current;
- const item = cid
- ? itemsRef.current.find((candidate) => candidate.$cid === cid)
- : undefined;
+ const item = cid ? itemsRef.current.find((candidate) => candidate.$cid === cid) : undefined;
if (item?.isEditing) {
- void onEditCancelRef.current(item);
+ void Promise.resolve()
+ .then(() => onEditCancelRef.current(item))
+ .catch((error) => {
+ console.error('Failed to release queued message editing lease', error);
+ });
}
};
}, []);
- // Sync local editing state with server-side `isEditing` flag: if the row disappears or another
- // client opens an edit, reflect it.
+ // A displaced row must not discard an unsaved local draft.
useEffect(() => {
if (editingCid) {
- const item = items.find((candidate) => candidate.$cid === editingCid);
- if (!item) {
- setEditingCid(null);
- setEditValue('');
- }
return;
}
- const editingItem = items.find((item) => item.isEditing);
- if (editingItem) {
- setEditingCid(editingItem.$cid);
- setEditValue(getEditableTaskText(editingItem));
+ const sharedEditor = items.find((item) => item.isEditing);
+ if (sharedEditor) {
+ const dismissed = dismissedLeaseRef.current;
+ if (
+ dismissed?.cid === sharedEditor.$cid &&
+ dismissed.startedAt === sharedEditor.editingStartedAt
+ )
+ return;
+ setEditingCid(sharedEditor.$cid);
+ setEditingItem(sharedEditor);
+ setEditValue(getEditableTaskText(sharedEditor));
}
}, [editingCid, items]);
@@ -95,7 +101,9 @@ export function useMessageQueueEditing(
await onEditCancel(previous);
}
await onEditStart(item);
+ dismissedLeaseRef.current = null;
setEditingCid(item.$cid);
+ setEditingItem(item);
setEditValue(getEditableTaskText(item));
} catch (error) {
console.error('Failed to start queued message edit', error);
@@ -110,8 +118,11 @@ export function useMessageQueueEditing(
async (item: MessageQueueItem) => {
setPendingCid(item.$cid);
try {
- await onEditCancel(item);
+ if (itemsRef.current.some((candidate) => candidate.$cid === item.$cid))
+ await onEditCancel(item);
+ dismissedLeaseRef.current = { cid: item.$cid, startedAt: item.editingStartedAt };
setEditingCid(null);
+ setEditingItem(null);
setEditValue('');
} catch (error) {
console.error('Failed to cancel queued message edit', error);
@@ -127,7 +138,10 @@ export function useMessageQueueEditing(
setPendingCid(item.$cid);
try {
await onEditSave(item, editValue.trim());
+ // The daemon ACK can precede its CRDT delta; do not reopen the stale shared lease.
+ dismissedLeaseRef.current = { cid: item.$cid, startedAt: item.editingStartedAt };
setEditingCid(null);
+ setEditingItem(null);
setEditValue('');
} catch (error) {
console.error('Failed to save queued message edit', error);
@@ -140,6 +154,7 @@ export function useMessageQueueEditing(
return {
editingCid,
+ editingItem,
editValue,
pendingCid,
setEditValue,
diff --git a/packages/components/src/components/sessions/session-chat-interface.tsx b/packages/components/src/components/sessions/session-chat-interface.tsx
index 522ef450c..c436e3cb6 100644
--- a/packages/components/src/components/sessions/session-chat-interface.tsx
+++ b/packages/components/src/components/sessions/session-chat-interface.tsx
@@ -68,7 +68,7 @@ import {
type SessionTurnAgentRoleSelection,
} from './session-chat-input-area';
import { useSessionMcpSelection } from '@/hooks/use-session-mcp-selection';
-import { MessageQueueDisplay, resolveQueuedMessageSteerRoute } from './message-queue';
+import { MessageQueueDisplay } from './message-queue';
import { useTranslation } from 'react-i18next';
import { useRouter } from '@tanstack/react-router';
import { toast } from 'sonner';
@@ -5104,19 +5104,11 @@ export const SessionChatInterface = memo(
[captureSessionEvent, reorderMessageQueueItem, t]
);
- const queueSteerCapability = session.agentConfigId
- ? sessionMachine?.acpCapabilities?.[getAcpCapabilityCacheKey(session.agentConfigId)]
- : undefined;
- const queuedMessageSteerRoute = resolveQueuedMessageSteerRoute({
- supportsExactDaemonProtocol: machineSupportsQueueItemSteerProtocol(sessionMachine),
- authority: capabilityAuthority,
- capability: queueSteerCapability,
- });
- const legacyQueueSteerRequiresHead = queuedMessageSteerRoute === 'legacy-head';
+ const supportsQueueItemSteer = machineSupportsQueueItemSteerProtocol(sessionMachine);
- const handleExactQueueItemSteer = useCallback(
+ const handleSteerQueuedMessage = useCallback(
async (item: MessageQueueItem) => {
- if (isExternalHistoryRefreshing || !activeAssistantTurnId) {
+ if (isExternalHistoryRefreshing || !activeAssistantTurnId || !supportsQueueItemSteer) {
return;
}
if (steeringQueueItemIdsRef.current.has(item.$cid)) return;
@@ -5167,141 +5159,13 @@ export const SessionChatInterface = memo(
captureSessionEvent,
isExternalHistoryRefreshing,
requestSessionQueueSteer,
+ supportsQueueItemSteer,
session.id,
session.machineId,
t,
]
);
- const handleLegacyNativeQueueSteer = useCallback(
- async (item: MessageQueueItem) => {
- if (isExternalHistoryRefreshing || !activeAssistantTurnId) return;
- if (steeringQueueItemIdsRef.current.has(item.$cid)) return;
- steeringQueueItemIdsRef.current.add(item.$cid);
- try {
- const inputConfig = normalizeSessionTurnInputConfig(item.acpSessionConfig);
- const userId = item.userId?.trim() || currentUser?.id;
- if (!inputConfig || !userId) {
- throw new Error('Queued message input is invalid');
- }
- const inputBlocks = normalizeSessionInputBlocks(
- inputConfig.inputBlocks,
- inputConfig.prompt ?? item.task
- );
- const pendingHistoryEntry = buildPendingUserHistoryEntry({
- userId,
- inputBlocks,
- timestamp: item.timestamp,
- inputConfig,
- status: 'pending_apply',
- });
- if (!pendingHistoryEntry) throw new Error('Queued message is empty');
-
- const queuedUserTurnId = item.userTurnId?.trim() || `queued-${item.$cid}`;
- const { entry } = await addSessionHistory({
- ...pendingHistoryEntry,
- id: queuedUserTurnId,
- });
- await removeMessageQueueItem(item.$cid);
- trackMessageSend(entry.id);
- void touchSessionActivity(session.id).catch((error: unknown) => {
- console.warn('Failed to update session activity for steer', error);
- });
- const applied = await guideHistoryEntry(entry.id, activeAssistantTurnId);
- captureSessionEvent('session/queue_legacy_native_steer_result', {
- queue_item_id: item.$cid,
- active_assistant_turn_id: activeAssistantTurnId,
- applied,
- });
- } catch (error) {
- console.error('Failed to steer queued message through legacy native path', error);
- captureSessionEvent('session/queue_legacy_native_steer_failed', {
- queue_item_id: item.$cid,
- active_assistant_turn_id: activeAssistantTurnId,
- error_name: error instanceof Error ? error.name : typeof error,
- error_message: getErrorMessage(error),
- });
- toast.error(t('sessions.sendError'), { description: getErrorMessage(error) });
- } finally {
- steeringQueueItemIdsRef.current.delete(item.$cid);
- }
- },
- [
- activeAssistantTurnId,
- addSessionHistory,
- captureSessionEvent,
- currentUser?.id,
- guideHistoryEntry,
- isExternalHistoryRefreshing,
- removeMessageQueueItem,
- session.id,
- t,
- touchSessionActivity,
- trackMessageSend,
- ]
- );
-
- const handleLegacyHeadQueueSteer = useCallback(
- async (item: MessageQueueItem) => {
- if (
- isExternalHistoryRefreshing ||
- !activeAssistantTurnId ||
- messageQueue[0]?.$cid !== item.$cid
- ) {
- return;
- }
- setInputActionState('ready');
- pendingUserInterruptRef.current = true;
- try {
- await requestSessionCancel(session.id, activeAssistantTurnId);
- captureSessionEvent('session/queue_legacy_head_steer_succeeded', {
- queue_item_id: item.$cid,
- active_assistant_turn_id: activeAssistantTurnId,
- });
- } catch (error) {
- pendingUserInterruptRef.current = false;
- captureSessionEvent('session/queue_legacy_head_steer_failed', {
- queue_item_id: item.$cid,
- active_assistant_turn_id: activeAssistantTurnId,
- error_name: error instanceof Error ? error.name : typeof error,
- error_message: getErrorMessage(error),
- });
- toast.error(t('sessions.interruptFailed', 'Failed to interrupt current task'), {
- description: getErrorMessage(error),
- });
- }
- },
- [
- activeAssistantTurnId,
- captureSessionEvent,
- isExternalHistoryRefreshing,
- messageQueue,
- requestSessionCancel,
- session.id,
- t,
- ]
- );
-
- const handleSteerQueuedMessage = useCallback(
- async (item: MessageQueueItem) => {
- if (queuedMessageSteerRoute === 'exact-daemon') {
- await handleExactQueueItemSteer(item);
- return;
- }
- if (queuedMessageSteerRoute === 'legacy-native') {
- await handleLegacyNativeQueueSteer(item);
- return;
- }
- await handleLegacyHeadQueueSteer(item);
- },
- [
- handleExactQueueItemSteer,
- handleLegacyHeadQueueSteer,
- handleLegacyNativeQueueSteer,
- queuedMessageSteerRoute,
- ]
- );
-
const handleStartQueueItemEdit = useCallback(
async (item: MessageQueueItem) => {
const isFirstItem = messageQueue[0]?.$cid === item.$cid;
@@ -6201,28 +6065,24 @@ export const SessionChatInterface = memo(
commandsEnabled={isVisible}
freeTurnLimitNotice={freeSessionTurnNotice}
queueDisplay={
- messageQueue.length > 0 ? (
-
+ next as unknown as Record,
+ queueItemRevision(current)
);
},
[withStore, runtime, sessionId]
@@ -371,7 +375,11 @@ export function useSessionDoc(
// Full-order is idempotent and robust across the intent wire; compute the
// resulting `$cid` order renderer-side.
const orderedItemIds = arrayMove(mq, fromIndex, toIndex).map((item) => item.$cid);
- await runtime.writer.reorderSessionMessages(sessionId, orderedItemIds);
+ await runtime.writer.reorderSessionMessages(
+ sessionId,
+ orderedItemIds,
+ mq.map((item) => item.$cid)
+ );
},
[withStore, runtime, sessionId]
);
diff --git a/packages/components/src/providers/AGENTS.md b/packages/components/src/providers/AGENTS.md
index 9aaa61d70..de3d4c568 100644
--- a/packages/components/src/providers/AGENTS.md
+++ b/packages/components/src/providers/AGENTS.md
@@ -53,6 +53,9 @@ and update only decision fields through HistoryWriter; never replace a rendered
- `create-workspace-runtime.ts` maintains one Repo view. `WorkspaceTargetRouter` owns
target ownership and transport selection; do not restore a second writer or a
proxy-authoring/write-intent mirror.
+- Queue edit/remove/reorder on queueItemSteer v2 use the narrow daemon domain RPC,
+ with revision checks against reservation ownership. Never direct-write after RPC failure.
+ Enqueue and other user writes retain their renderer authority.
- Repo storage, durable Streams cursors, and eager-sync high-water state must use the
same per-renderer cache namespace. A checkpoint must never be shared by independently
persisted Repo views.
diff --git a/packages/components/src/providers/create-workspace-runtime.ts b/packages/components/src/providers/create-workspace-runtime.ts
index 5e24f3fdf..cba1ad310 100644
--- a/packages/components/src/providers/create-workspace-runtime.ts
+++ b/packages/components/src/providers/create-workspace-runtime.ts
@@ -1,3 +1,4 @@
+import { machineSupportsQueueItemSteerProtocol, type SessionMeta } from '@lody/shared';
import { jotaiStore } from '@/lib/utils';
import { desktopWindowId } from '@/lib/desktop-window';
import { navigationSidebarHiddenAtom } from '@/atoms/layout-state';
@@ -1689,6 +1690,7 @@ export async function createWorkspaceRuntime(deps: RuntimeDeps): Promise repo.unloadDoc(getTaskRoomId(taskId)),
});
- // Dual-author: every client direct-authors its own durable writes and uploads
- // them over its own cloud connection; local targets additionally converge with
- // the CLI over the local plane (specs/local-first-two-plane.md 作者规则).
+ // Queue controls share the daemon's reservation authority; other user writes remain local.
const workspaceWriter = createDirectWorkspaceWriter({
repo,
+ mutateQueue: async (request) => {
+ const session = await repo.getDocMeta(getSessionRoomId(request.sessionId));
+ const machineId = (session?.meta as Partial | undefined)?.machineId;
+ if (!machineId) throw new Error('Queue owner is unavailable.');
+ const machine = await repo.getDocMeta(getMachineRoomId(machineId));
+ if (!machine) throw new Error('Queue owner capabilities are unavailable.');
+ const protocolCapabilities = (machine.meta as Partial).protocolCapabilities;
+ if (!machineSupportsQueueItemSteerProtocol({ protocolCapabilities })) return false;
+ const response = await requestSessionQueueMutation(machineId, request);
+ if (!response?.success)
+ throw new Error(response?.error ?? 'Queue change could not be confirmed.');
+ return true;
+ },
acquireSessionStore: sessionStoreCache.acquire,
releaseSessionStoreRef: sessionStoreCache.releaseRef,
acquirePreviewVisualCommentStore: previewVisualCommentStoreCache.acquire,
diff --git a/packages/components/src/providers/workspace-machine-rpc-facade.ts b/packages/components/src/providers/workspace-machine-rpc-facade.ts
index f7138862c..3d2fda48b 100644
--- a/packages/components/src/providers/workspace-machine-rpc-facade.ts
+++ b/packages/components/src/providers/workspace-machine-rpc-facade.ts
@@ -1,3 +1,4 @@
+import type { SessionQueueMutation, SessionQueueMutationResponse } from '@lody/shared';
import type { LocalFilePreviewResource } from '@lody/shared/local-file-preview';
import type {
LoroStreamsMachineRpcClient,
@@ -770,6 +771,40 @@ export function createWorkspaceMachineRpcFacade(deps: WorkspaceMachineRpcFacadeD
}
};
+ const requestSessionQueueMutation = async (
+ machineId: MachineId,
+ args: SessionQueueMutation
+ ): Promise => {
+ try {
+ const protocolCapabilities = await deps.getMachineProtocolCapabilities(machineId);
+ if (!machineSupportsQueueItemSteerProtocol({ protocolCapabilities })) {
+ throw new Error('This daemon does not support queue ownership controls.');
+ }
+ if (await canUseLocalMachineRpc(machineId)) {
+ const response = await getLocalMachineRpcSender()?.({
+ machineId,
+ workspaceId,
+ method: 'session/queue-mutate',
+ params: args,
+ timeoutMs: 5_000,
+ });
+ if (!response) throw new Error('Local queue control is unavailable.');
+ if (!response.ok) throw new Error(response.error);
+ return response.result as SessionQueueMutationResponse;
+ }
+ if (!deps.getAuthorizedMachineIds?.()?.has(machineId)) {
+ throw new Error('Source authorization for this machine is unavailable or denied.');
+ }
+ return await (await getMachineRpcClient(machineId)).requestSessionQueueMutation(args);
+ } catch (error) {
+ return {
+ type: 'session/queue-mutate_response',
+ success: false,
+ error: error instanceof Error ? error.message : String(error),
+ };
+ }
+ };
+
const requestSessionQueueSteer = async (
machineId: MachineId,
args: {
@@ -810,6 +845,7 @@ export function createWorkspaceMachineRpcFacade(deps: WorkspaceMachineRpcFacadeD
};
}
if (response?.ok) return response.result as SessionQueueSteerResponse;
+ throw new Error('Local queue control is unavailable.');
}
const authorizedMachineIds = deps.getAuthorizedMachineIds?.() ?? null;
if (!authorizedMachineIds?.has(machineId)) {
@@ -1247,6 +1283,7 @@ export function createWorkspaceMachineRpcFacade(deps: WorkspaceMachineRpcFacadeD
return {
requestSessionCancel,
+ requestSessionQueueMutation,
requestSessionQueueSteer,
requestSessionSteer,
requestSessionGoal,
diff --git a/packages/components/src/providers/workspace-writer-impl.ts b/packages/components/src/providers/workspace-writer-impl.ts
index 88bec2a1d..5f50f2980 100644
--- a/packages/components/src/providers/workspace-writer-impl.ts
+++ b/packages/components/src/providers/workspace-writer-impl.ts
@@ -2,6 +2,8 @@ import {
applyPreviewVisualCommentMutation,
getServerNow,
getSessionRoomId,
+ queueItemRevision,
+ type SessionQueueMutation,
type MessageQueueItem,
type PreviewVisualCommentDocInput,
} from '@lody/shared';
@@ -16,24 +18,21 @@ import type { WorkspaceWriter } from './workspace-writer';
// # WorkspaceWriter implementation
//
-// Dual-author: every client authors the mutation against its own repo / session
-// stores (identical for Web, Mobile, and Electron; see `workspace-writer.ts`).
-// A pure factory with injected deps so hooks stay agnostic to the runtime.
+// Renderer authorship with a narrow daemon-owned queue-control exception.
+// Injected deps keep transport and capability policy out of hooks.
/** Deps the writer needs from the runtime (repo + session stores). */
export type DirectWorkspaceWriterDeps = {
repo: LoroRepo;
+ /** False means a confirmed legacy target; rejection never permits a direct write. */
+ mutateQueue?: (request: SessionQueueMutation) => Promise;
acquireSessionStore: (sessionId: SessionId) => Promise;
releaseSessionStoreRef: (sessionId: SessionId) => void;
acquirePreviewVisualCommentStore: (sessionId: SessionId) => Promise;
releasePreviewVisualCommentStoreRef: (sessionId: SessionId) => void;
};
-/**
- * Direct-mode writer (web/cloud): applies each mutation to the renderer's own
- * repo / session stores. This is exactly what the hooks did before the seam, so
- * there is zero behavior change in cloud mode.
- */
+/** Ordinary writes stay local; supported queue controls await authoritative daemon acceptance. */
export function createDirectWorkspaceWriter(deps: DirectWorkspaceWriterDeps): WorkspaceWriter {
const withSessionStore = async (
sessionId: string,
@@ -182,17 +181,47 @@ export function createDirectWorkspaceWriter(deps: DirectWorkspaceWriterDeps): Wo
},
async removeSessionMessage(sessionId, itemId) {
- await withSessionStore(sessionId, (store) => {
+ const remote = await withSessionStore(sessionId, async (store) => {
+ const row = store.getState().mq?.find((item) => item.$cid === itemId);
+ if (!row) throw new Error('This message is no longer in the editable queue.');
+ if (
+ await deps.mutateQueue?.({
+ sessionId: sessionId as SessionId,
+ mutation: {
+ kind: 'remove',
+ queueItemId: itemId,
+ expectedRevision: queueItemRevision(row),
+ },
+ })
+ )
+ return true;
store.setState((draft: SessionDocDraft) => {
const mq = (draft.mq ?? []) as MessageQueueItem[];
draft.mq = mq.filter((item) => item.$cid !== itemId);
});
});
- await bumpMessageQueueWatermark(sessionId);
+ if (!remote) await bumpMessageQueueWatermark(sessionId);
},
- async updateSessionMessage(sessionId, itemId, patch) {
- await withSessionStore(sessionId, (store) => {
+ async updateSessionMessage(sessionId, itemId, patch, expectedRevision) {
+ const remote = await withSessionStore(sessionId, async (store) => {
+ const row = store.getState().mq?.find((item) => item.$cid === itemId);
+ if (!row)
+ throw new Error(
+ 'This message is no longer in the editable queue. Your draft was not saved.'
+ );
+ if (
+ await deps.mutateQueue?.({
+ sessionId: sessionId as SessionId,
+ mutation: {
+ kind: 'update',
+ queueItemId: itemId,
+ expectedRevision: expectedRevision ?? queueItemRevision(row),
+ patch,
+ },
+ })
+ )
+ return true;
store.setState((draft: SessionDocDraft) => {
const mq = (draft.mq ?? []) as MessageQueueItem[];
draft.mq = mq.map((item) =>
@@ -202,11 +231,21 @@ export function createDirectWorkspaceWriter(deps: DirectWorkspaceWriterDeps): Wo
);
});
});
- await bumpMessageQueueWatermark(sessionId);
+ if (!remote) await bumpMessageQueueWatermark(sessionId);
},
- async reorderSessionMessages(sessionId, orderedItemIds) {
- await withSessionStore(sessionId, (store) => {
+ async reorderSessionMessages(sessionId, orderedItemIds, expectedIds) {
+ const remote = await withSessionStore(sessionId, async (store) => {
+ const expectedItemIds = expectedIds
+ ? [...expectedIds]
+ : (store.getState().mq ?? []).map((item) => item.$cid!);
+ if (
+ await deps.mutateQueue?.({
+ sessionId: sessionId as SessionId,
+ mutation: { kind: 'reorder', orderedItemIds: [...orderedItemIds], expectedItemIds },
+ })
+ )
+ return true;
store.setState((draft: SessionDocDraft) => {
const mq = (draft.mq ?? []) as MessageQueueItem[];
const byCid = new Map(mq.map((item) => [item.$cid, item] as const));
@@ -226,7 +265,7 @@ export function createDirectWorkspaceWriter(deps: DirectWorkspaceWriterDeps): Wo
draft.mq = ordered;
});
});
- await bumpMessageQueueWatermark(sessionId);
+ if (!remote) await bumpMessageQueueWatermark(sessionId);
},
async mutatePreviewVisualComments(sessionId, mutation) {
diff --git a/packages/components/src/providers/workspace-writer.ts b/packages/components/src/providers/workspace-writer.ts
index 029433be0..4bf78c43b 100644
--- a/packages/components/src/providers/workspace-writer.ts
+++ b/packages/components/src/providers/workspace-writer.ts
@@ -15,6 +15,8 @@ import type {
// uploads them over its own cloud connection; for local targets the local data
// plane converges the same ops with the CLI. The seam stays so hooks depend on
// one narrow mutation surface rather than raw repo/store handles.
+// Queue edit/remove/reorder on queueItemSteer v2 instead require the daemon's
+// revision-checked domain operation; failures never authorize a local fallback.
export interface WorkspaceWriter {
/** `repo.upsertDocMeta(roomId, patch)` — session/machine doc-meta write. */
upsertDocMeta(roomId: string, patch: Record): Promise;
@@ -116,9 +118,14 @@ export interface WorkspaceWriter {
updateSessionMessage(
sessionId: string,
itemId: string,
- patch: Record
+ patch: Record,
+ expectedRevision?: string
+ ): Promise;
+ reorderSessionMessages(
+ sessionId: string,
+ orderedItemIds: readonly string[],
+ expectedItemIds?: readonly string[]
): Promise;
- reorderSessionMessages(sessionId: string, orderedItemIds: readonly string[]): Promise;
/** Mutate the dedicated preview-comment doc (renderer-authored user data). */
mutatePreviewVisualComments(
diff --git a/packages/components/tests/message-queue-row-editing.test.tsx b/packages/components/tests/message-queue-row-editing.test.tsx
index d9d19d2c8..acf4e0fc0 100644
--- a/packages/components/tests/message-queue-row-editing.test.tsx
+++ b/packages/components/tests/message-queue-row-editing.test.tsx
@@ -133,6 +133,56 @@ describe('queued message editing commits', () => {
expect(saved).toEqual([{ cid: 'cid-0', task: 'Rewrite the queue instead' }]);
});
+ it('retains an unsaved draft when another client reserves the last queue row', async () => {
+ const item = makeItem();
+ const render = async (items: MessageQueueItem[]) => {
+ await act(async () => {
+ root?.render(
+ createElement(MessageQueueDisplay, {
+ sessionId: 'session-test' as SessionId,
+ items,
+ onRemove: () => {},
+ onReorder: () => {},
+ onSteer: () => {},
+ onEditStart: () => {},
+ onEditCancel: () => {},
+ onEditSave: async () => {
+ throw new Error('Message is operation-owned');
+ },
+ })
+ );
+ });
+ };
+ await render([item]);
+ const textarea = await startEditing(container!);
+ await act(async () => setTextareaValue(textarea, 'Roll back instead'));
+ await render([]);
+ expect(container?.querySelector('textarea')?.value).toBe('Roll back instead');
+ expect(container?.querySelector('[role="alert"]')?.textContent).toContain('unsaved draft');
+ await pressEnter(container!.querySelector('textarea')!);
+ expect(container?.querySelector('textarea')?.value).toBe('Roll back instead');
+ });
+
+ it('does not reopen an old editing lease when the save ACK arrives before replication', async () => {
+ const item = { ...makeItem(), isEditing: true, editingStartedAt: 1 };
+ await act(async () => {
+ root?.render(
+ createElement(MessageQueueDisplay, {
+ sessionId: 'session-test' as SessionId,
+ items: [item],
+ onRemove: () => {},
+ onReorder: () => {},
+ onSteer: () => {},
+ onEditStart: () => {},
+ onEditCancel: () => {},
+ onEditSave: () => {},
+ })
+ );
+ });
+ await pressEnter(container!.querySelector('textarea')!);
+ expect(container?.querySelector('textarea')).toBeNull();
+ });
+
it('focuses the editor when the editing flag arrives before the start write completes', async () => {
let finishStart!: () => void;
function QueueWithEarlyUpdate() {
diff --git a/packages/components/tests/queued-message-steer.test.ts b/packages/components/tests/queued-message-steer.test.ts
deleted file mode 100644
index 48ededdae..000000000
--- a/packages/components/tests/queued-message-steer.test.ts
+++ /dev/null
@@ -1,49 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
- resolveQueuedMessageSteerRoute,
- shouldUseLegacyNativeQueueSteer,
-} from '../src/components/sessions/message-queue';
-
-describe('legacy queued-message steering', () => {
- it('uses true native steering only for an authoritative acknowledged capability', () => {
- expect(shouldUseLegacyNativeQueueSteer('authoritative', { acknowledgedSteer: true })).toBe(
- true
- );
- expect(shouldUseLegacyNativeQueueSteer('authoritative', { acknowledgedSteer: false })).toBe(
- false
- );
- expect(shouldUseLegacyNativeQueueSteer('provisional', { acknowledgedSteer: true })).toBe(false);
- expect(shouldUseLegacyNativeQueueSteer('unavailable', undefined)).toBe(false);
- });
-
- it('routes new renderers across new and old daemon capability combinations', () => {
- expect(
- resolveQueuedMessageSteerRoute({
- supportsExactDaemonProtocol: true,
- authority: 'authoritative',
- capability: { acknowledgedSteer: true },
- })
- ).toBe('exact-daemon');
- expect(
- resolveQueuedMessageSteerRoute({
- supportsExactDaemonProtocol: false,
- authority: 'authoritative',
- capability: { acknowledgedSteer: true },
- })
- ).toBe('legacy-native');
- expect(
- resolveQueuedMessageSteerRoute({
- supportsExactDaemonProtocol: false,
- authority: 'authoritative',
- capability: { acknowledgedSteer: false },
- })
- ).toBe('legacy-head');
- expect(
- resolveQueuedMessageSteerRoute({
- supportsExactDaemonProtocol: false,
- authority: 'provisional',
- capability: { acknowledgedSteer: true },
- })
- ).toBe('legacy-head');
- });
-});
diff --git a/packages/components/tests/workspace-machine-rpc-facade.test.ts b/packages/components/tests/workspace-machine-rpc-facade.test.ts
index c4c459eb4..7af58e6ca 100644
--- a/packages/components/tests/workspace-machine-rpc-facade.test.ts
+++ b/packages/components/tests/workspace-machine-rpc-facade.test.ts
@@ -17,6 +17,64 @@ afterEach(() => {
});
describe('createWorkspaceMachineRpcFacade', () => {
+ it.each([undefined, { queueItemSteer: 1 }])(
+ 'disables every old-daemon queue row for %j',
+ async (capabilities) => {
+ const facade = createWorkspaceMachineRpcFacade({
+ workspaceId,
+ getMachineProtocolCapabilities: async () => capabilities,
+ targetRouter: {
+ getPlaneForMachine: () => 'remote',
+ resolvePlaneForMachine: async () => 'remote',
+ },
+ getMachineRpcClient: async () => {
+ throw new Error('Legacy delivery must not run');
+ },
+ });
+ for (const queueItemId of ['A', 'B', 'C']) {
+ await expect(
+ facade.requestSessionQueueSteer(remoteMachineId, {
+ sessionId,
+ expectedTurnId: 'active',
+ queueItemId,
+ })
+ ).resolves.toMatchObject({ accepted: false, disposition: 'unsupported', queueItemId });
+ }
+ }
+ );
+
+ it('returns a queue mutation failure from local IPC without trying remote delivery', async () => {
+ vi.stubGlobal('window', {
+ __LODY_ELECTRON__: true,
+ ipc: {
+ invoke: async () => ({
+ ok: true,
+ result: {
+ type: 'session/queue-mutate_response',
+ success: false,
+ error: 'Row is reserved',
+ },
+ }),
+ },
+ });
+ const facade = createWorkspaceMachineRpcFacade({
+ workspaceId,
+ getMachineProtocolCapabilities: async () => CURRENT_MACHINE_PROTOCOL_CAPABILITIES,
+ targetRouter: {
+ getPlaneForMachine: () => 'local',
+ resolvePlaneForMachine: async () => 'local',
+ },
+ getMachineRpcClient: async () => {
+ throw new Error('Must not use remote');
+ },
+ });
+ await expect(
+ facade.requestSessionQueueMutation(localMachineId, {
+ sessionId,
+ mutation: { kind: 'remove', queueItemId: 'C', expectedRevision: '{}' },
+ })
+ ).resolves.toMatchObject({ success: false, error: 'Row is reserved' });
+ });
it('sends queued Steer as one exact local daemon operation', async () => {
const invoke = vi.fn(async () => ({
ok: true as const,
diff --git a/packages/components/tests/workspace-writer.test.ts b/packages/components/tests/workspace-writer.test.ts
index f8f360283..33f673815 100644
--- a/packages/components/tests/workspace-writer.test.ts
+++ b/packages/components/tests/workspace-writer.test.ts
@@ -46,6 +46,43 @@ const anchor: MinimalVisualAnnotationAnchor = {
};
describe('createDirectWorkspaceWriter', () => {
+ it.each(['update', 'remove', 'reorder'] as const)(
+ 'does not direct-write after daemon rejects queue %s',
+ async (kind) => {
+ const row = { $cid: 'C', task: 'Repair database' };
+ const state = { mq: [row] };
+ let references = 0;
+ const writer = createDirectWorkspaceWriter({
+ repo: { upsertDocMeta: async () => {} } as never,
+ acquireSessionStore: async () => {
+ references++;
+ return {
+ getState: () => state,
+ setState: (update: (draft: typeof state) => void) => update(state),
+ } as never;
+ },
+ releaseSessionStoreRef: () => {
+ references--;
+ },
+ acquirePreviewVisualCommentStore: async () => {
+ throw new Error('unused');
+ },
+ releasePreviewVisualCommentStoreRef: () => {},
+ mutateQueue: async () => {
+ throw new Error('Queue item is reserved');
+ },
+ });
+ const request =
+ kind === 'update'
+ ? writer.updateSessionMessage('session', 'C', { task: 'Rollback' })
+ : kind === 'remove'
+ ? writer.removeSessionMessage('session', 'C')
+ : writer.reorderSessionMessages('session', ['C']);
+ await expect(request).rejects.toThrow('reserved');
+ expect(state).toEqual({ mq: [{ $cid: 'C', task: 'Repair database' }] });
+ expect(references).toBe(0);
+ }
+ );
it.each(['unchanged', 'edited', 'deleted', 'cancelled', 'other-owner', 'write-failure'] as const)(
'reconciles the durable role without overwriting intervening changes: %s',
async (scenario) => {
diff --git a/packages/loro-streams-rpc/AGENTS.md b/packages/loro-streams-rpc/AGENTS.md
index 83114c45d..910dc680a 100644
--- a/packages/loro-streams-rpc/AGENTS.md
+++ b/packages/loro-streams-rpc/AGENTS.md
@@ -46,7 +46,7 @@ and the `file/preview` namespace are in
needs read-check-write atomicity serializes in its own service layer (Code Collab
`save-text` per absolute path in `code-collab-v2-service.ts`), not in the request loop.
- Control-plane methods (`machine/status`, `machine/ping`, `session/cancel`,
- `session/live-status`, `session/queue-steer`, `session/steer`, `session/terminate`, `machine/restart`,
+ `session/live-status`, `session/queue-steer`, `session/queue-mutate`, `session/steer`, `session/terminate`, `machine/restart`,
`machine/upgrade`, `session/dispatch-turn`)
bypass the shared semaphore and run on a small dedicated lane
(`CONTROL_METHODS` in `machine-rpc-server.ts`) so saturated code-collab
diff --git a/packages/loro-streams-rpc/src/machine-rpc-server.ts b/packages/loro-streams-rpc/src/machine-rpc-server.ts
index 11d904b96..9e10e8e71 100644
--- a/packages/loro-streams-rpc/src/machine-rpc-server.ts
+++ b/packages/loro-streams-rpc/src/machine-rpc-server.ts
@@ -1,3 +1,4 @@
+import type { SessionQueueMutation, SessionQueueMutationResponse } from '@lody/shared';
import type {
AgentConfigId,
CodeCollabV2InitDirectoryOk,
@@ -119,6 +120,7 @@ const CONTROL_METHODS: ReadonlySet = new Set([
'machine/acp-capabilities-refresh-cancel',
'session/cancel',
'session/live-status',
+ 'session/queue-mutate',
'session/queue-steer',
'session/steer',
'session/goal',
@@ -352,6 +354,7 @@ type RpcServerDeps = {
getSessionLiveStatus?: (args: {
sessionId: SessionId;
}) => Promise;
+ mutateQueuedMessage?: (args: SessionQueueMutation) => Promise;
steerQueuedMessage?: (args: {
sessionId: SessionId;
expectedTurnId: string;
@@ -1114,6 +1117,17 @@ export class LoroStreamsMachineRpcServer {
await this.appendResultResponse(request.replyTo, request.id, request.method, response);
return;
}
+ case 'session/queue-mutate': {
+ const response: SessionQueueMutationResponse = this.deps.mutateQueuedMessage
+ ? await this.deps.mutateQueuedMessage(request.params)
+ : {
+ type: 'session/queue-mutate_response',
+ success: false,
+ error: 'Queue mutation is unavailable on this machine.',
+ };
+ await this.appendResultResponse(request.replyTo, request.id, request.method, response);
+ return;
+ }
case 'session/queue-steer': {
if (!this.deps.steerQueuedMessage) {
await this.appendErrorResponse(request.replyTo, request.id, request.method, {
@@ -1638,6 +1652,7 @@ export class LoroStreamsMachineRpcServer {
| MachineBugReportResponse
| SessionCancelResponse
| LoroSessionLiveStatusRpcResponse
+ | SessionQueueMutationResponse
| SessionQueueSteerResponse
| SessionSteerResponse
| SessionGoalResponse
diff --git a/packages/loro-streams-rpc/src/rpc.ts b/packages/loro-streams-rpc/src/rpc.ts
index 6e44f05a0..5b0fc8aef 100644
--- a/packages/loro-streams-rpc/src/rpc.ts
+++ b/packages/loro-streams-rpc/src/rpc.ts
@@ -1,3 +1,9 @@
+import {
+ SessionQueueMutationSchema,
+ SessionQueueMutationResponseSchema,
+ type SessionQueueMutation,
+ type SessionQueueMutationResponse,
+} from '@lody/shared';
import { z } from 'zod';
import {
StreamsClient,
@@ -194,6 +200,7 @@ export const LoroStreamsRpcMethodSchema = z.enum([
'file/preview',
'session/cancel',
'session/live-status',
+ 'session/queue-mutate',
'session/queue-steer',
'session/steer',
'session/goal',
@@ -475,6 +482,11 @@ export const LoroSessionSteerRpcRequestSchema = BaseRpcRequestSchema.extend({
.strict(),
}).strict();
+export const LoroSessionQueueMutationRpcRequestSchema = BaseRpcRequestSchema.extend({
+ method: z.literal('session/queue-mutate'),
+ params: SessionQueueMutationSchema,
+}).strict();
+
export const LoroSessionQueueSteerRpcRequestSchema = BaseRpcRequestSchema.extend({
method: z.literal('session/queue-steer'),
params: z
@@ -613,6 +625,7 @@ export const LoroStreamsRpcRequestSchema = z.discriminatedUnion('method', [
LoroFilePreviewRpcRequestSchema,
LoroSessionCancelRpcRequestSchema,
LoroSessionLiveStatusRpcRequestSchema,
+ LoroSessionQueueMutationRpcRequestSchema,
LoroSessionQueueSteerRpcRequestSchema,
LoroSessionSteerRpcRequestSchema,
LoroSessionGoalRpcRequestSchema,
@@ -1457,6 +1470,7 @@ export type LoroMachineRpcResult =
| MachineBugReportResponse
| SessionCancelResponse
| LoroSessionLiveStatusRpcResponse
+ | SessionQueueMutationResponse
| SessionQueueSteerResponse
| SessionSteerResponse
| SessionGoalResponse
@@ -1663,6 +1677,9 @@ const toLegacyRpcErrorResponse = (
};
}
+ if (method === 'session/queue-mutate') {
+ return { type: 'session/queue-mutate_response', success: false, error: error.message };
+ }
if (method === 'session/queue-steer') {
return {
type: 'session/queue-steer_response',
@@ -1848,6 +1865,10 @@ const parseRpcSuccessResult = async (
const parsed = SessionSteerResponseSchema.safeParse(response.result);
return parsed.success ? (parsed.data as SessionSteerResponse) : null;
}
+ if (response.method === 'session/queue-mutate') {
+ const parsed = SessionQueueMutationResponseSchema.safeParse(response.result);
+ return parsed.success ? parsed.data : null;
+ }
if (response.method === 'session/queue-steer') {
const parsed = SessionQueueSteerResponseSchema.safeParse(response.result);
return parsed.success ? (parsed.data as SessionQueueSteerResponse) : null;
@@ -2727,6 +2748,16 @@ export class LoroStreamsMachineRpcClient {
})) as SessionSteerResponse | null;
}
+ async requestSessionQueueMutation(
+ options: SessionQueueMutation & { timeoutMs?: number }
+ ): Promise {
+ return (await this.sendRequest({
+ method: 'session/queue-mutate',
+ timeoutMs: options.timeoutMs ?? 5000,
+ params: { sessionId: options.sessionId, mutation: options.mutation },
+ })) as SessionQueueMutationResponse | null;
+ }
+
async requestSessionQueueSteer(options: {
sessionId: SessionId;
expectedTurnId: string;
@@ -3221,6 +3252,11 @@ export class LoroStreamsMachineRpcClient {
sessionId: string;
};
}
+ | {
+ method: 'session/queue-mutate';
+ timeoutMs: number;
+ params: SessionQueueMutation;
+ }
| {
method: 'session/queue-steer';
timeoutMs: number;
@@ -3577,6 +3613,9 @@ export class LoroStreamsMachineRpcClient {
case 'session/live-status':
request = { ...envelope, method: args.method, params: args.params };
break;
+ case 'session/queue-mutate':
+ request = { ...envelope, method: args.method, params: args.params };
+ break;
case 'session/queue-steer':
request = { ...envelope, method: args.method, params: args.params };
break;
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 5840015a4..b16356f28 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -474,3 +474,4 @@ export interface Attachment {
uploadedAt: Date;
uploadedBy: User;
}
+export * from './session-queue-mutation';
diff --git a/packages/shared/src/local-machine-rpc.ts b/packages/shared/src/local-machine-rpc.ts
index 8b2c232df..b5b3a2580 100644
--- a/packages/shared/src/local-machine-rpc.ts
+++ b/packages/shared/src/local-machine-rpc.ts
@@ -1,3 +1,7 @@
+import {
+ SessionQueueMutationSchema,
+ SessionQueueMutationResponseSchema,
+} from './session-queue-mutation';
import { LocalFileResolutionSchema } from './local-file-preview';
import { z } from 'zod';
import { SESSION_GOAL_ACTIONS } from './goal';
@@ -194,6 +198,10 @@ export const LocalMachineRpcRequestSchema = z.discriminatedUnion('method', [
method: z.literal('session/prepare-cancel'),
params: SessionPreparationCancelSpecSchema,
}).strict(),
+ BaseLocalMachineRpcRequestSchema.extend({
+ method: z.literal('session/queue-mutate'),
+ params: SessionQueueMutationSchema,
+ }).strict(),
BaseLocalMachineRpcRequestSchema.extend({
method: z.literal('session/queue-steer'),
params: z
@@ -261,6 +269,7 @@ export type LocalMachineRpcRequest = z.infer;
+export type SessionQueueMutationResponse = z.infer;
+
+/** Canonical JSON identity for compare-and-update across independent replicas. */
+export function queueItemRevision(value: unknown): string {
+ return JSON.stringify(value, (_key, item: unknown) => {
+ if (item && typeof item === 'object' && !Array.isArray(item)) {
+ return Object.fromEntries(
+ Object.entries(item).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+ );
+ }
+ return item;
+ });
+}
diff --git a/packages/shared/tests/local-machine-rpc.test.ts b/packages/shared/tests/local-machine-rpc.test.ts
index 5333191b7..67b398b5a 100644
--- a/packages/shared/tests/local-machine-rpc.test.ts
+++ b/packages/shared/tests/local-machine-rpc.test.ts
@@ -6,6 +6,32 @@ import {
describe('local Machine RPC', () => {
it.each([
+ {
+ method: 'session/queue-mutate',
+ params: {
+ sessionId: 'session-1',
+ mutation: {
+ kind: 'update',
+ queueItemId: 'queue-C',
+ expectedRevision: '{}',
+ patch: { task: 'rollback' },
+ },
+ },
+ },
+ {
+ method: 'session/queue-mutate',
+ params: {
+ sessionId: 'session-1',
+ mutation: { kind: 'remove', queueItemId: 'queue-C', expectedRevision: '{}' },
+ },
+ },
+ {
+ method: 'session/queue-mutate',
+ params: {
+ sessionId: 'session-1',
+ mutation: { kind: 'reorder', expectedItemIds: ['A', 'B'], orderedItemIds: ['B', 'A'] },
+ },
+ },
{
method: 'session/get-active-invocation-context',
params: { sessionId: 'session-1' },
diff --git a/packages/shared/tests/machine-protocol-capabilities.test.ts b/packages/shared/tests/machine-protocol-capabilities.test.ts
index b6235ab4c..8684699f7 100644
--- a/packages/shared/tests/machine-protocol-capabilities.test.ts
+++ b/packages/shared/tests/machine-protocol-capabilities.test.ts
@@ -50,6 +50,9 @@ it('requires an advertised local file resource protocol, independent of release
it('requires an advertised exact queue-item steer protocol', () => {
expect(machineSupportsQueueItemSteerProtocol(undefined)).toBe(false);
+ expect(
+ machineSupportsQueueItemSteerProtocol({ protocolCapabilities: { queueItemSteer: 1 } })
+ ).toBe(false);
expect(
machineSupportsQueueItemSteerProtocol({
protocolCapabilities: { [MACHINE_PROTOCOL_CAPABILITIES.queueItemSteer]: 0 },
diff --git a/specs/message-queue-interactions.md b/specs/message-queue-interactions.md
index e42a58612..7d61c9d76 100644
--- a/specs/message-queue-interactions.md
+++ b/specs/message-queue-interactions.md
@@ -65,6 +65,12 @@ the queue by hand.
A rejected edit retains the user's draft. Neither optimistic UI success nor a client-local
editing lease proves that an edit was accepted by that authority.
+ `queueItemSteer` v2 binds this guarantee to `session/queue-mutate`: renderer edit/remove
+ carry the observed row revision, and reorder carries the observed ID sequence. The owning
+ daemon compares them under the reservation boundary and persists accepted changes before
+ replying. A failed RPC never falls back to a direct CRDT write. Enqueue and ordinary sends
+ retain their renderer authorship; this is not a generic write-intent protocol.
+
The native submission order is:
1. Validate the selected identity, content, editing ownership, and expected turn; establish
exclusive reservation ownership against concurrent ordinary queue mutations.
@@ -129,14 +135,11 @@ reported, never silently replayed.
## Implementation evidence
-The service/port split, reservation ownership transfer, pre-submission durable queue removal,
-and capability-only availability above are intended changes, not completed implementation.
-The current native path retains the editable row through provider handoff; ordinary row updates
-do not enforce operation ownership, and missing-row updates can silently succeed. This permits
-an accepted edit to disappear when handoff removes the row. The renderer also still contains
-old-daemon native/head paths and the execution service owns queue orchestration. Implementation
-and two-client mutation/crash regression verification remain
-pending under the [Effect boundary proposal](../.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.md).
+The [Effect boundary decision](../.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.md)
+records the implemented service/port split, v2 mutation authority, durable pre-submission removal,
+capability-only availability, and verification limits. Deterministic tests cover reservation versus
+second-client mutations, displaced drafts, persistence failures and marker-based recovery.
+Real provider, installed-app and process-kill end-to-end verification remain outstanding.
The new availability policy applies to queued-row Steer, not composer submission routing.
- `packages/components/src/components/sessions/session-message-submit-route.ts`
@@ -144,6 +147,7 @@ The new availability policy applies to queued-row Steer, not composer submission
- `packages/components/src/components/sessions/message-queue/`
- `packages/components/tests/{session-message-submit-route,session-chat-input-submission,message-queue-row-editing}.test.*`
- `apps/cli/{tests/session-execution-service.test.ts,src/lib/loro/doc-user-turn.test.ts,src/session/session-queue-steer-operation-store.ts}`
+- `apps/cli/src/session/{queue-steer-service,active-turn-steer-port}.ts`
- [Decision record](../.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.md)
This is a draft for human review. Implementation and passing tests do not approve it.
diff --git a/specs/message-queue-interactions.zh.md b/specs/message-queue-interactions.zh.md
index 904403dd2..1a2db8870 100644
--- a/specs/message-queue-interactions.zh.md
+++ b/specs/message-queue-interactions.zh.md
@@ -55,6 +55,11 @@ Translation: current
后续修改须明确拒绝。被拒绝的编辑保留用户草稿。乐观 UI 成功或客户端本地 editing lease
都不证明权威写入端已接受编辑。
+ `queueItemSteer` v2 通过 `session/queue-mutate` 建立该保证：renderer edit/remove
+ 携带观察到的 row revision，reorder 携带观察到的 ID 顺序。所属 daemon 在 reservation
+ 边界内比较，并在已接受修改持久化后回复。RPC 失败绝不退回直接写 CRDT。
+ enqueue 和普通发送仍由 renderer 写入；这不是通用 write-intent 协议。
+
Native 提交顺序为：
1. 验证目标标识、内容、编辑归属和 expected turn，并针对并发普通队列修改取得排他 reservation
ownership。
@@ -110,19 +115,18 @@ Translation: current
## 实现证据
-上述 service/port 拆分、reservation ownership 转移、提交前持久化删除队列项及仅按
-capability 开放能力均是待实现的意图变更。当前 native 路径仍保留可编辑 row 直到 provider
-handoff；普通 row 更新没有 operation ownership 检查，更新缺失 row 也可能静默成功。
-因此已接受的编辑可能在 handoff 删除 row 时丢失。renderer 也仍包含旧 daemon 的
-native/head 路径，execution service 仍拥有队列编排。实现及双客户端修改/崩溃回归验证
-待按 [Effect 边界提案](../.agents/notes/proposed/architecture/2026-09-14-queue-steer-effect-boundary.zh.md)
-完成。新的可用性策略只适用于队列行“引导”，不改变 composer 提交路由。
+[Effect 边界决策](../.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.zh.md)
+记录已实现的 service/port 拆分、v2 修改权威、提交前持久化删除、仅按 capability 开放能力及验证限制。
+确定性测试覆盖 reservation 与第二客户端修改、草稿保留、持久化失败和 marker 恢复。
+真实 provider、已安装应用及进程 kill 的端到端验证尚未完成。
+新的可用性策略只适用于队列行“引导”，不改变 composer 提交路由。
- `packages/components/src/components/sessions/session-message-submit-route.ts`
- `packages/components/src/components/sessions/session-chat-input-area.tsx`
- `packages/components/src/components/sessions/message-queue/`
- `packages/components/tests/{session-message-submit-route,session-chat-input-submission,message-queue-row-editing}.test.*`
- `apps/cli/{tests/session-execution-service.test.ts,src/lib/loro/doc-user-turn.test.ts,src/session/session-queue-steer-operation-store.ts}`
+- `apps/cli/src/session/{queue-steer-service,active-turn-steer-port}.ts`
- [决策记录](../.agents/notes/implemented/feature/2026-09-13-queue-steer-controls.zh.md)
这是供人工审阅的草稿；实现和测试通过不代表 Spec 已获批准。
From 446cd45c62172199d4a7c460a07039aeae99cf2a Mon Sep 17 00:00:00 2001
From: wibus-wee <62133302+wibus-wee@users.noreply.github.com>
Date: Mon, 14 Sep 2026 17:42:44 +0800
Subject: [PATCH 12/15] fix: secure queue session controls and pre-history
retries
Share source-side session authorization across queue controls, preserve routing planes on transport failure, and allow safe pre-history recovery retries.
Model: gpt-6
---
.agents/docs/rpc-loro-streams-rpc.md | 9 +-
.../2026-09-14-queue-steer-effect-boundary.md | 21 +-
...26-09-14-queue-steer-effect-boundary.zh.md | 20 +-
apps/cli/src/session/AGENTS.md | 6 +-
apps/cli/src/session/queue-steer-service.ts | 64 ++---
.../tests/session-execution-service.test.ts | 232 ++++++++++++++----
packages/components/src/providers/AGENTS.md | 3 +
.../src/providers/create-workspace-runtime.ts | 8 +-
.../src/providers/runtime-provider.tsx | 37 ++-
.../session-control-authorization.ts | 30 +++
.../providers/workspace-machine-rpc-facade.ts | 37 ++-
.../workspace-machine-rpc-facade.test.ts | 83 ++++++-
specs/message-queue-interactions.md | 21 +-
specs/message-queue-interactions.zh.md | 17 +-
14 files changed, 472 insertions(+), 116 deletions(-)
create mode 100644 packages/components/src/providers/session-control-authorization.ts
diff --git a/.agents/docs/rpc-loro-streams-rpc.md b/.agents/docs/rpc-loro-streams-rpc.md
index fb2625695..14564aa05 100644
--- a/.agents/docs/rpc-loro-streams-rpc.md
+++ b/.agents/docs/rpc-loro-streams-rpc.md
@@ -30,8 +30,13 @@ editing lease is inactive, then preserves native ACP Steer when acknowledged or
ordinary follow-up before cancelling the expected turn. The ordinary path retains the queue
row until history and its activation pointer are durable. Missing, editing, and stale targets
do neither.
-Before a remote renderer writes this control request, it fails closed against its authenticated
-`machines:listVisibleMachines` snapshot. The retained request contains no requester identity:
+Before either remote queue control is written, the shared
+[source authorizer](../../packages/components/src/providers/session-control-authorization.ts)
+matches session metadata to the target machine and applies the existing session visibility
+policy to authenticated machine/project snapshots and current user. Incomplete snapshots fail
+closed; shared machine access does not expose another user's private project. Local routing
+with an unavailable sender fails locally without creating a Streams client.
+The retained request contains no requester identity:
the target daemon cannot authenticate such a claim and must not grant its owner fast path from it.
Native queue Steer instead inherits the frozen requester from the authenticated active invocation;
it fails before consumption when that identity is unavailable and never trusts the queue row.
diff --git a/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.md b/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.md
index 581a71e53..75766889e 100644
--- a/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.md
+++ b/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.md
@@ -51,9 +51,17 @@ were read as supplementary evidence, not run or assumed identical to the pinned
The queue service never reads runtime maps, agentClient, promptInFlight, invocation or successor,
and receives no onSubmitting/onAcknowledged/onApplied/onUndelivered callbacks.
+It defines its own narrow dependency contract, without importing SessionExecutionServiceDeps.
Provider requester identity comes from the active invocation, not the shared queue author.
Ordinary turn and composer routing remain unchanged.
+The source facade shares [session authorization](../../../../packages/components/src/providers/session-control-authorization.ts)
+between queue Steer and mutation, using the existing session visibility predicate and complete
+authenticated machine/project snapshots. A machine-only check would expose private-project
+sessions. RuntimeProvider supplies a workspace-fenced snapshot; missing metadata or authorization
+fails closed. Routing plane is decided independently of sender availability: local failure cannot
+fall through to Streams. The target daemon cannot authenticate a caller identity from this RPC.
+
## Resources and failures
Rewrite/ownership guards and the adapter's local ACK gate belong to Scope through
@@ -86,7 +94,11 @@ Recovery uses marker and frozen history, without requiring a surviving row. Exis
remain readable. A legacy row without a revision may be removed only when its frozen content
is provably unchanged and it is not being edited; otherwise preserve it for reconciliation.
-Reserved/fallback recover the same ordinary turn; submitting/acknowledged never replay;
+Reserved without history clears its marker and leaves the queue untouched, with no terminal
+receipt. Same C/T retries revalidate and reserve anew, either after startup recovery or within
+the current request; a failed clear prevents proceeding. A cached error here would incorrectly
+make a proven-unsubmitted operation permanently unsteerable for the remaining active turn.
+Reserved with history/fallback recover the same ordinary turn; submitting/acknowledged never replay;
applied recovers an accepted receipt. Ordinary cancel-and-dispatch retains its history/activation
publication order and in-memory receipts. The [Spec](../../../../specs/message-queue-interactions.md)
owns the full contract and remains draft. This supersedes the
@@ -106,6 +118,13 @@ reservation/history/removal/submission-marker persistence failure, marker-plus-h
and local guard release. Components verify displaced-draft retention; shared negotiation rejects v1.
No race assertion depends on sleeps or real network scheduling.
+The execution suite connects the real source facade, Streams client/server, LoroDoc and execution
+service over an in-memory transport. A visible machine with a denied private project rejects
+both controls with zero appends, no marker, and unchanged queue/history/active turn. Local routing
+with no sender also rejects without constructing the remote client. A positive project-access
+control reaches the daemon and applies C. Restart and in-request pre-history recovery both allow
+the same C/T to proceed. These are deterministic synthetic traces, not production-user traces.
+
Direct CLI/components typechecks and targeted tests were run. Root pnpm check / pnpm format
cannot start because corepack is absent; installed pnpm runs targeted checks and Prettier instead.
No real-provider, full desktop end-to-end, process kill/restart, or arbitrary mixed-old-client
diff --git a/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.zh.md b/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
index b02559755..17952eb74 100644
--- a/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
@@ -49,7 +49,14 @@ CLI 规则引用的 `context/cli-effect-ts.md` 在当前 checkout 缺失。
Queue 服务不读取 runtime map、agentClient、promptInFlight、invocation 或 successor，
也不使用 onSubmitting/onAcknowledged/onApplied/onUndelivered 回调。Provider requester
-来自活动 invocation，不相信队列作者。既有普通 turn 与 composer 路由不变。
+来自活动 invocation，不相信队列作者。服务定义自己的窄依赖契约，不导入
+SessionExecutionServiceDeps。既有普通 turn 与 composer 路由不变。
+
+Source facade 为队列 Steer 和 mutation 共用 [session 授权](../../../../packages/components/src/providers/session-control-authorization.ts)，
+使用已有 session visibility 判断和完整的已认证 machine/project 快照。Machine-only 检查会暴露
+私有项目 session。RuntimeProvider 提供按 workspace 隔离的快照；metadata 或授权缺失时
+fail closed。Routing plane 独立于 sender 可用性，local 失败不能落入 Streams。
+目标 daemon 无法从此 RPC 认证调用方身份。
## 资源和失败
@@ -80,7 +87,10 @@ Native 顺序是 reservation marker → pending_apply history durable → queue
恢复使用 marker 和冻结 history；不要求原 row 存在。旧 marker 仍可读；若残留 row 无 revision，
只有可证明与冻结内容一致且不在编辑中才删除，否则保留并等待对账。不能通过恢复丢掉已接受编辑。
-`reserved`/`fallback` 可恢复同一个普通 turn；`submitting`/`acknowledged` 不重放；
+没有 history 的 `reserved` 清除 marker、保留 queue，不生成终态 receipt。相同 C/T 的重试
+重新验证并建立 reservation，既支持启动恢复后重试，也支持当前请求继续；clear 失败则不能继续。
+此处缓存错误会让确定未提交的操作在当前 active turn 剩余期间永久无法再次 Steer。
+有 history 的 `reserved`/`fallback` 可恢复同一个普通 turn；`submitting`/`acknowledged` 不重放；
`applied` 恢复 accepted 回执。普通 cancel-and-dispatch 保留既有 history/activation
发布顺序与内存回执。完整契约由 [Spec](../../../../specs/message-queue-interactions.zh.md) 拥有；
它仍是 draft。本决策替代[原记录](../feature/2026-09-13-queue-steer-controls.zh.md)的
@@ -97,6 +107,12 @@ receipt/restart，以及真实 LoroDoc 上的 reservation 与 edit/remove/reorde
持久化失败时零提交、marker 加 history 的恢复和本地 guard 释放。组件覆盖 row 消失后的草稿保留，
共享协议拒绝 v1。测试不使用睡眠或真实网络来决定竞态。
+Execution suite 用内存传输连接真实 source facade、Streams client/server、LoroDoc 和
+execution service。Machine 可见但私有项目不可见时，两种 control 均拒绝：零 append、无 marker，
+queue/history/active turn 不变。Local 缺 sender 同样拒绝且不创建远程 client。开放项目权限的
+正向对照可到达 daemon 并应用 C。重启恢复和请求内 pre-history 恢复都允许相同 C/T 继续。
+这些是确定性合成数据 trace，不是生产用户 trace。
+
直接 CLI、components 类型检查与目标测试已运行；根级 pnpm check / pnpm format
因缺少 corepack 无法启动，改用已安装 pnpm 运行目标检查和 Prettier。
没有真实 provider、完整桌面端到端、进程 kill/restart 或任意旧客户端混跑的验证。
diff --git a/apps/cli/src/session/AGENTS.md b/apps/cli/src/session/AGENTS.md
index c52767ca2..c0e2908c3 100644
--- a/apps/cli/src/session/AGENTS.md
+++ b/apps/cli/src/session/AGENTS.md
@@ -56,9 +56,9 @@ Contract: specs/session-orchestration.md.
tombstone; CLI dispatch producers keep their own marker policy.
- Ordinary turn execution writes only `processingUserMsgId` and `lastHandledUserMsgId`; no start
or terminal path may read-await-rewrite the other slots.
-- Never steer after Stop; late ACK is indeterminate. Reserve against queue mutations/promotion;
- persist marker, frozen history and removal BEFORE native submission. Scope owns local guards,
- not provider effects. Only proven non-delivery may requeue; unknown delivery never replays.
+- No Steer after Stop; late ACK never replays. Exclude queue mutations/promotion; persist
+ marker/history/removal before submission. Scope owns guards only. Requeue only proven
+ non-delivery. Reserved without history clears marker, not row: retryable, no receipt.
- Resume must REOPEN the in-progress assistant entry, clearing
`finished`/`endedAt`/`permissionWaitMs` there only; never write `finished=false` from teardown.
- Keep JSON-RPC/transport matching in `acp-error-classification.ts`: disposed/stale `-32603` is
diff --git a/apps/cli/src/session/queue-steer-service.ts b/apps/cli/src/session/queue-steer-service.ts
index c22c1c7c9..6b928c8ac 100644
--- a/apps/cli/src/session/queue-steer-service.ts
+++ b/apps/cli/src/session/queue-steer-service.ts
@@ -5,33 +5,45 @@ import {
queueItemRevision,
resolveSessionHistoryStatus,
type SessionId,
+ type WorkspaceId,
+ type MachineId,
+ type ChatFailedReason,
+ type ChatFailedCode,
type SessionQueueSteerResponse,
type SessionQueueMutation,
type SessionQueueMutationResponse,
} from '@lody/shared';
import { readSessionHistory } from '@lody/shared/session-data';
-import { hasActiveMessageQueueEditingLease, type SessionDocument } from '@/lib/loro/doc';
+import {
+ hasActiveMessageQueueEditingLease,
+ type SessionDocument,
+ type LoroDocumentManager,
+} from '@/lib/loro/doc';
+import type { Logger } from '@/utils/logger';
import { formatErrorMessage } from '@/utils/format-error';
import { ActiveTurnSteerPort, PersistenceFailure } from './active-turn-steer-port';
import { buildQueuedMessageUserTurn } from './queued-message-turn';
import {
isQueueSteerMarkerOwnedBy,
type QueueSteerOperationMarker,
+ type QueueSteerOperationStore,
} from './session-queue-steer-operation-store';
-import type { SessionExecutionServiceDeps } from './session-execution-service';
type Request = { sessionId: SessionId; expectedTurnId: string; queueItemId: string };
type Marker = QueueSteerOperationMarker;
-type Recovery = SessionQueueSteerResponse | 'deferred' | null;
-type Deps = Pick<
- SessionExecutionServiceDeps,
- | 'workspaceId'
- | 'machineId'
- | 'workspaceDocument'
- | 'queueSteerOperationStore'
- | 'recordChatFailure'
- | 'logger'
-> & {
+type Recovery = SessionQueueSteerResponse | 'deferred' | 'retryable' | null;
+export type QueueSteerServiceDeps = {
+ workspaceId: WorkspaceId;
+ machineId: MachineId;
+ workspaceDocument: Pick;
+ queueSteerOperationStore: QueueSteerOperationStore;
+ logger: Logger;
+ recordChatFailure(
+ sessionDoc: SessionDocument,
+ reason: ChatFailedReason,
+ message?: string,
+ code?: ChatFailedCode
+ ): Promise;
requeue(
sessionId: SessionId,
userTurnId: string
@@ -70,11 +82,11 @@ export class QueueSteerService extends Context.Tag('lody/QueueSteerService')<
mutate(request: SessionQueueMutation): Effect.Effect;
}
>() {
- static layer(deps: Deps) {
+ static layer(deps: QueueSteerServiceDeps) {
return Layer.effect(QueueSteerService, QueueSteerService.make(deps));
}
- static make(deps: Deps) {
+ static make(deps: QueueSteerServiceDeps) {
return Effect.gen(function* () {
const active = yield* ActiveTurnSteerPort;
const receipts = new Map();
@@ -218,14 +230,8 @@ export class QueueSteerService extends Context.Tag('lody/QueueSteerService')<
const request = { sessionId, queueItemId: marker.queueItemId };
if (!entry) {
if (marker.phase !== 'reserved') return 'deferred';
- return yield* complete(
- sessionId,
- marker,
- respond(request, 'error', {
- userTurnId: marker.userTurnId,
- error: 'Reservation ended before history was persisted. The message remains queued.',
- })
- );
+ yield* persist(() => deps.queueSteerOperationStore.clear(sessionId));
+ return 'retryable';
}
if (marker.phase === 'reserved' || marker.phase === 'fallback') {
return yield* fallback(
@@ -306,13 +312,13 @@ export class QueueSteerService extends Context.Tag('lody/QueueSteerService')<
if (previous.operationKey === operationKey) {
if (previousReceipt) return remember(operationKey, previousReceipt);
const recovered = yield* recoverMarker(sessionId, doc, previous);
- return recovered && recovered !== 'deferred'
- ? recovered
- : respond(request, 'error', {
- error: 'The previous delivery is still indeterminate.',
- });
- }
- if (!previousReceipt)
+ if (recovered !== 'retryable')
+ return recovered && recovered !== 'deferred'
+ ? recovered
+ : respond(request, 'error', {
+ error: 'The previous delivery is still indeterminate.',
+ });
+ } else if (!previousReceipt)
return respond(request, 'busy', {
error: 'Another queue operation is being recovered.',
});
diff --git a/apps/cli/tests/session-execution-service.test.ts b/apps/cli/tests/session-execution-service.test.ts
index d249e5522..a8237713d 100644
--- a/apps/cli/tests/session-execution-service.test.ts
+++ b/apps/cli/tests/session-execution-service.test.ts
@@ -1,4 +1,12 @@
import { queueItemRevision } from '@lody/shared';
+import { CURRENT_MACHINE_PROTOCOL_CAPABILITIES } from '@lody/shared';
+import { createWorkspaceMachineRpcFacade } from '../../../packages/components/src/providers/workspace-machine-rpc-facade';
+import {
+ LoroStreamsMachineRpcClient,
+ LoroStreamsMachineRpcServer,
+ type LoroStreamsJsonStreamClient,
+ type LoroJsonLiveBatchHandler,
+} from '@lody/loro-streams-rpc';
import { SessionDocument } from '../src/lib/loro/doc';
import { composeTestSessionDoc } from './session-doc-fixture';
import { withHistoryPort } from './history-port-fixture';
@@ -331,6 +339,189 @@ describe('SessionExecutionService', () => {
};
};
+ it.each(['startup', 'same-request', 'clear-failure'] as const)(
+ 'retries C/T after pre-history recovery via %s',
+ async (mode) => {
+ const h = await ownedQueue();
+ await h.deps.queueSteerOperationStore.record({
+ version: 2,
+ workspaceId: 'workspace-1',
+ machineId: 'machine-1',
+ ...h.request,
+ operationKey: JSON.stringify([
+ h.request.sessionId,
+ h.request.expectedTurnId,
+ h.request.queueItemId,
+ ]),
+ userTurnId: 'user:C',
+ phase: 'reserved',
+ updatedAt: 1,
+ });
+ const restarted = new SessionExecutionService(h.deps);
+ if (mode === 'startup') {
+ await restarted.recoverPendingQueueSteers();
+ expect(await h.deps.queueSteerOperationStore.read(h.request.sessionId)).toBeNull();
+ expect(await h.doc.getMessageQueue()).toEqual(h.rows);
+ expect(await h.doc.sessionData.history.readAll()).toEqual([]);
+ }
+ (
+ restarted as unknown as { turnRuntimeBySession: Map }
+ ).turnRuntimeBySession.set(h.request.sessionId, h.runtime);
+ h.steerPrompt.mockImplementation(() => ({
+ applied: Promise.resolve({ release: () => {} }),
+ completion: Promise.resolve(),
+ }));
+ if (mode === 'clear-failure') {
+ vi.spyOn(h.deps.queueSteerOperationStore, 'clear').mockRejectedValueOnce(
+ new Error('marker clear failed')
+ );
+ expect(await restarted.steerQueuedMessage(h.request)).toMatchObject({
+ accepted: false,
+ error: 'marker clear failed',
+ });
+ expect(await h.deps.queueSteerOperationStore.read(h.request.sessionId)).toMatchObject({
+ phase: 'reserved',
+ });
+ expect(await h.doc.getMessageQueue()).toEqual(h.rows);
+ expect(await h.doc.sessionData.history.readAll()).toEqual([]);
+ expect(h.runtime.userTurnId).toBe('user:active');
+ }
+ expect(await restarted.steerQueuedMessage(h.request)).toMatchObject({ accepted: true });
+ expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(['A', 'B']);
+ expect(h.runtime.userTurnId).toBe('user:C');
+ expect(await h.deps.queueSteerOperationStore.read(h.request.sessionId)).toMatchObject({
+ phase: 'applied',
+ response: { disposition: 'accepted' },
+ });
+ }
+ );
+
+ it.each(['private-project', 'local-sender-missing'] as const)(
+ 'traces %s rejection before Streams and daemon state changes',
+ async (scenario) => {
+ const h = await ownedQueue();
+ const machineId = 'machine-1' as MachineId;
+ const meta = await h.doc.getMetaState();
+ vi.spyOn(h.doc, 'getMetaState').mockResolvedValue({
+ ...meta,
+ project: { kind: 'local', localProjectId: 'private-P' },
+ } as SessionMeta);
+ const appended: unknown[] = [];
+ const readers = new Map();
+ const streamClient: LoroStreamsJsonStreamClient = {
+ ensureJsonStream: async () => {},
+ appendJson: async (streamId, value) => {
+ appended.push(value);
+ const reader = readers.get(streamId);
+ if (!reader) throw new Error('Missing test stream reader');
+ await reader({ messages: [value], nextOffset: String(appended.length), upToDate: true });
+ return String(appended.length);
+ },
+ readJsonLive: async (streamId, _state, onBatch, options) => {
+ readers.set(streamId, onBatch);
+ await new Promise((resolve) => {
+ if (options?.signal?.aborted) resolve();
+ else options?.signal?.addEventListener('abort', () => resolve(), { once: true });
+ });
+ readers.delete(streamId);
+ },
+ };
+ const server = new LoroStreamsMachineRpcServer({
+ workspaceId: h.deps.workspaceId,
+ machineId,
+ logger: createSilentLogger(),
+ streamClient,
+ getMachineStatus: vi.fn(),
+ refreshMachineAcpCapabilities: vi.fn(),
+ steerQueuedMessage: (args) => h.service.steerQueuedMessage(args),
+ mutateQueuedMessage: (args) => h.service.mutateQueuedMessage(args),
+ });
+ const client = new LoroStreamsMachineRpcClient({
+ workspaceId: h.deps.workspaceId,
+ machineId,
+ streamClient,
+ });
+ let projectVisible = false;
+ let plane: 'local' | 'cloud' = scenario === 'private-project' ? 'cloud' : 'local';
+ const getMachineRpcClient = vi.fn(async () => client);
+ const facade = createWorkspaceMachineRpcFacade({
+ workspaceId: h.deps.workspaceId,
+ targetRouter: {
+ getPlaneForMachine: () => plane,
+ resolvePlaneForMachine: async () => plane,
+ },
+ getMachineProtocolCapabilities: async () => CURRENT_MACHINE_PROTOCOL_CAPABILITIES,
+ getSessionMeta: async () => h.doc.getMetaState(),
+ getSessionControlAuthorization: () => ({
+ visibleMachineIds: new Set([machineId]),
+ visibleLocalProjectKeys: new Set(projectVisible ? [machineId + ':private-P'] : []),
+ currentUserId: 'user-U',
+ }),
+ getMachineRpcClient,
+ });
+ await server.start();
+ try {
+ const error =
+ scenario === 'private-project'
+ ? 'Source authorization for this session is unavailable or denied.'
+ : 'Local queue control is unavailable.';
+ expect(await facade.requestSessionQueueSteer(machineId, h.request)).toMatchObject({
+ accepted: false,
+ error,
+ });
+ expect(
+ await facade.requestSessionQueueMutation(machineId, {
+ sessionId: h.request.sessionId,
+ mutation: {
+ kind: 'remove',
+ queueItemId: h.request.queueItemId,
+ expectedRevision: queueItemRevision(h.rows[2]),
+ },
+ })
+ ).toMatchObject({ success: false, error });
+ expect(getMachineRpcClient).not.toHaveBeenCalled();
+ expect(appended).toEqual([]);
+ expect(await h.deps.queueSteerOperationStore.read(h.request.sessionId)).toBeNull();
+ expect(await h.doc.getMessageQueue()).toEqual(h.rows);
+ expect(await h.doc.sessionData.history.readAll()).toEqual([]);
+ expect(h.runtime.userTurnId).toBe('user:active');
+ expect(h.runtime.promptInFlight).toBe(true);
+ // Positive control traverses the same real RPC client/server and execution service.
+ projectVisible = true;
+ plane = 'cloud';
+ h.steerPrompt.mockImplementation(() => ({
+ applied: Promise.resolve({ release: () => {} }),
+ completion: Promise.resolve(),
+ }));
+ expect(await facade.requestSessionQueueSteer(machineId, h.request)).toMatchObject({
+ accepted: true,
+ });
+ expect(appended.length).toBeGreaterThan(0);
+ expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(['A', 'B']);
+ expect(h.runtime.userTurnId).toBe('user:C');
+ expect(await h.deps.queueSteerOperationStore.read(h.request.sessionId)).toMatchObject({
+ phase: 'applied',
+ });
+ const secondRow = h.rows[1];
+ if (!secondRow) throw new Error('Missing B fixture');
+ expect(
+ await facade.requestSessionQueueMutation(machineId, {
+ sessionId: h.request.sessionId,
+ mutation: {
+ kind: 'remove',
+ queueItemId: secondRow.$cid,
+ expectedRevision: queueItemRevision(secondRow),
+ },
+ })
+ ).toMatchObject({ success: true });
+ expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(['A']);
+ } finally {
+ client.stop();
+ server.stop();
+ }
+ }
+ );
+
it.each(['update', 'remove', 'reorder'] as const)(
'rejects a stale second-client %s after reservation, with removal durable before submission',
async (kind) => {
@@ -1346,47 +1537,6 @@ describe('SessionExecutionService', () => {
).resolves.toMatchObject({ machineId: 'machine-2', phase: 'reserved' });
});
- it('leaves the row queued when a crash precedes the reserved history write', async () => {
- const sessionId = 'session-native-steer-pre-history-crash' as SessionId;
- const queueSteerOperationStore = createMemoryQueueSteerOperationStore();
- await queueSteerOperationStore.record({
- version: 1,
- workspaceId: 'workspace-1',
- machineId: 'machine-1',
- sessionId,
- operationKey: 'pre-history-operation',
- queueItemId: 'C',
- expectedTurnId: 'assistant:old',
- userTurnId: 'user:C',
- phase: 'reserved',
- updatedAt: 1,
- });
- const removeMessageQueueItem = vi.fn(async () => {});
- const sessionDoc = withHistoryPort({
- waitUntilSynced: vi.fn(async () => {}),
- getHistory: () => [],
- getMessageQueue: vi.fn(async () => [{ $cid: 'C', task: 'task C' }]),
- removeMessageQueueItem,
- });
- const deps = createBaseDeps({
- queueSteerOperationStore,
- workspaceDocument: {
- repo: { upsertDocMeta: vi.fn(async () => {}) },
- getOrCreateSessionDoc: vi.fn(async () => sessionDoc),
- } as unknown as LoroDocumentManager,
- });
- const service = new SessionExecutionService(deps);
-
- await service.recoverPendingQueueSteers();
-
- expect(removeMessageQueueItem).not.toHaveBeenCalled();
- await expect(queueSteerOperationStore.read(sessionId)).resolves.toMatchObject({
- phase: 'reserved',
- completedAt: expect.any(Number),
- response: { disposition: 'error' },
- });
- });
-
it('advances one session owner through consecutive prompt handoffs', async () => {
const steerPrompt = vi.fn(() => ({
completion: new Promise(() => {}),
diff --git a/packages/components/src/providers/AGENTS.md b/packages/components/src/providers/AGENTS.md
index de3d4c568..e05454a43 100644
--- a/packages/components/src/providers/AGENTS.md
+++ b/packages/components/src/providers/AGENTS.md
@@ -56,6 +56,9 @@ and update only decision fields through HistoryWriter; never replace a rendered
- Queue edit/remove/reorder on queueItemSteer v2 use the narrow daemon domain RPC,
with revision checks against reservation ownership. Never direct-write after RPC failure.
Enqueue and other user writes retain their renderer authority.
+- Remote queue Steer and mutation share source-side session visibility authorization:
+ verify target metadata against authenticated machine/project visibility and current user.
+ Missing metadata or incomplete snapshots fail closed; machine access alone is insufficient.
- Repo storage, durable Streams cursors, and eager-sync high-water state must use the
same per-renderer cache namespace. A checkpoint must never be shared by independently
persisted Repo views.
diff --git a/packages/components/src/providers/create-workspace-runtime.ts b/packages/components/src/providers/create-workspace-runtime.ts
index cba1ad310..4b270e7ce 100644
--- a/packages/components/src/providers/create-workspace-runtime.ts
+++ b/packages/components/src/providers/create-workspace-runtime.ts
@@ -127,6 +127,7 @@ import { META_REMOTE_CURSOR_BYPASS_STORAGE_KEY_PREFIX } from '@/lib/clear-local-
import { runStartupAcpCapabilitiesRefresh } from './startup-acp-capabilities-refresh';
import { createLocalLoroDataPlaneConnection } from './local-loro-data-plane-connection';
import { createWorkspaceMachineRpcFacade } from './workspace-machine-rpc-facade';
+import type { SessionControlAuthorization } from './session-control-authorization';
import { resyncMachineFlockRows } from '@/hooks/use-machine-flock-rows';
import { createCodeCollabFileIndexCache } from '@/lib/code-collab-file-index-cache';
import { getIpcServices, onIpcEvent, sendLocalSessionControl } from '@/lib/electron-ipc-client';
@@ -203,6 +204,7 @@ type RuntimeDeps = {
* authorization is not ready, so optional startup capability refresh is skipped.
*/
getAuthorizedMachineIds?: () => ReadonlySet | null;
+ getSessionControlAuthorization?: () => SessionControlAuthorization | null;
eagerSyncSurface?: EagerSyncSurface;
};
@@ -1722,7 +1724,11 @@ export async function createWorkspaceRuntime(deps: RuntimeDeps): Promise | undefined)?.protocolCapabilities;
},
- getAuthorizedMachineIds: deps.getAuthorizedMachineIds,
+ getSessionControlAuthorization: deps.getSessionControlAuthorization,
+ getSessionMeta: async (sessionId) => {
+ const entry = await repo.getDocMeta(getSessionRoomId(sessionId));
+ return entry?.meta as SessionMeta | undefined;
+ },
workspaceId,
targetRouter,
getMachineRpcClient,
diff --git a/packages/components/src/providers/runtime-provider.tsx b/packages/components/src/providers/runtime-provider.tsx
index 8f7f92760..687603f0f 100644
--- a/packages/components/src/providers/runtime-provider.tsx
+++ b/packages/components/src/providers/runtime-provider.tsx
@@ -2,7 +2,7 @@ import { useEffect, useRef, type ReactNode } from 'react';
import { useAtomValue, useSetAtom } from 'jotai';
import { LODY_PRESENCE_HEARTBEAT_MS, type MachineId, type WorkspaceId } from '@lody/shared';
import { authTokenAtom, runtimeAtom } from '@/atoms/runtime';
-import { currentWorkspaceIdAtom, currentWorkspaceSlugAtom } from '@/atoms';
+import { currentWorkspaceIdAtom, currentWorkspaceSlugAtom, userAtom } from '@/atoms';
import { clearDocMetaCacheAtom, docMetaSubscriptionAtom } from '@/atoms/doc-meta';
import {
clearLodyPresenceStatesAtom,
@@ -35,6 +35,9 @@ import { isElectronRenderer } from '@/lib/electron';
import { isNativeAppShell } from '@/lib/native-platform';
import { usePlatform } from '@lody/platform/react';
import { useVisibleMachineMetas } from '@/hooks/use-visible-machine-metas';
+import { useVisibleLocalProjectsFromMachineIndex } from '@/hooks/use-visible-local-projects';
+import { useAuthenticatedConvex } from '@/hooks/use-authenticated-convex';
+import type { SessionControlAuthorization } from './session-control-authorization';
const isExpectedRuntimeShutdownError = (error: unknown): boolean => {
if (!(error instanceof Error)) {
@@ -87,6 +90,29 @@ export function RuntimeProvider({ children }: { children: ReactNode }) {
includeMachineFlock: false,
syncMachineFlock: false,
});
+ const visibleProjectIndex = useVisibleLocalProjectsFromMachineIndex(visibleMachineIndex);
+ const currentUserId = useAtomValue(userAtom)?.id;
+ const authentication = useAuthenticatedConvex();
+ const sessionAuthorizationRef = useRef<{
+ workspaceId: WorkspaceId;
+ authorization: SessionControlAuthorization;
+ } | null>(null);
+ sessionAuthorizationRef.current =
+ !workspaceId ||
+ !currentUserId ||
+ !authentication.isAuthenticated ||
+ authentication.isLoading ||
+ visibleMachineIndex.isLoading ||
+ visibleProjectIndex.isLoading
+ ? null
+ : {
+ workspaceId,
+ authorization: {
+ visibleMachineIds: new Set(visibleMachineIndex.convexAuthorizedMachineIds),
+ visibleLocalProjectKeys: new Set(visibleProjectIndex.accessByProjectKey.keys()),
+ currentUserId,
+ },
+ };
const authorizedMachineIdsRef = useRef<{
machineIds: ReadonlySet;
workspaceId: WorkspaceId;
@@ -264,9 +290,16 @@ export function RuntimeProvider({ children }: { children: ReactNode }) {
const snapshot = authorizedMachineIdsRef.current;
return snapshot?.workspaceId === effectiveWorkspaceId ? snapshot.machineIds : null;
},
+ getSessionControlAuthorization: () => {
+ const snapshot = sessionAuthorizationRef.current;
+ return snapshot?.workspaceId === effectiveWorkspaceId ? snapshot.authorization : null;
+ },
...(telemetryEnabled
? {
- onAnalyticsEvent: (event: { name: string; properties?: Record }) => {
+ onAnalyticsEvent: (event: {
+ name: string;
+ properties?: Record;
+ }) => {
capturePostHogEvent(postHogRef.current, event.name, event.properties);
},
}
diff --git a/packages/components/src/providers/session-control-authorization.ts b/packages/components/src/providers/session-control-authorization.ts
new file mode 100644
index 000000000..5538ff145
--- /dev/null
+++ b/packages/components/src/providers/session-control-authorization.ts
@@ -0,0 +1,30 @@
+import type { MachineId, SessionId } from '@lody/shared';
+import { isSessionVisibleToUser, type SessionMachineRecord } from '../lib/session-visibility';
+
+export type SessionControlAuthorization = {
+ visibleMachineIds: ReadonlySet;
+ visibleLocalProjectKeys: ReadonlySet;
+ currentUserId?: string;
+};
+
+export type SessionControlAuthorizationDeps = {
+ getSessionMeta?: (sessionId: SessionId) => Promise;
+ /** Null until the authenticated machine and project snapshots are both ready. */
+ getSessionControlAuthorization?: () => SessionControlAuthorization | null;
+};
+
+export async function authorizeSessionControl(
+ deps: SessionControlAuthorizationDeps,
+ sessionId: SessionId,
+ machineId: MachineId
+): Promise {
+ const meta = await deps.getSessionMeta?.(sessionId);
+ const authorization = deps.getSessionControlAuthorization?.();
+ if (!meta || meta.machineId !== machineId || !authorization) return false;
+ return isSessionVisibleToUser(
+ meta,
+ authorization.visibleMachineIds,
+ authorization.visibleLocalProjectKeys,
+ authorization.currentUserId
+ );
+}
diff --git a/packages/components/src/providers/workspace-machine-rpc-facade.ts b/packages/components/src/providers/workspace-machine-rpc-facade.ts
index 3d2fda48b..f4e74a59c 100644
--- a/packages/components/src/providers/workspace-machine-rpc-facade.ts
+++ b/packages/components/src/providers/workspace-machine-rpc-facade.ts
@@ -67,9 +67,13 @@ import {
sessionForkFailure,
sessionEditAndResendFailure,
} from '@lody/shared';
-import { createAsyncConcurrencyGate } from '@/lib/async-concurrency-gate';
-import { getIpcServices } from '@/lib/electron-ipc-client';
+import { createAsyncConcurrencyGate } from '../lib/async-concurrency-gate';
+import { getIpcServices } from '../lib/electron-ipc-client';
import type { WorkspaceTargetRouter } from './workspace-target-router';
+import {
+ authorizeSessionControl,
+ type SessionControlAuthorizationDeps,
+} from './session-control-authorization';
const LOCAL_MACHINE_ID_READY_TIMEOUT_MS = 2_000;
const CODE_COLLAB_DIFF_RPC_CONCURRENCY_LIMIT = 4;
@@ -90,14 +94,12 @@ type LspRequest = {
readonly character?: number;
};
-export type WorkspaceMachineRpcFacadeDeps = {
+export type WorkspaceMachineRpcFacadeDeps = SessionControlAuthorizationDeps & {
workspaceId: WorkspaceId;
targetRouter: Pick;
getMachineProtocolCapabilities: (
machineId: MachineId
) => Promise;
- /** Authenticated source snapshot; null means cloud authorization is not ready. */
- getAuthorizedMachineIds?: () => ReadonlySet | null;
getMachineRpcClient: (machineId: MachineId) => Promise;
};
@@ -137,6 +139,18 @@ export function createWorkspaceMachineRpcFacade(deps: WorkspaceMachineRpcFacadeD
);
};
+ const resolveSessionControlPlane = async (machineId: MachineId) => {
+ const plane =
+ targetRouter.getPlaneForMachine(machineId) ??
+ (await targetRouter.resolvePlaneForMachine(machineId, {
+ timeoutMs: LOCAL_MACHINE_ID_READY_TIMEOUT_MS,
+ }));
+ if (plane !== 'local' && plane !== 'cloud') {
+ throw new Error('Session control routing is unavailable.');
+ }
+ return plane;
+ };
+
const sendLocalMachineRpcRequest = async (
request: LocalMachineRpcRequest
): Promise => {
@@ -780,7 +794,7 @@ export function createWorkspaceMachineRpcFacade(deps: WorkspaceMachineRpcFacadeD
if (!machineSupportsQueueItemSteerProtocol({ protocolCapabilities })) {
throw new Error('This daemon does not support queue ownership controls.');
}
- if (await canUseLocalMachineRpc(machineId)) {
+ if ((await resolveSessionControlPlane(machineId)) === 'local') {
const response = await getLocalMachineRpcSender()?.({
machineId,
workspaceId,
@@ -792,8 +806,8 @@ export function createWorkspaceMachineRpcFacade(deps: WorkspaceMachineRpcFacadeD
if (!response.ok) throw new Error(response.error);
return response.result as SessionQueueMutationResponse;
}
- if (!deps.getAuthorizedMachineIds?.()?.has(machineId)) {
- throw new Error('Source authorization for this machine is unavailable or denied.');
+ if (!(await authorizeSessionControl(deps, args.sessionId, machineId))) {
+ throw new Error('Source authorization for this session is unavailable or denied.');
}
return await (await getMachineRpcClient(machineId)).requestSessionQueueMutation(args);
} catch (error) {
@@ -826,7 +840,7 @@ export function createWorkspaceMachineRpcFacade(deps: WorkspaceMachineRpcFacadeD
error: 'This machine does not support exact queued-message steering.',
};
}
- if (await canUseLocalMachineRpc(machineId)) {
+ if ((await resolveSessionControlPlane(machineId)) === 'local') {
const response = await getLocalMachineRpcSender()?.({
machineId,
workspaceId,
@@ -847,15 +861,14 @@ export function createWorkspaceMachineRpcFacade(deps: WorkspaceMachineRpcFacadeD
if (response?.ok) return response.result as SessionQueueSteerResponse;
throw new Error('Local queue control is unavailable.');
}
- const authorizedMachineIds = deps.getAuthorizedMachineIds?.() ?? null;
- if (!authorizedMachineIds?.has(machineId)) {
+ if (!(await authorizeSessionControl(deps, args.sessionId, machineId))) {
return {
type: 'session/queue-steer_response',
sessionId: args.sessionId,
queueItemId: args.queueItemId,
accepted: false,
disposition: 'error',
- error: 'Source authorization for this machine is unavailable or denied.',
+ error: 'Source authorization for this session is unavailable or denied.',
};
}
return await (
diff --git a/packages/components/tests/workspace-machine-rpc-facade.test.ts b/packages/components/tests/workspace-machine-rpc-facade.test.ts
index 7af58e6ca..6be044a47 100644
--- a/packages/components/tests/workspace-machine-rpc-facade.test.ts
+++ b/packages/components/tests/workspace-machine-rpc-facade.test.ts
@@ -17,6 +17,61 @@ afterEach(() => {
});
describe('createWorkspaceMachineRpcFacade', () => {
+ it.each([
+ 'snapshot-missing',
+ 'meta-missing',
+ 'wrong-machine',
+ 'revoked-during-meta-read',
+ 'route-missing',
+ ] as const)('fails both session controls closed for %s', async (scenario) => {
+ let authorization =
+ scenario === 'snapshot-missing'
+ ? null
+ : {
+ visibleMachineIds: new Set([remoteMachineId]),
+ visibleLocalProjectKeys: new Set(),
+ currentUserId: 'user-U',
+ };
+ const getMachineRpcClient = vi.fn(async () => {
+ throw new Error('Remote client must not be created');
+ });
+ const facade = createWorkspaceMachineRpcFacade({
+ workspaceId,
+ getMachineProtocolCapabilities: async () => CURRENT_MACHINE_PROTOCOL_CAPABILITIES,
+ getSessionControlAuthorization: () => authorization,
+ getSessionMeta: async () => {
+ if (scenario === 'revoked-during-meta-read') authorization = null;
+ return scenario === 'meta-missing'
+ ? undefined
+ : {
+ machineId: scenario === 'wrong-machine' ? localMachineId : remoteMachineId,
+ };
+ },
+ targetRouter: {
+ getPlaneForMachine: () => (scenario === 'route-missing' ? null : 'cloud'),
+ resolvePlaneForMachine: async () => null,
+ },
+ getMachineRpcClient,
+ });
+ const error =
+ scenario === 'route-missing'
+ ? 'Session control routing is unavailable.'
+ : 'Source authorization for this session is unavailable or denied.';
+ expect(
+ await facade.requestSessionQueueSteer(remoteMachineId, {
+ sessionId,
+ queueItemId: 'C',
+ expectedTurnId: 'T',
+ })
+ ).toMatchObject({ accepted: false, error });
+ expect(
+ await facade.requestSessionQueueMutation(remoteMachineId, {
+ sessionId,
+ mutation: { kind: 'remove', queueItemId: 'C', expectedRevision: '{}' },
+ })
+ ).toMatchObject({ success: false, error });
+ expect(getMachineRpcClient).not.toHaveBeenCalled();
+ });
it.each([undefined, { queueItemSteer: 1 }])(
'disables every old-daemon queue row for %j',
async (capabilities) => {
@@ -24,8 +79,8 @@ describe('createWorkspaceMachineRpcFacade', () => {
workspaceId,
getMachineProtocolCapabilities: async () => capabilities,
targetRouter: {
- getPlaneForMachine: () => 'remote',
- resolvePlaneForMachine: async () => 'remote',
+ getPlaneForMachine: () => 'cloud',
+ resolvePlaneForMachine: async () => 'cloud',
},
getMachineRpcClient: async () => {
throw new Error('Legacy delivery must not run');
@@ -133,8 +188,8 @@ describe('createWorkspaceMachineRpcFacade', () => {
workspaceId,
getMachineProtocolCapabilities: async () => undefined,
targetRouter: {
- getPlaneForMachine: () => 'remote',
- resolvePlaneForMachine: async () => 'remote',
+ getPlaneForMachine: () => 'cloud',
+ resolvePlaneForMachine: async () => 'cloud',
},
getMachineRpcClient,
});
@@ -155,10 +210,10 @@ describe('createWorkspaceMachineRpcFacade', () => {
const facade = createWorkspaceMachineRpcFacade({
workspaceId,
getMachineProtocolCapabilities: async () => CURRENT_MACHINE_PROTOCOL_CAPABILITIES,
- getAuthorizedMachineIds: () => null,
+ getSessionControlAuthorization: () => null,
targetRouter: {
- getPlaneForMachine: () => 'remote',
- resolvePlaneForMachine: async () => 'remote',
+ getPlaneForMachine: () => 'cloud',
+ resolvePlaneForMachine: async () => 'cloud',
},
getMachineRpcClient,
});
@@ -185,10 +240,14 @@ describe('createWorkspaceMachineRpcFacade', () => {
const facade = createWorkspaceMachineRpcFacade({
workspaceId,
getMachineProtocolCapabilities: async () => CURRENT_MACHINE_PROTOCOL_CAPABILITIES,
- getAuthorizedMachineIds: () => new Set([remoteMachineId]),
+ getSessionMeta: async () => ({ machineId: remoteMachineId }),
+ getSessionControlAuthorization: () => ({
+ visibleMachineIds: new Set([remoteMachineId]),
+ visibleLocalProjectKeys: new Set(),
+ }),
targetRouter: {
- getPlaneForMachine: () => 'remote',
- resolvePlaneForMachine: async () => 'remote',
+ getPlaneForMachine: () => 'cloud',
+ resolvePlaneForMachine: async () => 'cloud',
},
getMachineRpcClient: async () => ({ requestSessionQueueSteer }) as never,
});
@@ -213,8 +272,8 @@ describe('createWorkspaceMachineRpcFacade', () => {
workspaceId,
getMachineProtocolCapabilities: async () => undefined,
targetRouter: {
- getPlaneForMachine: () => 'remote',
- resolvePlaneForMachine: async () => 'remote',
+ getPlaneForMachine: () => 'cloud',
+ resolvePlaneForMachine: async () => 'cloud',
},
getMachineRpcClient: async () => {
throw new Error('Unexpected RPC');
diff --git a/specs/message-queue-interactions.md b/specs/message-queue-interactions.md
index 7d61c9d76..b08a7ab2b 100644
--- a/specs/message-queue-interactions.md
+++ b/specs/message-queue-interactions.md
@@ -46,11 +46,18 @@ the queue by hand.
preconditions. Indeterminate delivery must propagate without replay; local failures recover
from durable evidence and never imply non-delivery by themselves.
- A remote renderer must authorize the target before writing the request, using its
- authenticated authoritative machine-access snapshot and failing closed if that snapshot is
- unavailable. The request carries no requester identity: workspace Machine RPC cannot
+ Both `session/queue-steer` and `session/queue-mutate` must pass one source-side session
+ authorization before a remote request is written. The session metadata must match the target
+ machine; access follows `isSessionVisibleToUser` using authenticated machine visibility,
+ local-project visibility and the current user. Visible machine access alone does not grant
+ access to another user's private local-project session. Missing metadata or an incomplete
+ authorization snapshot fails closed, with no machine-only fallback.
+ The request carries no requester identity: workspace Machine RPC cannot
authenticate a caller-supplied member ID, and the target daemon must not use one for an owner
fast path. Same-host local IPC is already the trusted local control boundary.
+ Routing is resolved before transport availability: local with no sender returns a local
+ transport error, and unresolved routing returns an error. Neither can create a Streams
+ client or append a remote request; transport failure cannot change the selected plane.
Native exact Steer must derive its requester identity from the authenticated active
invocation, never from the shared queue row. If that frozen identity is unavailable, the
@@ -83,9 +90,11 @@ the queue by hand.
Any failure to persist the reservation, history, or removal forbids provider submission.
Removing the row before the network call is necessary but does not replace the ownership
boundary during steps 1–4. Native recovery uses the machine-local marker plus frozen history,
- not an editable queue row as a retry token. A pre-history reservation interrupted by a crash
- must be reconciled as unsubmitted before its surviving row becomes editable again; it must not
- report a stale edit as saved or construct a turn from later queue content. Once history is
+ not an editable queue row as a retry token. A `reserved` marker with no history is unsubmitted:
+ recovery clears the marker, leaves the surviving row untouched and creates no terminal receipt.
+ The same queue item/expected turn may retry immediately, including within the current request,
+ after rereading and validating the queue and live turn as a new reservation. Failed marker
+ cleanup blocks that retry. Once history is
durable, recovery can finish removal and recover the same turn without requiring the row to
exist. A new missing-row request still fails; replay of the same reserved operation resolves
through its marker or receipt.
diff --git a/specs/message-queue-interactions.zh.md b/specs/message-queue-interactions.zh.md
index 1a2db8870..556316294 100644
--- a/specs/message-queue-interactions.zh.md
+++ b/specs/message-queue-interactions.zh.md
@@ -40,10 +40,16 @@ Translation: current
交付不确定须向上传递，禁止 replay；本地失败依据 durable evidence 恢复，不能仅凭本地
失败推断未交付。
- 远程 Renderer 在写入请求前，必须使用其已认证的权威 machine-access 快照验证目标；快照
- 不可用时应 fail closed。请求不得携带请求者身份：workspace Machine RPC 无法认证调用方
+ `session/queue-steer` 与 `session/queue-mutate` 在写入远程请求前，必须共用 source-side
+ session 授权。Session metadata 必须匹配目标 machine；权限通过 `isSessionVisibleToUser`
+ 根据已认证的 machine visibility、local-project visibility 和 current user 判断。
+ Machine 可见不意味着其他用户的私有 local-project session 可见。Metadata 缺失或授权快照
+ 不完整时 fail closed，绝不降级成 machine-only 检查。
+ 请求不得携带请求者身份：workspace Machine RPC 无法认证调用方
声称的成员 ID，目标 daemon 也不得用它命中 owner fast path。同机 local IPC 已是可信的
本地控制边界。
+ 先确定 routing plane，再检查 transport：local 缺少 sender 返回本地传输错误，路由未确定
+ 则返回路由错误。两者都不得创建 Streams client 或追加远程请求；传输失败不能改变已选 plane。
Native 精确“引导”的 requester identity 必须来自已认证的活动 invocation，绝不来自共享
queue row。若该冻结身份不可用，daemon 必须在消费 row、提交 provider 或停止 turn 之前失败。
@@ -71,9 +77,10 @@ Translation: current
reservation、history 或删除任一持久化失败，都禁止提交 provider。网络调用前删除 row
是必要条件，但不能替代步骤 1–4 期间的 ownership 边界。Native 恢复依赖 machine-local
- marker 与冻结 history，不再拿可编辑 queue row 当 retry token。若在 history 持久化前
- 崩溃，须先将 reservation 对账为未提交，剩余 row 才能恢复可编辑；不得把旧客户端编辑
- 报成保存成功，也不得从后来的 queue 内容构建 turn。history 持久化后，恢复可完成删除并
+ marker 与冻结 history，不再拿可编辑 queue row 当 retry token。`reserved` marker 没有
+ history 时属于未提交：恢复清除 marker，保留剩余 row，不生成终态 receipt。同一个 queue
+ item/expected turn 可立即重试，包括继续当前请求，但必须重新读取并验证 queue 和 live turn，
+ 建立新的 reservation。Marker 清理失败时不得继续重试。history 持久化后，恢复可完成删除并
恢复同一个 turn，无需 row 仍存在。新的缺失 row 请求仍失败；同一 reserved operation
的重试通过 marker 或 receipt 解析。
From 204e0d3d18cf3248f2dd06a4c1ebbc6ee4a18ce2 Mon Sep 17 00:00:00 2001
From: wibus-wee <62133302+wibus-wee@users.noreply.github.com>
Date: Mon, 14 Sep 2026 17:54:26 +0800
Subject: [PATCH 13/15] fix: satisfy queue steer static checks
Make local/remote mutation outcomes and successful Effect guard completion explicit, and align the machine registration assertion with queueItemSteer v2.\n\nModel: gpt-5
---
apps/cli/src/session/queue-steer-service.ts | 1 +
apps/cli/src/session/session-execution-service.ts | 1 +
apps/cli/tests/message-handler-machine-registration.test.ts | 2 +-
packages/components/src/providers/workspace-writer-impl.ts | 3 +++
4 files changed, 6 insertions(+), 1 deletion(-)
diff --git a/apps/cli/src/session/queue-steer-service.ts b/apps/cli/src/session/queue-steer-service.ts
index 6b928c8ac..ea03e624a 100644
--- a/apps/cli/src/session/queue-steer-service.ts
+++ b/apps/cli/src/session/queue-steer-service.ts
@@ -178,6 +178,7 @@ export class QueueSteerService extends Context.Tag('lody/QueueSteerService')<
yield* persist(() => doc.removeMessageQueueItem(marker.queueItemId));
}
yield* flush();
+ return undefined;
});
const fallback = Effect.fn('QueueSteer.fallback')(function* (
diff --git a/apps/cli/src/session/session-execution-service.ts b/apps/cli/src/session/session-execution-service.ts
index acac76ab7..22a4891bb 100644
--- a/apps/cli/src/session/session-execution-service.ts
+++ b/apps/cli/src/session/session-execution-service.ts
@@ -1624,6 +1624,7 @@ export class SessionExecutionService {
message: 'The active turn is stopping.',
});
}
+ return undefined;
});
const sessionDoc = yield* prepare(() =>
self.deps.workspaceDocument.getOrCreateSessionDoc(options.sessionId)
diff --git a/apps/cli/tests/message-handler-machine-registration.test.ts b/apps/cli/tests/message-handler-machine-registration.test.ts
index 90c428cfe..39fb95301 100644
--- a/apps/cli/tests/message-handler-machine-registration.test.ts
+++ b/apps/cli/tests/message-handler-machine-registration.test.ts
@@ -187,7 +187,7 @@ describe('MessageHandler machine registration', () => {
localFileResources: 1,
providerSetup: 1,
acpProtocolAuthentication: 2,
- queueItemSteer: 1,
+ queueItemSteer: 2,
subagentCancellation: 1,
});
diff --git a/packages/components/src/providers/workspace-writer-impl.ts b/packages/components/src/providers/workspace-writer-impl.ts
index 5f50f2980..fd708735e 100644
--- a/packages/components/src/providers/workspace-writer-impl.ts
+++ b/packages/components/src/providers/workspace-writer-impl.ts
@@ -199,6 +199,7 @@ export function createDirectWorkspaceWriter(deps: DirectWorkspaceWriterDeps): Wo
const mq = (draft.mq ?? []) as MessageQueueItem[];
draft.mq = mq.filter((item) => item.$cid !== itemId);
});
+ return false;
});
if (!remote) await bumpMessageQueueWatermark(sessionId);
},
@@ -230,6 +231,7 @@ export function createDirectWorkspaceWriter(deps: DirectWorkspaceWriterDeps): Wo
: item
);
});
+ return false;
});
if (!remote) await bumpMessageQueueWatermark(sessionId);
},
@@ -264,6 +266,7 @@ export function createDirectWorkspaceWriter(deps: DirectWorkspaceWriterDeps): Wo
}
draft.mq = ordered;
});
+ return false;
});
if (!remote) await bumpMessageQueueWatermark(sessionId);
},
From 64fc2f1d1d14cb2f2c9dac0de84df41806b711b5 Mon Sep 17 00:00:00 2001
From: wibus-wee <62133302+wibus-wee@users.noreply.github.com>
Date: Mon, 14 Sep 2026 18:15:33 +0800
Subject: [PATCH 14/15] fix: separate session control authorization from UI
visibility
Require current machine and local-project access for queue controls, remove the session-owner authorization fallback, and cover revoked-owner requests with end-to-end in-memory traces.
Model: gpt-6
---
.agents/docs/rpc-loro-streams-rpc.md | 7 +-
.../2026-09-14-queue-steer-effect-boundary.md | 13 +-
...26-09-14-queue-steer-effect-boundary.zh.md | 9 +-
.../tests/session-execution-service.test.ts | 255 +++++++++---------
packages/components/src/providers/AGENTS.md | 6 +-
.../src/providers/runtime-provider.tsx | 1 -
.../session-control-authorization.ts | 28 +-
.../workspace-machine-rpc-facade.test.ts | 1 -
specs/message-queue-interactions.md | 7 +-
specs/message-queue-interactions.zh.md | 7 +-
10 files changed, 181 insertions(+), 153 deletions(-)
diff --git a/.agents/docs/rpc-loro-streams-rpc.md b/.agents/docs/rpc-loro-streams-rpc.md
index 14564aa05..9eeca24bb 100644
--- a/.agents/docs/rpc-loro-streams-rpc.md
+++ b/.agents/docs/rpc-loro-streams-rpc.md
@@ -32,9 +32,10 @@ row until history and its activation pointer are durable. Missing, editing, and
do neither.
Before either remote queue control is written, the shared
[source authorizer](../../packages/components/src/providers/session-control-authorization.ts)
-matches session metadata to the target machine and applies the existing session visibility
-policy to authenticated machine/project snapshots and current user. Incomplete snapshots fail
-closed; shared machine access does not expose another user's private project. Local routing
+matches session metadata to the target machine and requires current machine access plus
+matching project access for local-project sessions. Unlike UI visibility, control has no
+session-owner fallback: authorship cannot override revoked access. Incomplete snapshots fail
+closed. Local routing
with an unavailable sender fails locally without creating a Streams client.
The retained request contains no requester identity:
the target daemon cannot authenticate such a claim and must not grant its owner fast path from it.
diff --git a/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.md b/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.md
index 75766889e..ba98b9707 100644
--- a/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.md
+++ b/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.md
@@ -56,9 +56,12 @@ Provider requester identity comes from the active invocation, not the shared que
Ordinary turn and composer routing remain unchanged.
The source facade shares [session authorization](../../../../packages/components/src/providers/session-control-authorization.ts)
-between queue Steer and mutation, using the existing session visibility predicate and complete
-authenticated machine/project snapshots. A machine-only check would expose private-project
-sessions. RuntimeProvider supplies a workspace-fenced snapshot; missing metadata or authorization
+between queue Steer and mutation, using complete authenticated machine/project snapshots.
+Control requires machine access plus matching project access for local-project sessions.
+Reusing UI visibility was incorrect: its intentional session-owner fallback permits display
+after machine access is revoked, but must not grant control. The control contract therefore
+contains no currentUserId or session-owner input and does not call the visibility predicate.
+RuntimeProvider supplies a workspace-fenced snapshot; missing metadata or authorization
fails closed. Routing plane is decided independently of sender availability: local failure cannot
fall through to Streams. The target daemon cannot authenticate a caller identity from this RPC.
@@ -120,7 +123,9 @@ No race assertion depends on sleeps or real network scheduling.
The execution suite connects the real source facade, Streams client/server, LoroDoc and execution
service over an in-memory transport. A visible machine with a denied private project rejects
-both controls with zero appends, no marker, and unchanged queue/history/active turn. Local routing
+both controls with zero appends, no marker, and unchanged queue/history/active turn. The same
+trace covers session creators with revoked machine or denied project access, even while UI
+visibility remains true; a retained project grant cannot override machine revocation. Local routing
with no sender also rejects without constructing the remote client. A positive project-access
control reaches the daemon and applies C. Restart and in-request pre-history recovery both allow
the same C/T to proceed. These are deterministic synthetic traces, not production-user traces.
diff --git a/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.zh.md b/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
index 17952eb74..954a97fe1 100644
--- a/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-14-queue-steer-effect-boundary.zh.md
@@ -53,8 +53,10 @@ Queue 服务不读取 runtime map、agentClient、promptInFlight、invocation
SessionExecutionServiceDeps。既有普通 turn 与 composer 路由不变。
Source facade 为队列 Steer 和 mutation 共用 [session 授权](../../../../packages/components/src/providers/session-control-authorization.ts)，
-使用已有 session visibility 判断和完整的已认证 machine/project 快照。Machine-only 检查会暴露
-私有项目 session。RuntimeProvider 提供按 workspace 隔离的快照；metadata 或授权缺失时
+使用完整的已认证 machine/project 快照。控制需要 machine 权限，local-project session 还需
+对应项目权限。复用 UI visibility 是错误的：它刻意允许 session 创建者在 machine 权限撤销后
+仍看到 session，但不能据此授予控制权。因此控制契约不包含 currentUserId 或 session owner，
+也不调用 visibility predicate。RuntimeProvider 提供按 workspace 隔离的快照；metadata 或授权缺失时
fail closed。Routing plane 独立于 sender 可用性，local 失败不能落入 Streams。
目标 daemon 无法从此 RPC 认证调用方身份。
@@ -109,7 +111,8 @@ receipt/restart，以及真实 LoroDoc 上的 reservation 与 edit/remove/reorde
Execution suite 用内存传输连接真实 source facade、Streams client/server、LoroDoc 和
execution service。Machine 可见但私有项目不可见时，两种 control 均拒绝：零 append、无 marker，
-queue/history/active turn 不变。Local 缺 sender 同样拒绝且不创建远程 client。开放项目权限的
+queue/history/active turn 不变。同一 trace 覆盖 session 创建者被撤销 machine 或拒绝项目权限，
+即使 UI visibility 仍为 true；残留项目权限不能绕过 machine 撤权。Local 缺 sender 同样拒绝且不创建远程 client。开放项目权限的
正向对照可到达 daemon 并应用 C。重启恢复和请求内 pre-history 恢复都允许相同 C/T 继续。
这些是确定性合成数据 trace，不是生产用户 trace。
diff --git a/apps/cli/tests/session-execution-service.test.ts b/apps/cli/tests/session-execution-service.test.ts
index a8237713d..ca87c85d9 100644
--- a/apps/cli/tests/session-execution-service.test.ts
+++ b/apps/cli/tests/session-execution-service.test.ts
@@ -1,6 +1,7 @@
import { queueItemRevision } from '@lody/shared';
import { CURRENT_MACHINE_PROTOCOL_CAPABILITIES } from '@lody/shared';
import { createWorkspaceMachineRpcFacade } from '../../../packages/components/src/providers/workspace-machine-rpc-facade';
+import { isSessionVisibleToUser } from '../../../packages/components/src/lib/session-visibility';
import {
LoroStreamsMachineRpcClient,
LoroStreamsMachineRpcServer,
@@ -396,131 +397,143 @@ describe('SessionExecutionService', () => {
}
);
- it.each(['private-project', 'local-sender-missing'] as const)(
- 'traces %s rejection before Streams and daemon state changes',
- async (scenario) => {
- const h = await ownedQueue();
- const machineId = 'machine-1' as MachineId;
- const meta = await h.doc.getMetaState();
- vi.spyOn(h.doc, 'getMetaState').mockResolvedValue({
- ...meta,
- project: { kind: 'local', localProjectId: 'private-P' },
- } as SessionMeta);
- const appended: unknown[] = [];
- const readers = new Map();
- const streamClient: LoroStreamsJsonStreamClient = {
- ensureJsonStream: async () => {},
- appendJson: async (streamId, value) => {
- appended.push(value);
- const reader = readers.get(streamId);
- if (!reader) throw new Error('Missing test stream reader');
- await reader({ messages: [value], nextOffset: String(appended.length), upToDate: true });
- return String(appended.length);
- },
- readJsonLive: async (streamId, _state, onBatch, options) => {
- readers.set(streamId, onBatch);
- await new Promise((resolve) => {
- if (options?.signal?.aborted) resolve();
- else options?.signal?.addEventListener('abort', () => resolve(), { once: true });
- });
- readers.delete(streamId);
- },
- };
- const server = new LoroStreamsMachineRpcServer({
- workspaceId: h.deps.workspaceId,
- machineId,
- logger: createSilentLogger(),
- streamClient,
- getMachineStatus: vi.fn(),
- refreshMachineAcpCapabilities: vi.fn(),
- steerQueuedMessage: (args) => h.service.steerQueuedMessage(args),
- mutateQueuedMessage: (args) => h.service.mutateQueuedMessage(args),
+ it.each([
+ 'private-project',
+ 'local-sender-missing',
+ 'revoked-owner-machine',
+ 'revoked-owner-project',
+ 'owner-private-project',
+ ] as const)('traces %s rejection before Streams and daemon state changes', async (scenario) => {
+ const h = await ownedQueue();
+ const machineId = 'machine-1' as MachineId;
+ const meta = await h.doc.getMetaState();
+ const sessionMeta = {
+ ...meta,
+ userId: scenario.includes('owner') ? 'user-U' : meta?.userId,
+ project:
+ scenario === 'revoked-owner-machine'
+ ? undefined
+ : { kind: 'local', localProjectId: 'private-P' },
+ } as SessionMeta;
+ vi.spyOn(h.doc, 'getMetaState').mockResolvedValue(sessionMeta);
+ const appended: unknown[] = [];
+ const readers = new Map();
+ const streamClient: LoroStreamsJsonStreamClient = {
+ ensureJsonStream: async () => {},
+ appendJson: async (streamId, value) => {
+ appended.push(value);
+ const reader = readers.get(streamId);
+ if (!reader) throw new Error('Missing test stream reader');
+ await reader({ messages: [value], nextOffset: String(appended.length), upToDate: true });
+ return String(appended.length);
+ },
+ readJsonLive: async (streamId, _state, onBatch, options) => {
+ readers.set(streamId, onBatch);
+ await new Promise((resolve) => {
+ if (options?.signal?.aborted) resolve();
+ else options?.signal?.addEventListener('abort', () => resolve(), { once: true });
+ });
+ readers.delete(streamId);
+ },
+ };
+ const server = new LoroStreamsMachineRpcServer({
+ workspaceId: h.deps.workspaceId,
+ machineId,
+ logger: createSilentLogger(),
+ streamClient,
+ getMachineStatus: vi.fn(),
+ refreshMachineAcpCapabilities: vi.fn(),
+ steerQueuedMessage: (args) => h.service.steerQueuedMessage(args),
+ mutateQueuedMessage: (args) => h.service.mutateQueuedMessage(args),
+ });
+ const client = new LoroStreamsMachineRpcClient({
+ workspaceId: h.deps.workspaceId,
+ machineId,
+ streamClient,
+ });
+ let projectVisible = scenario.startsWith('revoked');
+ let machineVisible = !scenario.startsWith('revoked');
+ let plane: 'local' | 'cloud' = scenario === 'local-sender-missing' ? 'local' : 'cloud';
+ const getMachineRpcClient = vi.fn(async () => client);
+ const facade = createWorkspaceMachineRpcFacade({
+ workspaceId: h.deps.workspaceId,
+ targetRouter: {
+ getPlaneForMachine: () => plane,
+ resolvePlaneForMachine: async () => plane,
+ },
+ getMachineProtocolCapabilities: async () => CURRENT_MACHINE_PROTOCOL_CAPABILITIES,
+ getSessionMeta: async () => h.doc.getMetaState(),
+ getSessionControlAuthorization: () => ({
+ visibleMachineIds: new Set(machineVisible ? [machineId] : []),
+ visibleLocalProjectKeys: new Set(projectVisible ? [machineId + ':private-P'] : []),
+ }),
+ getMachineRpcClient,
+ });
+ await server.start();
+ try {
+ const error =
+ scenario === 'local-sender-missing'
+ ? 'Local queue control is unavailable.'
+ : 'Source authorization for this session is unavailable or denied.';
+ if (scenario.includes('owner')) {
+ expect(isSessionVisibleToUser(sessionMeta, new Set(), new Set(), 'user-U')).toBe(true);
+ }
+ expect(await facade.requestSessionQueueSteer(machineId, h.request)).toMatchObject({
+ accepted: false,
+ error,
});
- const client = new LoroStreamsMachineRpcClient({
- workspaceId: h.deps.workspaceId,
- machineId,
- streamClient,
+ expect(
+ await facade.requestSessionQueueMutation(machineId, {
+ sessionId: h.request.sessionId,
+ mutation: {
+ kind: 'remove',
+ queueItemId: h.request.queueItemId,
+ expectedRevision: queueItemRevision(h.rows[2]),
+ },
+ })
+ ).toMatchObject({ success: false, error });
+ expect(getMachineRpcClient).not.toHaveBeenCalled();
+ expect(appended).toEqual([]);
+ expect(await h.deps.queueSteerOperationStore.read(h.request.sessionId)).toBeNull();
+ expect(await h.doc.getMessageQueue()).toEqual(h.rows);
+ expect(await h.doc.sessionData.history.readAll()).toEqual([]);
+ expect(h.runtime.userTurnId).toBe('user:active');
+ expect(h.runtime.promptInFlight).toBe(true);
+ // Positive control traverses the same real RPC client/server and execution service.
+ projectVisible = true;
+ machineVisible = true;
+ plane = 'cloud';
+ h.steerPrompt.mockImplementation(() => ({
+ applied: Promise.resolve({ release: () => {} }),
+ completion: Promise.resolve(),
+ }));
+ expect(await facade.requestSessionQueueSteer(machineId, h.request)).toMatchObject({
+ accepted: true,
});
- let projectVisible = false;
- let plane: 'local' | 'cloud' = scenario === 'private-project' ? 'cloud' : 'local';
- const getMachineRpcClient = vi.fn(async () => client);
- const facade = createWorkspaceMachineRpcFacade({
- workspaceId: h.deps.workspaceId,
- targetRouter: {
- getPlaneForMachine: () => plane,
- resolvePlaneForMachine: async () => plane,
- },
- getMachineProtocolCapabilities: async () => CURRENT_MACHINE_PROTOCOL_CAPABILITIES,
- getSessionMeta: async () => h.doc.getMetaState(),
- getSessionControlAuthorization: () => ({
- visibleMachineIds: new Set([machineId]),
- visibleLocalProjectKeys: new Set(projectVisible ? [machineId + ':private-P'] : []),
- currentUserId: 'user-U',
- }),
- getMachineRpcClient,
+ expect(appended.length).toBeGreaterThan(0);
+ expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(['A', 'B']);
+ expect(h.runtime.userTurnId).toBe('user:C');
+ expect(await h.deps.queueSteerOperationStore.read(h.request.sessionId)).toMatchObject({
+ phase: 'applied',
});
- await server.start();
- try {
- const error =
- scenario === 'private-project'
- ? 'Source authorization for this session is unavailable or denied.'
- : 'Local queue control is unavailable.';
- expect(await facade.requestSessionQueueSteer(machineId, h.request)).toMatchObject({
- accepted: false,
- error,
- });
- expect(
- await facade.requestSessionQueueMutation(machineId, {
- sessionId: h.request.sessionId,
- mutation: {
- kind: 'remove',
- queueItemId: h.request.queueItemId,
- expectedRevision: queueItemRevision(h.rows[2]),
- },
- })
- ).toMatchObject({ success: false, error });
- expect(getMachineRpcClient).not.toHaveBeenCalled();
- expect(appended).toEqual([]);
- expect(await h.deps.queueSteerOperationStore.read(h.request.sessionId)).toBeNull();
- expect(await h.doc.getMessageQueue()).toEqual(h.rows);
- expect(await h.doc.sessionData.history.readAll()).toEqual([]);
- expect(h.runtime.userTurnId).toBe('user:active');
- expect(h.runtime.promptInFlight).toBe(true);
- // Positive control traverses the same real RPC client/server and execution service.
- projectVisible = true;
- plane = 'cloud';
- h.steerPrompt.mockImplementation(() => ({
- applied: Promise.resolve({ release: () => {} }),
- completion: Promise.resolve(),
- }));
- expect(await facade.requestSessionQueueSteer(machineId, h.request)).toMatchObject({
- accepted: true,
- });
- expect(appended.length).toBeGreaterThan(0);
- expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(['A', 'B']);
- expect(h.runtime.userTurnId).toBe('user:C');
- expect(await h.deps.queueSteerOperationStore.read(h.request.sessionId)).toMatchObject({
- phase: 'applied',
- });
- const secondRow = h.rows[1];
- if (!secondRow) throw new Error('Missing B fixture');
- expect(
- await facade.requestSessionQueueMutation(machineId, {
- sessionId: h.request.sessionId,
- mutation: {
- kind: 'remove',
- queueItemId: secondRow.$cid,
- expectedRevision: queueItemRevision(secondRow),
- },
- })
- ).toMatchObject({ success: true });
- expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(['A']);
- } finally {
- client.stop();
- server.stop();
- }
+ const secondRow = h.rows[1];
+ if (!secondRow) throw new Error('Missing B fixture');
+ expect(
+ await facade.requestSessionQueueMutation(machineId, {
+ sessionId: h.request.sessionId,
+ mutation: {
+ kind: 'remove',
+ queueItemId: secondRow.$cid,
+ expectedRevision: queueItemRevision(secondRow),
+ },
+ })
+ ).toMatchObject({ success: true });
+ expect((await h.doc.getMessageQueue()).map((row) => row.task)).toEqual(['A']);
+ } finally {
+ client.stop();
+ server.stop();
}
- );
+ });
it.each(['update', 'remove', 'reorder'] as const)(
'rejects a stale second-client %s after reservation, with removal durable before submission',
diff --git a/packages/components/src/providers/AGENTS.md b/packages/components/src/providers/AGENTS.md
index e05454a43..236c9890c 100644
--- a/packages/components/src/providers/AGENTS.md
+++ b/packages/components/src/providers/AGENTS.md
@@ -56,9 +56,9 @@ and update only decision fields through HistoryWriter; never replace a rendered
- Queue edit/remove/reorder on queueItemSteer v2 use the narrow daemon domain RPC,
with revision checks against reservation ownership. Never direct-write after RPC failure.
Enqueue and other user writes retain their renderer authority.
-- Remote queue Steer and mutation share source-side session visibility authorization:
- verify target metadata against authenticated machine/project visibility and current user.
- Missing metadata or incomplete snapshots fail closed; machine access alone is insufficient.
+- Remote queue Steer and mutation share source-side control authorization, not UI visibility:
+ require target machine access and, for local-project sessions, matching project access.
+ Session authorship never grants control. Missing metadata or incomplete snapshots fail closed.
- Repo storage, durable Streams cursors, and eager-sync high-water state must use the
same per-renderer cache namespace. A checkpoint must never be shared by independently
persisted Repo views.
diff --git a/packages/components/src/providers/runtime-provider.tsx b/packages/components/src/providers/runtime-provider.tsx
index 687603f0f..554ea2912 100644
--- a/packages/components/src/providers/runtime-provider.tsx
+++ b/packages/components/src/providers/runtime-provider.tsx
@@ -110,7 +110,6 @@ export function RuntimeProvider({ children }: { children: ReactNode }) {
authorization: {
visibleMachineIds: new Set(visibleMachineIndex.convexAuthorizedMachineIds),
visibleLocalProjectKeys: new Set(visibleProjectIndex.accessByProjectKey.keys()),
- currentUserId,
},
};
const authorizedMachineIdsRef = useRef<{
diff --git a/packages/components/src/providers/session-control-authorization.ts b/packages/components/src/providers/session-control-authorization.ts
index 5538ff145..d2dfea88c 100644
--- a/packages/components/src/providers/session-control-authorization.ts
+++ b/packages/components/src/providers/session-control-authorization.ts
@@ -1,14 +1,15 @@
-import type { MachineId, SessionId } from '@lody/shared';
-import { isSessionVisibleToUser, type SessionMachineRecord } from '../lib/session-visibility';
+import type { MachineId, SessionId, SessionMeta } from '@lody/shared';
+import { getLocalProjectVisibilityKey } from '../lib/visible-local-project-index';
export type SessionControlAuthorization = {
visibleMachineIds: ReadonlySet;
visibleLocalProjectKeys: ReadonlySet;
- currentUserId?: string;
};
export type SessionControlAuthorizationDeps = {
- getSessionMeta?: (sessionId: SessionId) => Promise;
+ getSessionMeta?: (
+ sessionId: SessionId
+ ) => Promise | undefined>;
/** Null until the authenticated machine and project snapshots are both ready. */
getSessionControlAuthorization?: () => SessionControlAuthorization | null;
};
@@ -20,11 +21,16 @@ export async function authorizeSessionControl(
): Promise