Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(agent-island): 操作前校验完成卡并保留归档确认

Dash645bbec04b5d
diff --git a/apps/desktop/native/agent-island/macos-agent-island-helper.swift b/apps/desktop/native/agent-island/macos-agent-island-helper.swift
index 8b9df19cf9..53e2af22b8 100644
--- a/apps/desktop/native/agent-island/macos-agent-island-helper.swift
+++ b/apps/desktop/native/agent-island/macos-agent-island-helper.swift
@@ -1377,6 +1377,7 @@ struct AgentIslandCompanion: Codable, Equatable {
struct AgentIslandSession: Codable, Equatable, Identifiable {
let sessionId: String
+ var completionToken: String? = nil
let title: String
// Older main-process payloads have no companion field.
var companion: AgentIslandCompanion? = nil
@@ -3336,7 +3337,7 @@ struct ExpandedSessionsView: View {
},
onPermissionAction: emitPermissionAction,
onCompletionAction: { action, requestId in
- eventSink(["type": "completion-action", "sessionId": current.sessionId, "action": action, "requestId": requestId])
+ eventSink(["type": "completion-action", "sessionId": current.sessionId, "action": action, "requestId": requestId, "completionToken": current.completionToken ?? ""])
}
)
.equatable()
@@ -3379,7 +3380,7 @@ struct ExpandedSessionsView: View {
},
onPermissionAction: emitPermissionAction,
onCompletionAction: { action, requestId in
- eventSink(["type": "completion-action", "sessionId": session.sessionId, "action": action, "requestId": requestId])
+ eventSink(["type": "completion-action", "sessionId": session.sessionId, "action": action, "requestId": requestId, "completionToken": session.completionToken ?? ""])
}
)
.equatable()
@@ -3418,12 +3419,12 @@ struct ExpandedSessionRow: View, Equatable {
}
var body: some View {
- if session.phase == "completed" {
+ if session.phase == "completed", let completionToken = session.completionToken {
CompletedSessionSwipeRow(strings: strings, canArchive: session.companion == nil,
onFocus: onFocus, onAction: onCompletionAction) {
card
}
- .id("\(session.sessionId):\(session.lastActivityAt)")
+ .id("\(session.sessionId):\(completionToken)")
} else {
card
}
diff --git a/apps/desktop/src/main/agent-island/MacAgentIslandNativeHost.ts b/apps/desktop/src/main/agent-island/MacAgentIslandNativeHost.ts
index 4a4fdcb849..6d6fbcca47 100644
--- a/apps/desktop/src/main/agent-island/MacAgentIslandNativeHost.ts
+++ b/apps/desktop/src/main/agent-island/MacAgentIslandNativeHost.ts
@@ -70,7 +70,7 @@ interface MacAgentIslandNativeHostOptions {
onExpand: (displayId?: number | null) => void;
onCollapse: (displayId?: number | null) => void;
onFocusSession: (sessionId: string) => void;
- onCompletionAction?: (sessionId: string, action: 'mark-read' | 'archive') => Promise<boolean>;
+ onCompletionAction?: (sessionId: string, action: 'mark-read' | 'archive', completionToken: string) => Promise<boolean>;
onOpenSettings: () => void;
onNewMessage: () => void;
onToggleSound: () => void;
@@ -122,6 +122,7 @@ type NativePayload = {
panel?: unknown;
sessionId?: unknown;
requestId?: unknown;
+ completionToken?: unknown;
action?: unknown;
active?: unknown;
centerXRatio?: unknown;
@@ -515,8 +516,9 @@ export class MacAgentIslandNativeHost {
payload.type === 'completion-action' && this.child === child
&& typeof payload.sessionId === 'string' && payload.sessionId.length > 0
&& (payload.action === 'mark-read' || payload.action === 'archive')
+ && typeof payload.completionToken === 'string' && payload.completionToken.length > 0 && payload.completionToken.length <= 128
) {
- const { sessionId, action, requestId } = payload;
+ const { sessionId, action, requestId, completionToken } = payload;
const reply = (success: boolean): void => {
if (this.child !== child || typeof requestId !== 'string') return;
try {
@@ -526,7 +528,7 @@ export class MacAgentIslandNativeHost {
}
};
void Promise.resolve()
- .then(() => this.options.onCompletionAction?.(sessionId, action) ?? false)
+ .then(() => this.options.onCompletionAction?.(sessionId, action, completionToken) ?? false)
.then(reply, () => reply(false));
return;
}
diff --git a/apps/desktop/src/main/agent-island/__tests__/MacAgentIslandNativeHost.test.ts b/apps/desktop/src/main/agent-island/__tests__/MacAgentIslandNativeHost.test.ts
index e575e86197..7dcb7f6324 100644
--- a/apps/desktop/src/main/agent-island/__tests__/MacAgentIslandNativeHost.test.ts
+++ b/apps/desktop/src/main/agent-island/__tests__/MacAgentIslandNativeHost.test.ts
@@ -228,10 +228,10 @@ describe('MacAgentIslandNativeHost', () => {
host.publish(createDisplayState(), createFrame());
await vi.advanceTimersByTimeAsync(0);
for (const action of ['mark-read', 'archive', 'delete']) {
- (child.stdout as PassThrough).write(`${JSON.stringify({ type: 'completion-action', sessionId: 's1', action, requestId: action })}\n`);
+ (child.stdout as PassThrough).write(`${JSON.stringify({ type: 'completion-action', sessionId: 's1', action, requestId: action, completionToken: 'card-1' })}\n`);
}
await vi.advanceTimersByTimeAsync(0);
- expect(options.onCompletionAction.mock.calls).toEqual([['s1', 'mark-read'], ['s1', 'archive']]);
+ expect(options.onCompletionAction.mock.calls).toEqual([['s1', 'mark-read', 'card-1'], ['s1', 'archive', 'card-1']]);
expect(replies.map(line => JSON.parse(line)).filter(message => message.type === 'completion-action-result')).toEqual([
{ type: 'completion-action-result', requestId: 'mark-read', success: true },
{ type: 'completion-action-result', requestId: 'archive', success: false },
diff --git a/apps/desktop/src/main/agent-island/__tests__/archiveConfirmation.test.ts b/apps/desktop/src/main/agent-island/__tests__/archiveConfirmation.test.ts
new file mode 100644
index 0000000000..ab6aecdd8f
--- /dev/null
+++ b/apps/desktop/src/main/agent-island/__tests__/archiveConfirmation.test.ts
@@ -0,0 +1,71 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { confirmIslandArchive } from '../archiveConfirmation.js';
+
+const h = vi.hoisted(() => ({ preview: vi.fn(), list: vi.fn(), invoke: vi.fn(), confirm: vi.fn() }));
+vi.mock('electron', () => ({ dialog: { showMessageBox: h.confirm } }));
+vi.mock('../../i18n.js', () => ({ t: (key: string) =>
+ key.endsWith('scheduleName') ? '「{{name}}」' : key.includes('scheduleWarning') ? 'scheduleWarning {{names}}' : key,
+}));
+vi.mock('../../worktree/WorktreeManager.js', () => ({ getRemovalPreview: h.preview }));
+vi.mock('../../scheduler-host/index.js', () => ({ getScheduleStorageIfInitialized: () => ({ list: h.list }) }));
+vi.mock('../../device-link/index.js', () => ({ remoteInvoke: h.invoke }));
+
+// Production archive preflight entry. Existing renderer preflight tests cannot
+// protect a native main-process entry from bypassing dirty/schedule confirmation.
+describe('island archive confirmation (unit)', () => {
+ beforeEach(() => {
+ h.preview.mockReset().mockResolvedValue({ hasWorktree: false, dirty: false });
+ h.list.mockReset().mockResolvedValue([]);
+ h.invoke.mockReset();
+ h.confirm.mockReset().mockResolvedValue({ response: 1 });
+ });
+ afterEach(() => vi.useRealTimers());
+
+ it('archives a clean ordinary task without prompting', async () => {
+ h.list.mockResolvedValue([
+ { targetSessionId: 's1', status: 'paused', name: 'paused' },
+ { targetSessionId: 's1', status: 'active', persistentSession: true, name: 'persistent' },
+ ]);
+ expect(await confirmIslandArchive('s1', null)).toBe(true);
+ expect(h.preview).toHaveBeenCalledWith('s1');
+ expect(h.confirm).not.toHaveBeenCalled();
+ });
+
+ it('shows dirty worktree and bound automation warnings before accepting', async () => {
+ h.preview.mockResolvedValue({ hasWorktree: true, dirty: true });
+ h.list.mockResolvedValue([{ targetSessionId: 's1', status: 'active', name: 'Nightly' }]);
+ h.confirm.mockResolvedValue({ response: 0 });
+ expect(await confirmIslandArchive('s1', null)).toBe(true);
+ expect(h.confirm).toHaveBeenCalledWith(expect.objectContaining({
+ detail: expect.stringContaining('dirtyWorktreeWarning'), defaultId: 1, cancelId: 1,
+ }));
+ expect(h.confirm.mock.calls[0][0].detail).toContain('Nightly');
+ });
+
+ it('treats an unknown worktree as requiring confirmation and preserves cancellation', async () => {
+ h.preview.mockRejectedValue(new Error('unavailable'));
+ expect(await confirmIslandArchive('s1', null)).toBe(false);
+ expect(h.confirm).toHaveBeenCalledOnce();
+ });
+
+ it('reads preflights from the task owner and presents the confirmation locally', async () => {
+ h.invoke.mockImplementation(async (_device, channel) => ({ ok: true,
+ result: channel === 'worktree:removal-preview' ? { hasWorktree: false, dirty: false }
+ : [{ targetSessionId: 's1', status: 'active', name: 'Remote nightly' }],
+ }));
+ expect(await confirmIslandArchive('s1', 'studio')).toBe(false);
+ expect(h.invoke).toHaveBeenCalledWith('studio', 'worktree:removal-preview', ['s1']);
+ expect(h.confirm.mock.calls[0][0].detail).toContain('Remote nightly');
+ expect(h.preview).not.toHaveBeenCalled();
+ expect(h.list).not.toHaveBeenCalled();
+ });
+
+ it('bounds a cold schedule read to 1500ms without blocking a clean task', async () => {
+ vi.useFakeTimers();
+ h.list.mockReturnValue(new Promise(() => {}));
+ const pending = confirmIslandArchive('s1', null);
+ await vi.advanceTimersByTimeAsync(1500);
+ expect(await pending).toBe(true);
+ expect(h.confirm).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/desktop/src/main/agent-island/__tests__/service.test.ts b/apps/desktop/src/main/agent-island/__tests__/service.test.ts
index 5fad32d9ed..23592dc075 100644
--- a/apps/desktop/src/main/agent-island/__tests__/service.test.ts
+++ b/apps/desktop/src/main/agent-island/__tests__/service.test.ts
@@ -22,6 +22,7 @@ import {
DEFAULT_AGENT_ISLAND_SOUND_SETTINGS,
computeAgentIslandContentHeight,
type AgentIslandDisplayState,
+ type AgentIslandSessionActivity,
type AgentIslandSoundChoice,
type AgentIslandSoundSettings,
} from '../../../shared/agentIsland.js';
@@ -56,6 +57,8 @@ function handleInteractionRequestForTest(
}
const mocks = vi.hoisted(() => ({
+ attached: vi.fn(),
+ confirmIslandArchive: vi.fn(),
patchSessionMetaInDb: vi.fn(),
remoteInvoke: vi.fn(),
getSessionRowSnapshot: vi.fn<() => Promise<{
@@ -145,6 +148,8 @@ vi.mock('../../localDb/ipc/sessions.js', () => ({
}));
vi.mock('../../device-link/index.js', () => ({ remoteInvoke: mocks.remoteInvoke }));
+vi.mock('../archiveConfirmation.js', () => ({ confirmIslandArchive: mocks.confirmIslandArchive }));
+vi.mock('../../im/binding.js', () => ({ bindingStore: { findByTarget: mocks.attached } }));
vi.mock('../companionIdentity.js', async (importOriginal) => ({
...(await importOriginal<typeof import('../companionIdentity.js')>()),
@@ -167,6 +172,8 @@ vi.mock('../../device-link/broadcast-tap.js', () => ({
import { resetEpermGuidanceForTest } from '../../file-access/permissions.js';
beforeEach(() => {
+ mocks.attached.mockReset().mockReturnValue(null);
+ mocks.confirmIslandArchive.mockReset().mockResolvedValue(true);
mocks.patchSessionMetaInDb.mockReset();
mocks.remoteInvoke.mockReset();
setDeepLinkMainWindow(null);
@@ -630,20 +637,24 @@ describe('AgentIslandService native publishing', () => {
service.setEnabled(false);
const meta = { sessionId: 'swipe-task', agentKind: 'codex' as const };
service.handleUserPrompt(meta, 'run');
- await service.handleCompletionAction(meta.sessionId, 'archive');
+ await service.handleCompletionAction(meta.sessionId, 'archive', 'missing');
expect(mocks.patchSessionMetaInDb).not.toHaveBeenCalled();
service.handleAgentEvent(meta, doneEvent());
+ const token = (service.getSessionActivitySnapshot(meta.sessionId) as AgentIslandSessionActivity).completionToken!;
mocks.patchSessionMetaInDb.mockRejectedValueOnce(new Error('offline'));
- await service.handleCompletionAction(meta.sessionId, 'archive');
+ await service.handleCompletionAction(meta.sessionId, 'archive', token);
expect(service.getSessionActivitySnapshot(meta.sessionId)).toMatchObject({ attention: true });
expect(mocks.showMessageBox).toHaveBeenCalled();
mocks.patchSessionMetaInDb.mockResolvedValueOnce({ status: 'archived' });
- await service.handleCompletionAction(meta.sessionId, 'archive');
- expect(mocks.patchSessionMetaInDb).toHaveBeenLastCalledWith(meta.sessionId, { status: 'archived' });
+ await service.handleCompletionAction(meta.sessionId, 'archive', token);
+ expect(mocks.patchSessionMetaInDb).toHaveBeenLastCalledWith(meta.sessionId, { status: 'archived' }, {
+ routeLockHeld: true, beforeWrite: expect.any(Function),
+ });
expect(service.getSessionActivitySnapshot(meta.sessionId)?.attention ?? false).toBe(false);
service.handleUserPrompt(meta, 'again');
service.handleAgentEvent(meta, doneEvent());
- await service.handleCompletionAction(meta.sessionId, 'mark-read');
+ const nextToken = (service.getSessionActivitySnapshot(meta.sessionId) as AgentIslandSessionActivity).completionToken!;
+ await service.handleCompletionAction(meta.sessionId, 'mark-read', nextToken);
expect(service.getSessionActivitySnapshot(meta.sessionId)?.attention ?? false).toBe(false);
expect(mocks.patchSessionMetaInDb).toHaveBeenCalledTimes(2);
service.resetRuntimeState();
@@ -658,6 +669,7 @@ describe('AgentIslandService native publishing', () => {
});
syncEnabledForTest(service, publish);
const input = { sessionId: 'remote-swipe', deviceId: 'owner-device', deviceName: 'Mac',
+ completionToken: 'owner-completion',
title: 'Task', workingDir: null, workspaceKind: null, agentKind: 'codex', detail: '' };
const complete = () => {
service.setDeviceSessions([{ ...input, phase: 'running' }]);
@@ -665,23 +677,79 @@ describe('AgentIslandService native publishing', () => {
};
complete();
mocks.remoteInvoke.mockResolvedValueOnce({ ok: false, error: { message: 'offline' } });
- await service.handleCompletionAction(input.sessionId, 'mark-read');
+ await service.handleCompletionAction(input.sessionId, 'mark-read', input.completionToken);
expect(publish.mock.calls.at(-1)?.[0].sessions).toContainEqual(expect.objectContaining({ sessionId: input.sessionId, attention: true }));
- mocks.remoteInvoke.mockResolvedValue({ ok: true });
- await service.handleCompletionAction(input.sessionId, 'mark-read');
- expect(mocks.remoteInvoke).toHaveBeenLastCalledWith('owner-device', 'notification:clear-session-attention', ['remote-swipe', 'explicit']);
+ mocks.remoteInvoke.mockResolvedValue({ ok: true, result: true });
+ await service.handleCompletionAction(input.sessionId, 'mark-read', input.completionToken);
+ expect(mocks.remoteInvoke).toHaveBeenLastCalledWith('owner-device', 'agent-island:completion-action', ['remote-swipe', 'mark-read', input.completionToken]);
expect(publish.mock.calls.at(-1)?.[0].sessions.some(s => s.sessionId === input.sessionId && s.attention)).toBe(false);
complete();
- await service.handleCompletionAction(input.sessionId, 'archive');
- expect(mocks.remoteInvoke).toHaveBeenLastCalledWith('owner-device', 'local-db:sessions:patch-meta', ['remote-swipe', { status: 'archived' }]);
+ await service.handleCompletionAction(input.sessionId, 'archive', input.completionToken);
+ expect(mocks.remoteInvoke).toHaveBeenLastCalledWith('owner-device', 'agent-island:completion-action', ['remote-swipe', 'archive', input.completionToken]);
const count = mocks.remoteInvoke.mock.calls.length;
service.setDeviceSessions([{ ...input, phase: 'completed', companion: { name: 'Teammate', avatar: '', avatarColor: 'teal' } }]);
- await service.handleCompletionAction(input.sessionId, 'archive');
+ await service.handleCompletionAction(input.sessionId, 'archive', input.completionToken);
expect(mocks.remoteInvoke).toHaveBeenCalledTimes(count);
expect(mocks.patchSessionMetaInDb).not.toHaveBeenCalled();
service.resetRuntimeState();
});
+ // Owner handler + existing send lock: stale network/queue deliveries must not
+ // archive or acknowledge the next completion, even in the same millisecond.
+ it.each(['mark-read', 'archive'] as const)('rejects an old %s on the owning device after its route wait', async action => {
+ const { AgentIslandService } = await import('../service.js');
+ const { setSessionRouteLockImplementation } = await import('../../localDb/sessionRouteLock.js');
+ const service = new AgentIslandService({ getMainWindow: () => null });
+ service.setEnabled(false);
+ service.registerDeviceSessionIpc();
+ const meta = { sessionId: 'owner-race', agentKind: 'codex' as const };
+ const complete = () => { service.handleUserPrompt(meta, 'run'); service.handleAgentEvent(meta, doneEvent()); };
+ complete();
+ const token = (service.getSessionActivitySnapshot(meta.sessionId) as AgentIslandSessionActivity).completionToken!;
+ let release!: () => void;
+ const blocked = new Promise<void>(resolve => { release = resolve; });
+ setSessionRouteLockImplementation(async (_id, task) => { await blocked; return task(); });
+ try {
+ const actionPromise = registeredIpcHandler('agent-island:completion-action')(null, meta.sessionId, action, token);
+ complete();
+ release();
+ expect(await actionPromise).toBe(false);
+ expect(mocks.patchSessionMetaInDb).not.toHaveBeenCalled();
+ expect(service.getSessionActivitySnapshot(meta.sessionId)).toMatchObject({ attention: true });
+ expect((service.getSessionActivitySnapshot(meta.sessionId) as AgentIslandSessionActivity).completionToken).not.toBe(token);
+ } finally {
+ setSessionRouteLockImplementation(null);
+ service.resetRuntimeState();
+ }
+ });
+
+ it('keeps a cancelled archive and rechecks its card after confirmation and worktree waits', async () => {
+ const { AgentIslandService } = await import('../service.js');
+ const service = new AgentIslandService({ getMainWindow: () => null });
+ service.setEnabled(false);
+ const meta = { sessionId: 'archive-wait', agentKind: 'codex' as const };
+ const complete = () => { service.handleUserPrompt(meta, 'run'); service.handleAgentEvent(meta, doneEvent()); };
+ complete();
+ const token = () => (service.getSessionActivitySnapshot(meta.sessionId) as AgentIslandSessionActivity).completionToken!;
+ mocks.confirmIslandArchive.mockResolvedValueOnce(false);
+ expect(await service.handleCompletionAction(meta.sessionId, 'archive', token())).toBe(false);
+ expect(mocks.patchSessionMetaInDb).not.toHaveBeenCalled();
+ mocks.confirmIslandArchive.mockImplementationOnce(async () => { complete(); return true; });
+ expect(await service.handleCompletionAction(meta.sessionId, 'archive', token())).toBe(false);
+ expect(mocks.patchSessionMetaInDb).not.toHaveBeenCalled();
+ mocks.attached.mockReturnValueOnce({ channel: 'feishu' });
+ expect(await service.handleCompletionAction(meta.sessionId, 'archive', token())).toBe(false);
+ expect(mocks.patchSessionMetaInDb).not.toHaveBeenCalled();
+ mocks.patchSessionMetaInDb.mockImplementationOnce(async (_id, _patch, options) => {
+ complete();
+ options.beforeWrite();
+ throw new Error('unreachable');
+ });
+ expect(await service.handleCompletionAction(meta.sessionId, 'archive', token())).toBe(false);
+ expect(service.getSessionActivitySnapshot(meta.sessionId)).toMatchObject({ attention: true });
+ service.resetRuntimeState();
+ });
+
it('keeps compact activity broadcasting alive in headless mode', async () => {
const { AgentIslandService } = await import('../service.js');
const service = new AgentIslandService({
diff --git a/apps/desktop/src/main/agent-island/archiveConfirmation.ts b/apps/desktop/src/main/agent-island/archiveConfirmation.ts
new file mode 100644
index 0000000000..f04fc68cbb
--- /dev/null
+++ b/apps/desktop/src/main/agent-island/archiveConfirmation.ts
@@ -0,0 +1,47 @@
+import { dialog } from 'electron';
+import type { Schedule } from '@cindy/maker-scheduler';
+import { t } from '../i18n.js';
+import { remoteInvoke } from '../device-link/index.js';
+import { getRemovalPreview } from '../worktree/WorktreeManager.js';
+import { getScheduleStorageIfInitialized } from '../scheduler-host/index.js';
+
+/** Match desktop archive preflights, with the confirmation on the initiating computer. */
+export async function confirmIslandArchive(sessionId: string, deviceId: string | null): Promise<boolean> {
+ const preview = (async () => {
+ if (deviceId) {
+ const result = await remoteInvoke(deviceId, 'worktree:removal-preview', [sessionId]);
+ if (!result.ok) throw new Error(result.error.message);
+ return result.result as { hasWorktree: boolean; dirty: boolean };
+ }
+ return getRemovalPreview(sessionId);
+ })().then(value => value && typeof value.hasWorktree === 'boolean' && typeof value.dirty === 'boolean' ? value : null)
+ .catch(() => null);
+ let timeout: ReturnType<typeof setTimeout> | undefined;
+ const schedules = Promise.race([
+ (async () => {
+ if (deviceId) {
+ const result = await remoteInvoke(deviceId, 'maker:schedule:list', [null, { sessionBindings: true }]);
+ return result.ok && Array.isArray(result.result) ? result.result as Schedule[] : [];
+ }
+ return await getScheduleStorageIfInitialized()?.list({ status: 'active' }) ?? [];
+ })().catch(() => [] as Schedule[]),
+ new Promise<Schedule[]>(resolve => { timeout = setTimeout(() => resolve([]), 1500); }),
+ ]).finally(() => clearTimeout(timeout));
+ const [worktree, list] = await Promise.all([preview, schedules]);
+ const names = list.filter(s => s.targetSessionId === sessionId && s.status === 'active' && !s.persistentSession)
+ .map(s => s.name);
+ if (worktree && !(worktree.hasWorktree && worktree.dirty) && names.length === 0) return true;
+ const warning = names.length > 0
+ ? t(`ccAgent.sidebar.confirmArchive.scheduleWarning_${names.length === 1 ? 'one' : 'other'}`)
+ .replaceAll('{{names}}', names.map(name => t('ccAgent.sidebar.confirmArchive.scheduleName').replaceAll('{{name}}', name))
+ .join(t('ccAgent.sidebar.confirmArchive.scheduleNameSeparator')))
+ : '';
+ const result = await dialog.showMessageBox({
+ type: 'question', message: t('ccAgent.sidebar.confirmArchive.title'),
+ detail: [t('ccAgent.sidebar.confirmArchive.description'),
+ worktree?.dirty ? t('ccAgent.sidebar.confirmArchive.dirtyWorktreeWarning') : '', warning].filter(Boolean).join(' '),
+ buttons: [t('ccAgent.sidebar.confirmArchive.confirm'), t('ccAgent.sidebar.confirmArchive.cancel')],
+ defaultId: 1, cancelId: 1,
+ });
+ return result.response === 0;
+}
diff --git a/apps/desktop/src/main/agent-island/service.ts b/apps/desktop/src/main/agent-island/service.ts
index d8cae6b92b..2df4e2101a 100644
--- a/apps/desktop/src/main/agent-island/service.ts
+++ b/apps/desktop/src/main/agent-island/service.ts
@@ -76,6 +76,10 @@ import {
type AgentIslandScreenLayoutMetrics,
} from '../../shared/agentIsland.js';
import { getSessionRowSnapshot, patchSessionMetaInDb } from '../localDb/ipc/sessions.js';
+import { withSessionRouteLock } from '../localDb/sessionRouteLock.js';
+import { confirmIslandArchive } from './archiveConfirmation.js';
+import { remoteInvoke } from '../device-link/index.js';
+import { bindingStore } from '../im/binding.js';
import { setAgentIslandCompanionChangeSink } from '../localDb/agentIslandSessionPatch.js';
import {
companionAvatarHasArtwork,
@@ -89,6 +93,7 @@ import { t } from '../i18n.js';
import { isAppContentWindow, isFocusedAppContentWindow } from '../windowFocusClassifier.js';
import {
acknowledgeAgentIslandSessionRead,
+ agentIslandCompletionToken,
readAgentIslandUnreadTerminalStamp,
applyAgentIslandEvent,
applyAgentIslandInteractionDismissed,
@@ -276,6 +281,7 @@ function sessionActivitySnapshotsEqual(
right: AgentIslandSessionActivity,
): boolean {
return left.sessionId === right.sessionId
+ && left.completionToken === right.completionToken
&& left.workingPhase === right.workingPhase
&& left.phase === right.phase
&& left.currentTurnActive === right.currentTurnActive
@@ -423,7 +429,7 @@ export class AgentIslandService {
onExpand: (displayId) => this.handleNativeExpand(displayId),
onCollapse: () => this.handleNativeCollapse(),
onFocusSession: (sessionId) => this.focusSession(sessionId),
- onCompletionAction: (sessionId, action) => this.handleCompletionAction(sessionId, action),
+ onCompletionAction: (sessionId, action, token) => this.handleCompletionAction(sessionId, action, token),
onOpenSettings: () => this.dispatchMainWindowCommand('open-agent-island-settings', { playSelectSound: true }),
onNewMessage: () => this.dispatchMainWindowCommand('new-maker', { playSelectSound: true }),
onToggleSound: () => this.dispatchMainWindowCommand('toggle-agent-island-sound'),
@@ -542,6 +548,13 @@ export class AgentIslandService {
/** 各平台都注册(含无原生岛的 headless):灵动岛关闭时远程任务靠它发桌面通知。 */
registerDeviceSessionIpc(): void {
+ ipcMain.handle('agent-island:completion-action', (_event, sessionId: unknown, action: unknown, token: unknown) => {
+ if (typeof sessionId !== 'string' || !sessionId || (action !== 'archive' && action !== 'mark-read')
+ || typeof token !== 'string' || !token || token.length > 128) {
+ throwIpcError('INVALID_PARAMS', 'Invalid completion action');
+ }
+ return this.applyOwnedCompletionAction(sessionId, action, token);
+ });
ipcMain.handle(AGENT_ISLAND_SET_REMOTE_SESSIONS_CHANNEL, (event, raw: unknown) => {
assertTrustedAppRendererEvent(event);
// 只认主窗:副窗也挂侧栏,多份输入会让跃迁判定来回抖动。
@@ -1758,6 +1771,7 @@ export class AgentIslandService {
*/
private buildSessionActivityPayload(): AgentIslandSessionActivity[] {
return buildAllSessionActivitySnapshots(this.state).map((s) => ({
+ ...(s.completionToken ? { completionToken: s.completionToken } : {}),
...(s.completionNotification ? { completionNotification: s.completionNotification } : {}),
...projectSessionActivity({
sessionId: s.sessionId,
@@ -2656,29 +2670,26 @@ export class AgentIslandService {
private readonly completionActionsPending = new Set<string>();
- async handleCompletionAction(sessionId: string, action: 'mark-read' | 'archive'): Promise<boolean> {
+ async handleCompletionAction(sessionId: string, action: 'mark-read' | 'archive', token: string): Promise<boolean> {
const session = this.state.sessions.get(sessionId);
- if (!session || session.phase !== 'completed' || this.completionActionsPending.has(sessionId)) return false;
+ if (!session || !token || agentIslandCompletionToken(session) !== token || this.completionActionsPending.has(sessionId)) return false;
// Companion main tasks have their own lifecycle; only their notification may be read here.
if (action === 'archive' && session.companion) return false;
- const generation = session.activityGeneration;
this.completionActionsPending.add(sessionId);
try {
+ if (action === 'archive' && !await confirmIslandArchive(sessionId, session.sourceDeviceId)) return false;
+ if (this.state.sessions.get(sessionId) !== session || agentIslandCompletionToken(session) !== token) return false;
if (session.sourceDeviceId) {
- const { remoteInvoke } = await import('../device-link/index.js');
- const result = await remoteInvoke(session.sourceDeviceId,
- action === 'archive' ? 'local-db:sessions:patch-meta' : 'notification:clear-session-attention',
- action === 'archive' ? [sessionId, { status: 'archived' }] : [sessionId, 'explicit']);
+ const result = await remoteInvoke(session.sourceDeviceId, 'agent-island:completion-action', [sessionId, action, token]);
if (!result.ok) throw new Error(result.error.message);
- } else if (action === 'archive') {
- await patchSessionMetaInDb(sessionId, { status: 'archived' });
+ if (result.result !== true) return false;
+ const current = this.state.sessions.get(sessionId);
+ if (current && (current !== session || agentIslandCompletionToken(current) !== token)) return false;
+ clearAppBadgeSessionAttention(sessionId, 'explicit');
+ this.handleSessionAttentionCleared(sessionId, 'explicit');
+ return true;
}
- const current = this.state.sessions.get(sessionId);
- if (current && (current !== session || current.activityGeneration !== generation)) return false;
- clearAppBadgeSessionAttention(sessionId, 'explicit');
- // Keep the local mirror in sync even when the remote push arrives later.
- this.handleSessionAttentionCleared(sessionId, 'explicit');
- return true;
+ return await this.applyOwnedCompletionAction(sessionId, action, token);
} catch (error) {
log.warn('island completion action failed', { action, error });
void dialog.showMessageBox({ type: 'error', message: t('agentIsland.native.actionFailed') });
@@ -2688,6 +2699,31 @@ export class AgentIslandService {
}
}
+ /** A tunneled action is never forwarded again or downgraded to an unguarded write. */
+ private async applyOwnedCompletionAction(sessionId: string, action: 'mark-read' | 'archive', token: string): Promise<boolean> {
+ return withSessionRouteLock(sessionId, async () => {
+ const session = this.state.sessions.get(sessionId);
+ const isCurrent = () => !!session && !session.sourceDeviceId
+ && this.state.sessions.get(sessionId) === session && agentIslandCompletionToken(session) === token
+ && (action !== 'archive' || !bindingStore.findByTarget(sessionId));
+ if (!isCurrent() || (action === 'archive' && session?.companion)) return false;
+ if (action === 'archive') {
+ await patchSessionMetaInDb(sessionId, { status: 'archived' }, {
+ routeLockHeld: true,
+ // The DB writer invokes this again after its worktree/resource waits.
+ beforeWrite: () => {
+ if (!isCurrent()) throwIpcError('PRECONDITION_FAILED', 'Completed card changed');
+ },
+ });
+ }
+ // Archiving may remove this projection. The route lock still excludes a new send.
+ if (this.state.sessions.has(sessionId) && !isCurrent()) return false;
+ clearAppBadgeSessionAttention(sessionId, 'explicit');
+ this.handleSessionAttentionCleared(sessionId, 'explicit');
+ return true;
+ });
+ }
+
/** 记下这次点击并取代之前的任何一次;被点的卡不是未读完成 / 报错时不留可处置记录。 */
private recordIslandEntryAlert(sessionId: string, now: number): string | null {
const stamp = readAgentIslandUnreadTerminalStamp(this.state, sessionId);
diff --git a/apps/desktop/src/main/agent-island/sessionActivityRelay.ts b/apps/desktop/src/main/agent-island/sessionActivityRelay.ts
index 90ed5a0d5a..ddcc5bc5e7 100644
--- a/apps/desktop/src/main/agent-island/sessionActivityRelay.ts
+++ b/apps/desktop/src/main/agent-island/sessionActivityRelay.ts
@@ -301,6 +301,7 @@ export class SessionActivityRelay {
function toSessionActivityPayload(activity: AgentIslandSessionActivity): SessionActivityPayload {
return {
+ ...(activity.completionToken ? { completionToken: activity.completionToken } : {}),
...(activity.completionNotification ? { completionNotification: activity.completionNotification } : {}),
sessionId: activity.sessionId,
phase: activity.phase,
@@ -334,6 +335,7 @@ function toTerminalActivityPayload(sessionId: string): SessionActivityPayload {
function activitySignature(payload: SessionActivityPayload): string {
return [
+ payload.completionToken ?? '',
payload.phase,
payload.completionNotification ?? '',
payload.compactDetail,
diff --git a/apps/desktop/src/main/agent-island/state.ts b/apps/desktop/src/main/agent-island/state.ts
index 7876c19dd4..e552ab03c7 100644
--- a/apps/desktop/src/main/agent-island/state.ts
+++ b/apps/desktop/src/main/agent-island/state.ts
@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
import { isSubagentParentToolUseId } from '@cindy/maker-shared/message-render';
import {
isCompactingWorkingStatus,
@@ -186,6 +187,15 @@ interface AgentIslandSessionState {
* {@link syncAgentIslandDeviceSessions} 的输入决定;本机 Maker 事件不会触达它。
*/
sourceDeviceId: string | null;
+ sourceCompletionToken?: string;
+}
+
+const completionTokenEpoch = randomUUID();
+
+export function agentIslandCompletionToken(session: AgentIslandSessionState): string | undefined {
+ if (session.phase !== 'completed') return undefined;
+ return session.sourceDeviceId ? session.sourceCompletionToken
+ : `${completionTokenEpoch}:${session.activityGeneration}`;
}
export interface AgentIslandUserPromptRollbackToken {
@@ -1211,10 +1221,12 @@ function applyDeviceSessionMeta(
const projectName = [project, input.deviceName].filter(Boolean).join(' · ') || null;
const agentKind = dbToMakerAgentKind(input.agentKind);
const changed = session.title !== input.title
+ || session.sourceCompletionToken !== input.completionToken
|| session.companion !== companion
|| session.projectName !== projectName
|| session.agentKind !== agentKind;
session.title = input.title;
+ session.sourceCompletionToken = input.completionToken;
session.companion = companion;
session.projectName = projectName;
session.agentKind = agentKind;
@@ -2647,10 +2659,12 @@ function applyMeta(session: AgentIslandSessionState, meta: AgentIslandSessionMet
function toSnapshot(session: AgentIslandSessionState): AgentIslandSessionSnapshot {
const reconnectStatus = session.phase === 'running' ? session.reconnectStatus : null;
+ const completionToken = agentIslandCompletionToken(session);
return {
...(session.phase === 'completed' && session.completionNotification ? { completionNotification: session.completionNotification } : {}),
sessionId: session.sessionId,
title: session.companion?.name || session.title || session.projectName || session.sessionId.slice(0, 8),
+ ...(completionToken ? { completionToken } : {}),
...(session.companion ? { companion: session.companion } : {}),
projectName: session.projectName,
detail: reconnectStatus ?? session.detail,
diff --git a/apps/desktop/src/main/localDb/ipc/__tests__/sessionsUpdate.test.ts b/apps/desktop/src/main/localDb/ipc/__tests__/sessionsUpdate.test.ts
index 363fabe300..2a11251d55 100644
--- a/apps/desktop/src/main/localDb/ipc/__tests__/sessionsUpdate.test.ts
+++ b/apps/desktop/src/main/localDb/ipc/__tests__/sessionsUpdate.test.ts
@@ -1194,6 +1194,19 @@ describe('local-db:sessions:update handler wiring', () => {
expect(h.closeSharedTask).toHaveBeenCalledWith('codex-local', h.client);
});
+ // Real status writer + SQLite: completion guards run inside resource locks and
+ // again after recycle preparation, before any lifecycle write (integration).
+ it('rejects a superseded completed card after worktree preparation without archiving it', async () => {
+ let current = true;
+ h.requestRecycle.mockImplementationOnce(async () => { current = false; });
+ await expect(patchSessionMetaInDb('codex-local', { status: 'archived' }, {
+ beforeWrite: () => { if (!current) throw new Error('card changed'); },
+ })).rejects.toThrow('[PRECONDITION_FAILED]');
+ expect(h.sqlite!.prepare('SELECT status FROM sessions WHERE id = ?').get('codex-local')).toEqual({ status: 'active' });
+ expect(h.runtimeCleanup).not.toHaveBeenCalled();
+ expect(h.prepareSharedTaskClosure).not.toHaveBeenCalled();
+ });
+
it('does not commit a terminal status when the shared-task journal cannot be prepared', async () => {
h.prepareSharedTaskClosure.mockRejectedValueOnce(new Error('disk failed'));
diff --git a/apps/desktop/src/main/localDb/ipc/sessions.ts b/apps/desktop/src/main/localDb/ipc/sessions.ts
index 0f307ba8ed..89e943e99e 100644
--- a/apps/desktop/src/main/localDb/ipc/sessions.ts
+++ b/apps/desktop/src/main/localDb/ipc/sessions.ts
@@ -211,13 +211,16 @@ async function withStatusWriteLock<T>(
status: unknown,
task: () => Promise<T>,
alreadyLocked = false,
+ beforeWrite?: () => void,
): Promise<T> {
const write = async () => {
const resources = status === undefined ? [] : await readSessionWorktreeResources(db, sessionId);
const physicalResources = await Promise.all(resources.map(physicalWorktreeKey));
const mutate = async () => {
+ beforeWrite?.();
if (status === 'archived' || status === 'deleted')
await requestWorktreeRecycle(sessionId, resources);
+ beforeWrite?.();
const result = await task();
for (const resource of physicalResources) notifyWorktreeRecycleOpportunity(resource);
return result;
@@ -2379,7 +2382,7 @@ export async function patchSessionMetaInDb(
title?: string;
pinnedAt?: string | null;
},
- options: { routeLockHeld?: boolean; signal?: AbortSignal } = {},
+ options: { routeLockHeld?: boolean; signal?: AbortSignal; beforeWrite?: () => void } = {},
): Promise<ReturnType<typeof sessionToCamel>> {
const ownerScope = captureOwnerScope();
for (const k of Object.keys(patch)) {
@@ -2407,15 +2410,18 @@ export async function patchSessionMetaInDb(
let deletedSideChats: SessionsSetTerminalStatusResult['deletedSideChats'] | undefined;
const updated = await withStatusWriteLock(db, sessionId, patch.status, async () => {
if (patch.status !== undefined) await assertGenericSessionLifecycleAllowed(db, sessionId);
+ options.beforeWrite?.();
const terminal = patch.status === 'archived' || patch.status === 'deleted';
if (terminal) {
if (typeof dbClient.tx === 'function') {
const { status: _status, ...nonTerminalPatch } = setObj;
await writeSessionPatch(db, sessionId, nonTerminalPatch, undefined);
+ options.beforeWrite?.();
deletedSideChats = await setTerminalSessionStatus(dbClient, sessionId, patch.status as 'archived' | 'deleted');
} else {
const prepared = await prepareSharedTaskClosure(sessionId, dbClient);
try {
+ options.beforeWrite?.();
await writeSessionPatch(db, sessionId, setObj, patch.status);
} catch (error) {
await rollbackSharedTaskClosure(dbClient, prepared);
@@ -2441,7 +2447,7 @@ export async function patchSessionMetaInDb(
await closeSharedTaskForTask(sessionId, dbClient);
}
return sessionToCamel(row);
- }, options.routeLockHeld);
+ }, options.routeLockHeld, options.beforeWrite);
if (updated.status === 'deleted' && isOwnerScopeCurrent(ownerScope)) {
clearSessionAttention(sessionId, 'explicit');
}
diff --git a/apps/desktop/src/renderer/features/device-link/__tests__/agentIslandRemoteSessions.test.ts b/apps/desktop/src/renderer/features/device-link/__tests__/agentIslandRemoteSessions.test.ts
index 246bf6ffff..5ad75ce383 100644
--- a/apps/desktop/src/renderer/features/device-link/__tests__/agentIslandRemoteSessions.test.ts
+++ b/apps/desktop/src/renderer/features/device-link/__tests__/agentIslandRemoteSessions.test.ts
@@ -4,7 +4,7 @@ import type { Session } from '@/lib/ccAgent.types';
import { buildAgentIslandRemoteSessionInputs } from '../agentIslandRemoteSessions';
import { applyRemoteSessionActivity, clearRemoteSessionActivity, getRemoteSessionActivity, type RemoteSessionActivity } from '../remoteSessionActivityStore';
import { parseAgentIslandRemoteSessions } from '../../../../shared/agentIsland';
-import { createAgentIslandState, syncAgentIslandDeviceSessions } from '../../../../main/agent-island/state';
+import { agentIslandCompletionToken, createAgentIslandState, syncAgentIslandDeviceSessions } from '../../../../main/agent-island/state';
import { SessionActivityRelay } from '../../../../main/agent-island/sessionActivityRelay';
import { MACHINE_ALL, MACHINE_LOCAL } from '../selectedMachineStore';
@@ -49,6 +49,31 @@ const readActivity = (sessionId: string): RemoteSessionActivity | undefined =>
activities.get(sessionId);
describe('buildAgentIslandRemoteSessionInputs', () => {
+ // Full production projection chain: a second completion with identical text
+ // must replace the owner token, while an old host must not gain swipe actions.
+ it('preserves completion identity through relay, store, parser and native projection', () => {
+ clearRemoteSessionActivity();
+ const state = createAgentIslandState();
+ const relay = new SessionActivityRelay(payload => {
+ applyRemoteSessionActivity('device-a', payload);
+ const inputs = buildAgentIslandRemoteSessionInputs([remoteSession('a-1', 'device-a')], MACHINE_ALL, getRemoteSessionActivity);
+ syncAgentIslandDeviceSessions(state, parseAgentIslandRemoteSessions(inputs)!, 2000);
+ }, { minIntervalMs: 0 });
+ const completion = { sessionId: 'a-1', phase: 'completed' as const, recordStatus: 'active',
+ compactDetail: 'Done', startedAtMs: 1, lastActivityAtMs: 1, currentActionSummary: 'Done',
+ attention: true, workflow: null, turnGeneration: null, gracefulStopState: 'none', source: 'live' } as const;
+ try {
+ relay.publish([{ ...completion, completionToken: 'owner:1' }]);
+ expect(agentIslandCompletionToken(state.sessions.get('a-1')!)).toBe('owner:1');
+ relay.publish([{ ...completion, completionToken: 'owner:2' }]);
+ expect(agentIslandCompletionToken(state.sessions.get('a-1')!)).toBe('owner:2');
+ relay.publish([completion]);
+ expect(agentIslandCompletionToken(state.sessions.get('a-1')!)).toBeUndefined();
+ } finally {
+ relay.dispose();
+ clearRemoteSessionActivity();
+ }
+ });
const sessions = [
remoteSession('a-1', 'device-a'),
remoteSession('a-idle', 'device-a'),
diff --git a/apps/desktop/src/renderer/features/device-link/agentIslandRemoteSessions.ts b/apps/desktop/src/renderer/features/device-link/agentIslandRemoteSessions.ts
index f4e045a89a..98de3688b8 100644
--- a/apps/desktop/src/renderer/features/device-link/agentIslandRemoteSessions.ts
+++ b/apps/desktop/src/renderer/features/device-link/agentIslandRemoteSessions.ts
@@ -73,10 +73,11 @@ export function buildAgentIslandRemoteSessionInputs(
function remoteActivityInput(activity: RemoteSessionActivity): Pick<
AgentIslandRemoteSessionInput,
- 'phase' | 'detail' | 'completionNotification' | 'workingPhase' | 'interactionKind'
+ 'phase' | 'detail' | 'completionNotification' | 'completionToken' | 'workingPhase' | 'interactionKind'
> {
return {
phase: activity.phase,
+ ...(activity.completionToken ? { completionToken: activity.completionToken } : {}),
detail: activity.compactDetail,
...(activity.completionNotification ? { completionNotification: activity.completionNotification } : {}),
...(activity.workingPhase ? { workingPhase: activity.workingPhase } : {}),
diff --git a/apps/desktop/src/renderer/features/device-link/remoteSessionActivityStore.ts b/apps/desktop/src/renderer/features/device-link/remoteSessionActivityStore.ts
index 8cb014abaf..2373401857 100644
--- a/apps/desktop/src/renderer/features/device-link/remoteSessionActivityStore.ts
+++ b/apps/desktop/src/renderer/features/device-link/remoteSessionActivityStore.ts
@@ -25,6 +25,7 @@ export type RemoteSessionActivityPhase = 'running' | 'needs-interaction' | 'comp
/** 镜像 @cindy/device-link 的 SessionActivityPayload(renderer 不直接依赖该包)。 */
export interface RemoteSessionActivity {
+ completionToken?: string;
sessionId: string;
phase: RemoteSessionActivityPhase;
compactDetail: string;
@@ -63,6 +64,7 @@ function isPhase(value: unknown): value is RemoteSessionActivityPhase {
function sameActivity(a: RemoteSessionActivity, b: RemoteSessionActivity): boolean {
return (
+ a.completionToken === b.completionToken &&
a.phase === b.phase &&
a.compactDetail === b.compactDetail &&
a.workingPhase === b.workingPhase &&
@@ -153,6 +155,8 @@ export function applyRemoteSessionActivity(deviceId: string, payload: unknown):
return;
}
const next: RemoteSessionActivity = {
+ ...(typeof p.completionToken === 'string' && p.completionToken.length > 0 && p.completionToken.length <= 128
+ ? { completionToken: p.completionToken } : {}),
sessionId,
phase: p.phase,
compactDetail: typeof p.compactDetail === 'string' ? p.compactDetail : '',
diff --git a/apps/desktop/src/shared/agentIsland.ts b/apps/desktop/src/shared/agentIsland.ts
index 03622db2ce..46b848b71b 100644
--- a/apps/desktop/src/shared/agentIsland.ts
+++ b/apps/desktop/src/shared/agentIsland.ts
@@ -43,6 +43,8 @@ export interface AgentIslandCompanionSnapshot {
* Renderer-facing session snapshot for the macOS Agent Island overlay.
*/
export interface AgentIslandSessionSnapshot {
+ /** Opaque identity of the completed card, issued by its owning process. */
+ completionToken?: string;
/** This completion preserves older unread state without requesting a new alert. */
completionNotification?: 'silent';
sessionId: string;
@@ -75,6 +77,7 @@ export interface AgentIslandPermissionActionSnapshot {
*/
export interface AgentIslandSessionActivity
extends Omit<SessionActivitySnapshot, 'phase' | 'interactionKind'> {
+ completionToken?: string;
completionNotification?: 'silent';
phase: AgentIslandSessionPhase;
interactionKind?: AgentIslandInteractionKind;
@@ -804,6 +807,7 @@ export const AGENT_ISLAND_SET_REMOTE_SESSIONS_CHANNEL = 'agent-island:set-remote
* 只含 running / needs-interaction / 未读终态;范围由 renderer 按侧栏「任务范围」裁剪。
*/
export interface AgentIslandRemoteSessionInput {
+ completionToken?: string;
completionNotification?: 'pending' | 'teammate' | 'silent';
sessionId: string;
deviceId: string;
@@ -866,10 +870,12 @@ export function parseAgentIslandRemoteSessions(raw: unknown): AgentIslandRemoteS
? record.interactionKind as AgentIslandInteractionKind
: undefined;
const workingPhase = readBoundedString(record.workingPhase, 64);
+ const completionToken = readBoundedString(record.completionToken, 128);
const companion = readRemoteCompanion(record.companion);
out.push({
sessionId,
deviceId,
+ ...(completionToken ? { completionToken } : {}),
deviceName: readBoundedString(record.deviceName, AGENT_ISLAND_REMOTE_TEXT_MAX_LENGTH),
title: readBoundedString(record.title, AGENT_ISLAND_REMOTE_TEXT_MAX_LENGTH),
workingDir: readBoundedString(record.workingDir, AGENT_ISLAND_REMOTE_TEXT_MAX_LENGTH * 4),
diff --git a/docs/dev-rules/protocol-compatibility.md b/docs/dev-rules/protocol-compatibility.md
index 43bb327b6d..9f4024c582 100644
--- a/docs/dev-rules/protocol-compatibility.md
+++ b/docs/dev-rules/protocol-compatibility.md
@@ -1,5 +1,19 @@
# 跨端协议兼容
+## 灵动岛完成卡操作
+
+`local-db:sessions:activity` 追加可选的 `completionToken`,由任务所属进程按完成卡代次签发。
+桌面控制端经活动镜像将它原样传到原生灵动岛;新完成卡即使文案和毫秒时间相同也会更换标识。
+新 invoke `agent-island:completion-action(sessionId, action, completionToken)` 只支持 `mark-read` /
+`archive`,复用同账号远控授权和既有任务发送锁;归属端在变更前核对卡片,归档另在现有
+worktree 资源等待后复核。控制端先按既有工作区/自动化预检规则确认,再发送归档动作。
+
+旧控制端忽略可选字段;新控制端连接旧归属端时,没有标识的远程卡片保留点击打开入口,
+不提供滑动动作。旧归属端不识别新增 invoke 时恢复本机卡片,不回退到无卡片校验的归档/已读
+请求,不重放。原生 helper 的完成动作追加同一标识,缺失时不执行。无需服务端、Mobile
+原生配置或数据库 migration 更新。回归见 `agentIslandRemoteSessions.test.ts`、
+`agent-island/__tests__/service.test.ts` 和 `localDb/ipc/__tests__/sessionsUpdate.test.ts`。
+
## 限额恢复时间查询
既有 `maker:usage:claude-subscription` 请求可选在 providerId 后追加 `true`,表示等待同一余量
diff --git a/docs/product-rules/archive-pauses-automations.md b/docs/product-rules/archive-pauses-automations.md
index d8cd3c22db..22b38f92ba 100644
--- a/docs/product-rules/archive-pauses-automations.md
+++ b/docs/product-rules/archive-pauses-automations.md
@@ -23,7 +23,7 @@
## 验收
-- 桌面:侧栏单条 / 行内归档、批量归档、项目「全部归档」、标题栏菜单、硬件快捷键、文件浏览
+- 桌面:侧栏单条 / 行内归档、灵动岛完成卡滑动归档、批量归档、项目「全部归档」、标题栏菜单、硬件快捷键、文件浏览
模式关闭任务,遇到上述绑定时均出现带自动化提示的确认。
- 手机:滑动归档、选项菜单归档、任务详情菜单归档弹系统确认;设备页批量归档的确认条显示
受影响的任务数。
diff --git a/packages/device-link/src/__tests__/allowlist.test.ts b/packages/device-link/src/__tests__/allowlist.test.ts
index f440a39137..b748bb75dc 100644
--- a/packages/device-link/src/__tests__/allowlist.test.ts
+++ b/packages/device-link/src/__tests__/allowlist.test.ts
@@ -108,6 +108,7 @@ describe('REMOTE_INVOKE_ALLOWLIST', () => {
it('放行会话未读已读回执(控制端看完会话,清被控端灵动岛 / 角标 / 侧栏未读)', () => {
expect(REMOTE_INVOKE_ALLOWLIST.has('notification:clear-session-attention')).toBe(true);
+ expect(REMOTE_INVOKE_ALLOWLIST.has('agent-island:completion-action')).toBe(true);
// mark 方向不放行:未读的产生真相只在被控端 main,远程不得凭空标未读。
expect(REMOTE_INVOKE_ALLOWLIST.has('notification:mark-session-attention')).toBe(false);
});
diff --git a/packages/device-link/src/allowlist.ts b/packages/device-link/src/allowlist.ts
index 1c346a1fce..da685906a6 100644
--- a/packages/device-link/src/allowlist.ts
+++ b/packages/device-link/src/allowlist.ts
@@ -419,6 +419,9 @@ const EXTENDED_INVOKE_CHANNELS: readonly string[] = [
// 副作用;语义在被控端执行才正确(灵动岛 / Dock 角标 / 侧栏红绿点的未读真相都在被控端
// main)。老被控端无此 channel → CHANNEL_NOT_ALLOWED → 控制端吞掉降级(仅本地清点)。
'notification:clear-session-attention',
+ // Completed-card action, guarded by an owner-issued token before any mutation.
+ // Old hosts reject this channel; callers must not fall back to unguarded writes.
+ 'agent-island:completion-action',
// —— Project automation ——
'maker:project-automation:reconcile',
'maker:project-automation:list-consents',
diff --git a/packages/device-link/src/topics.ts b/packages/device-link/src/topics.ts
index 028ea11c96..c912fb27e6 100644
--- a/packages/device-link/src/topics.ts
+++ b/packages/device-link/src/topics.ts
@@ -54,6 +54,8 @@ export function parseFsWatchTopic(topic: string): string | null {
export type SessionActivityPhase = 'running' | 'needs-interaction' | 'completed' | 'error';
export interface SessionActivityPayload {
+ /** Optional owner-issued completion identity. Old hosts omit it; never infer one. */
+ completionToken?: string;
/** Completion notification policy only; activity/attention remains unchanged.
* Absent on older hosts. Unknown values use ordinary completion semantics. */
completionNotification?: 'pending' | 'teammate' | 'silent';