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(desktop): 为 worktree 回收增加失败预算和恢复入口 (#4672)

Chris Zhangb0f9c35ecac3
diff --git a/apps/desktop/src/main/__tests__/managedWorktreeRecycle.test.ts b/apps/desktop/src/main/__tests__/managedWorktreeRecycle.test.ts
index dc2dda0367..0bb9c0f739 100644
--- a/apps/desktop/src/main/__tests__/managedWorktreeRecycle.test.ts
+++ b/apps/desktop/src/main/__tests__/managedWorktreeRecycle.test.ts
@@ -37,7 +37,7 @@ vi.mock('../worktree/recoveryArchive', async (original) => ({
createRecoveryArchive: archive, verifyRecoveryArchive: async () => {},
}));
-import { recycleManagedWorktree, requestWorktreeRecycle } from '../worktree/managedRecycle';
+import { checkpointWorktreeForReuse, recycleManagedWorktree, requestWorktreeRecycle } from '../worktree/managedRecycle';
import { readRecycleRecord } from '../worktree/recycleJournal';
import { inventoryWorktree } from '../worktree/recoveryArchive';
import { physicalWorktreeKey } from '../worktree/resourceLock';
@@ -78,6 +78,17 @@ describe('shared worktree recycling', () => {
});
const recycle = () => recycleManagedWorktree(meta, { canRemove: async () => removable });
+ it('does not rebuild failed archives after the durable budget is exhausted', async () => {
+ archive.mockRejectedValue(new Error('temporary filesystem failure'));
+ for (let attempt = 0; attempt < 5; attempt++) expect(await recycle()).toBe(false);
+ expect(archive).toHaveBeenCalledTimes(3);
+ expect((await readRecycleRecord(meta.path))?.retryPolicy?.state).toBe('paused');
+ await expect(checkpointWorktreeForReuse(meta)).rejects.toThrow('recycling is paused');
+ expect(archive).toHaveBeenCalledTimes(3);
+ expect((await fs.stat(meta.path)).isDirectory()).toBe(true);
+ expect(state.registry.has(meta.sessionId)).toBe(true);
+ });
+
it('limits simultaneous recycling of distinct resources to one', async () => {
let release!: () => void;
const gate = new Promise<void>((resolve) => { release = resolve; });
diff --git a/apps/desktop/src/main/__tests__/worktreeRecycleControls.test.ts b/apps/desktop/src/main/__tests__/worktreeRecycleControls.test.ts
new file mode 100644
index 0000000000..8c49e38c35
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/worktreeRecycleControls.test.ts
@@ -0,0 +1,60 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { WorktreeRecycleRecord } from '../worktree/recycleJournal';
+
+const state = vi.hoisted(() => ({ record: null as WorktreeRecycleRecord | null, registeredGeneration: 'g1' }));
+const wake = vi.hoisted(() => vi.fn());
+vi.mock('../worktree/recycleJournal', () => ({
+ listRecycleRecords: async () => state.record ? [state.record] : [],
+ readRecycleRecord: async () => state.record,
+ writeRecycleRecord: async (record: WorktreeRecycleRecord) => { state.record = JSON.parse(JSON.stringify(record)); },
+ worktreeGeneration: (meta: { generation: string }) => meta.generation,
+}));
+vi.mock('../worktree/worktreeStore', () => ({ get: () => ({ generation: state.registeredGeneration }) }));
+vi.mock('../worktree/resourceLock', () => ({
+ withWorktreeResourceLock: async (_path: string, run: () => Promise<void>) => run(),
+ physicalWorktreeKey: async (path: string) => path,
+}));
+vi.mock('../worktree/recycleEvents', () => ({ notifyWorktreeRecycleOpportunity: wake }));
+vi.mock('../worktree/recycleMaintenance', () => ({ isWorktreeRecycleRetrySuspended: () => false }));
+import { controlWorktreeRecycle, listWorktreeRecycleStatus } from '../worktree/recycleControls';
+
+const id = 'a'.repeat(64);
+describe('local worktree recycle controls', () => {
+ beforeEach(() => {
+ wake.mockClear(); state.registeredGeneration = 'g1';
+ state.record = { id, generation: 'g1', phase: 'snapshotted', attempts: 3, nextAttemptAt: 200,
+ reason: 'archive-integrity', retryPolicy: { state: 'paused', failures: 3, failedWorkMs: 100 },
+ meta: { sessionId: 'owner', generation: 'g1', path: '/fixture/worktree', name: 'fixture' },
+ archive: { file: 'encrypted-evidence' }, snapshot: { commit: 'saved-commit' },
+ } as WorktreeRecycleRecord;
+ });
+ it('shows a paused failure and restarts only its budget, preserving all recovery evidence', async () => {
+ expect(await listWorktreeRecycleStatus()).toMatchObject([{ state: 'paused', reason: 'integrity' }]);
+ await controlWorktreeRecycle({ id, generation: 'g1', action: 'retry' });
+ expect(state.record).toMatchObject({ phase: 'snapshotted', attempts: 0, nextAttemptAt: 0,
+ retryPolicy: { state: 'retrying', failures: 0, failedWorkMs: 0 },
+ archive: { file: 'encrypted-evidence' }, snapshot: { commit: 'saved-commit' } });
+ expect(wake).toHaveBeenCalledOnce();
+ });
+ it('keeps the directory without waking the recycler or dropping recovery evidence', async () => {
+ await controlWorktreeRecycle({ id, generation: 'g1', action: 'keep' });
+ expect(state.record!.retryPolicy!.state).toBe('kept');
+ expect(state.record!.archive).toBeDefined();
+ expect(wake).not.toHaveBeenCalled();
+ });
+ it.each([
+ { id, generation: 'old', action: 'retry' },
+ { id: '../path', generation: 'g1', action: 'retry' },
+ { id, generation: 'g1', action: 'delete' },
+ ])('rejects stale or malformed controls: %j', async (input) => {
+ await expect(controlWorktreeRecycle(input)).rejects.toThrow();
+ expect(state.record!.retryPolicy!.state).toBe('paused');
+ expect(wake).not.toHaveBeenCalled();
+ });
+ it('does not modify a replacement generation or a completed recovery', async () => {
+ state.registeredGeneration = 'g2';
+ await expect(controlWorktreeRecycle({ id, generation: 'g1', action: 'retry' })).rejects.toThrow();
+ state.registeredGeneration = 'g1'; state.record!.phase = 'removed';
+ await expect(controlWorktreeRecycle({ id, generation: 'g1', action: 'retry' })).rejects.toThrow();
+ });
+});
diff --git a/apps/desktop/src/main/__tests__/worktreeRecycleMaintenance.test.ts b/apps/desktop/src/main/__tests__/worktreeRecycleMaintenance.test.ts
index 21c75cdd2d..c9ab155f80 100644
--- a/apps/desktop/src/main/__tests__/worktreeRecycleMaintenance.test.ts
+++ b/apps/desktop/src/main/__tests__/worktreeRecycleMaintenance.test.ts
@@ -6,7 +6,7 @@ const state = vi.hoisted(() => ({
rows: [] as Array<{ id: string; status: string; source: string; currentDatabase: boolean }>,
records: [] as WorktreeRecycleRecord[],
changed: () => {},
- watchError: (_error: unknown) => {},
+ watchError: vi.fn<(error: unknown) => void>(),
}));
const remove = vi.hoisted(() => vi.fn());
const list = vi.hoisted(() => vi.fn());
@@ -73,6 +73,37 @@ describe('durable worktree maintenance', () => {
state.rows = []; await maintenance.start();
expect(remove).not.toHaveBeenCalled(); expect(closeAndRecycle).not.toHaveBeenCalled();
});
+ it('keeps missing owners recoverable beyond three checks without charging failures', async () => {
+ state.rows = [];
+ await maintenance.start();
+ await vi.advanceTimersByTimeAsync(70_000);
+ expect(client.readLocalWorktreeReferences).toHaveBeenCalledTimes(4);
+ expect(maintenance.isRetrySuspended(state.records[0])).toBe(false);
+ expect(closeAndRecycle).not.toHaveBeenCalled();
+ expect(vi.getTimerCount()).toBe(1);
+ state.rows = [{ id: 'owner', status: 'archived', source: 'desktop', currentDatabase: true }];
+ closeAndRecycle.mockImplementationOnce(async () => { state.records[0].phase = 'removed'; });
+ await vi.advanceTimersByTimeAsync(80_000);
+ expect(closeAndRecycle).toHaveBeenCalledExactlyOnceWith('owner', 'archived');
+ expect(vi.getTimerCount()).toBe(0);
+ });
+ it('bounds genuine prerequisite failures without executing the removal core', async () => {
+ read.mockRejectedValue(new Error('journal unavailable'));
+ await maintenance.start();
+ await vi.advanceTimersByTimeAsync(60 * 60_000);
+ expect(read).toHaveBeenCalledTimes(3);
+ expect(maintenance.isRetrySuspended(state.records[0])).toBe(true);
+ expect(closeAndRecycle).not.toHaveBeenCalled();
+ expect(vi.getTimerCount()).toBe(0);
+ });
+ it('charges a rejected core attempt once rather than again in its catch', async () => {
+ closeAndRecycle.mockRejectedValue(new Error('lock unavailable'));
+ await maintenance.start();
+ await vi.advanceTimersByTimeAsync(60 * 60_000);
+ expect(closeAndRecycle).toHaveBeenCalledTimes(3);
+ expect(maintenance.isRetrySuspended(state.records[0])).toBe(true);
+ expect(vi.getTimerCount()).toBe(0);
+ });
it('leaves an empty queue idle without reading databases or scanning historical registrations', async () => {
state.records = []; await maintenance.start();
expect(vi.getTimerCount()).toBe(0);
@@ -120,17 +151,31 @@ describe('durable worktree maintenance', () => {
await vi.advanceTimersByTimeAsync(100);
expect(closeAndRecycle).toHaveBeenCalledExactlyOnceWith('owner', 'archived');
});
- it('keeps retrying after the backoff cap and lets a resource event wake it early', async () => {
+ it('stops automatic retries after the budget and permits an explicit resource wake', async () => {
await maintenance.start();
- await vi.advanceTimersByTimeAsync(30 * 60_000);
- expect(closeAndRecycle).toHaveBeenCalledTimes(8);
- expect(vi.getTimerCount()).toBe(1);
- await vi.advanceTimersByTimeAsync(30 * 60_000);
- expect(closeAndRecycle).toHaveBeenCalledTimes(9);
+ await vi.advanceTimersByTimeAsync(60 * 60_000);
+ expect(closeAndRecycle).toHaveBeenCalledTimes(3);
+ expect(vi.getTimerCount()).toBe(0);
notifyWorktreeRecycleOpportunity(state.records[0].meta.path);
await vi.advanceTimersByTimeAsync(100);
- expect(closeAndRecycle.mock.calls.length).toBeGreaterThan(9);
- expect(vi.getTimerCount()).toBe(1);
+ expect(closeAndRecycle).toHaveBeenCalledTimes(4);
+ });
+ it('never wakes durable pauses on incidental resource events', async () => {
+ state.records[0].retryPolicy = { state: 'paused', failures: 3, failedWorkMs: 100 };
+ await maintenance.start();
+ notifyWorktreeRecycleOpportunity(state.records[0].meta.path);
+ await vi.advanceTimersByTimeAsync(60 * 60_000);
+ expect(closeAndRecycle).not.toHaveBeenCalled();
+ expect(vi.getTimerCount()).toBe(0);
+ });
+ it('rechecks waiting references once at startup, then waits for a release event', async () => {
+ state.records[0].retryPolicy = { state: 'waiting', failures: 0, failedWorkMs: 0 };
+ await maintenance.start();
+ expect(closeAndRecycle).toHaveBeenCalledTimes(1);
+ expect(vi.getTimerCount()).toBe(0);
+ notifyWorktreeRecycleOpportunity(state.records[0].meta.path);
+ await vi.advanceTimersByTimeAsync(100);
+ expect(closeAndRecycle).toHaveBeenCalledTimes(2);
});
it('continues with other resources after one request fails', async () => {
state.records.push(record('second')); state.rows.push({ ...state.rows[0], id: 'second' });
diff --git a/apps/desktop/src/main/__tests__/worktreeRecyclePolicy.test.ts b/apps/desktop/src/main/__tests__/worktreeRecyclePolicy.test.ts
new file mode 100644
index 0000000000..8cb0358a94
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/worktreeRecyclePolicy.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import type { WorktreeRecycleRecord } from '../worktree/recycleJournal';
+import { deferRecycle, MAX_RECYCLE_FAILED_WORK_MS, recycleFailureReason, recyclePolicy } from '../worktree/recyclePolicy';
+
+const record = () => ({ attempts: 0, nextAttemptAt: 0 } as WorktreeRecycleRecord);
+describe('worktree recycle retry budget', () => {
+ it('persists exhaustion across serialized reloads', () => {
+ let value = record();
+ for (let i = 0; i < 3; i++) {
+ deferRecycle(value, 'EBUSY', 100, 1000);
+ value = JSON.parse(JSON.stringify(value));
+ }
+ expect(recyclePolicy(value)).toEqual({ state: 'paused', failures: 3, failedWorkMs: 300 });
+ expect(value.nextAttemptAt).toBe(0);
+ });
+ it('pauses after the accumulated failed-work budget even below the retry count', () => {
+ const value = record();
+ deferRecycle(value, 'recycle-failed', MAX_RECYCLE_FAILED_WORK_MS);
+ expect(recyclePolicy(value).state).toBe('paused');
+ });
+ it('does not charge reference waits or repeatedly schedule kept directories', () => {
+ const value = record();
+ deferRecycle(value, 'referenced-before-removal', 100);
+ expect(recyclePolicy(value)).toEqual({ state: 'waiting', failures: 0, failedWorkMs: 0 });
+ expect(value.nextAttemptAt).toBe(0);
+ deferRecycle(value, 'keep-sentinel', 100);
+ expect(recyclePolicy(value).state).toBe('kept');
+ });
+ it.each(['archive-integrity', 'ENOSPC', 'EACCES', 'directory-replaced'])('pauses %s without burning more attempts', (reason) => {
+ const value = record(); deferRecycle(value, reason, 100);
+ expect(recyclePolicy(value).state).toBe('paused');
+ });
+ it('does not convert historical reference waits into exhausted failures', () => {
+ const value = { ...record(), attempts: 400, reason: 'referenced-or-runtime-unavailable' };
+ expect(recyclePolicy(value)).toEqual({ state: 'waiting', failures: 0, failedWorkMs: 0 });
+ value.reason = 'recycle-failed';
+ expect(recyclePolicy(value).state).toBe('paused');
+ });
+ it('recognizes exact integrity errors without treating arbitrary errors as permanent', () => {
+ expect(recycleFailureReason(new Error('archive content does not match worktree inventory'))).toBe('archive-integrity');
+ expect(recycleFailureReason(new Error('temporary unavailable'))).toBe('recycle-failed');
+ });
+});
diff --git a/apps/desktop/src/main/bootstrap-electron.ts b/apps/desktop/src/main/bootstrap-electron.ts
index 2fc8d7bcf3..d215746e80 100644
--- a/apps/desktop/src/main/bootstrap-electron.ts
+++ b/apps/desktop/src/main/bootstrap-electron.ts
@@ -1,3 +1,4 @@
+import { listWorktreeRecycleStatus, controlWorktreeRecycle } from './worktree/recycleControls';
import { registerFilePeerIpc } from './device-link/filePeer';
import { registerLoginItemIpc } from './login-item-ipc.js';
import { createLatestSourceVersionReader } from './cindy-make/latestSourceVersion.js';
@@ -8166,6 +8167,16 @@ const registerIpcHandlers = () => {
},
);
+ // Local storage controls never accept a filesystem path from the renderer.
+ ipcMain.handle('worktree-recycle:list', async (event) => {
+ assertTrustedAppRendererEvent(event);
+ return listWorktreeRecycleStatus();
+ });
+ ipcMain.handle('worktree-recycle:control', async (event, input: unknown) => {
+ assertTrustedAppRendererEvent(event);
+ await controlWorktreeRecycle(input);
+ });
+
// ── 存储空间卡片(关于页)IPC:媒体总仓回收器 + 对账──
// 业务体在 cindy-media/storageIpc.ts(依赖注入,规则 14),这里只做接线。
{
diff --git a/apps/desktop/src/main/worktree/managedRecycle.ts b/apps/desktop/src/main/worktree/managedRecycle.ts
index 9a41a53ded..0966967b59 100644
--- a/apps/desktop/src/main/worktree/managedRecycle.ts
+++ b/apps/desktop/src/main/worktree/managedRecycle.ts
@@ -1,3 +1,4 @@
+import { deferRecycle, recycleFailureReason, recyclePolicy } from './recyclePolicy';
import { randomUUID } from 'node:crypto';
import fs from 'node:fs/promises';
import path from 'node:path';
@@ -7,7 +8,6 @@ import { gitExec } from './gitExec';
import { hasLiveSessionReference, loadLiveSessionPathKeys } from './liveSessionRefs';
import {
newRecycleRecord, readRecycleRecord, writeRecycleRecord, worktreeGeneration,
- type WorktreeRecycleRecord,
} from './recycleJournal';
import { createRecoveryArchive, inventoryWorktree, sameWorktreeFiles, verifyRecoveryArchive } from './recoveryArchive';
import { physicalWorktreeKey, withWorktreeResourceLock } from './resourceLock';
@@ -33,6 +33,11 @@ export async function checkpointWorktreeForReuse(meta: WorktreeMeta): Promise<vo
if (hasLiveSessionReference(meta, await loadLiveSessionPathKeys({ contextPath: meta.path }))) {
throw new Error('pooled worktree is referenced');
}
+ const previous = await readRecycleRecord(meta.path);
+ if (previous?.generation === worktreeGeneration(meta)
+ && ['paused', 'kept'].includes(recyclePolicy(previous).state)) {
+ throw new Error('pooled worktree recycling is paused');
+ }
const record = await newRecycleRecord(meta);
record.directoryIdentity = (await directoryIdentity(meta.path)) ?? undefined;
if (!record.directoryIdentity || !isManagedWorktreePath(meta.path, meta.baseRepo, store.getAllPaths())) {
@@ -100,10 +105,11 @@ async function recycleManagedWorktreeInSlot(meta: WorktreeMeta, options: Managed
record.directoryIdentity = (await directoryIdentity(meta.path)) ?? undefined;
await writeRecycleRecord(record);
}
+ const policy = recyclePolicy(record);
+ if (policy.state === 'paused' || policy.state === 'kept') return false;
+ const startedAt = performance.now();
const defer = async (reason: string): Promise<false> => {
- record.reason = reason;
- record.attempts += 1;
- record.nextAttemptAt = Date.now() + Math.min(30 * 60_000, 5_000 * 2 ** Math.min(record.attempts, 9));
+ deferRecycle(record, reason, performance.now() - startedAt);
await writeRecycleRecord(record);
return false;
};
@@ -227,7 +233,7 @@ async function recycleManagedWorktreeInSlot(meta: WorktreeMeta, options: Managed
await unregisterResource(meta);
return true;
} catch (error) {
- return defer((error as NodeJS.ErrnoException).code ?? 'recycle-failed');
+ return defer(recycleFailureReason(error));
}
}));
}
diff --git a/apps/desktop/src/main/worktree/recycleControls.ts b/apps/desktop/src/main/worktree/recycleControls.ts
new file mode 100644
index 0000000000..851867f25a
--- /dev/null
+++ b/apps/desktop/src/main/worktree/recycleControls.ts
@@ -0,0 +1,72 @@
+import { isIpcError } from '../../shared/ipc-errors';
+import { createLogger } from '../logger';
+import type { WorktreeRecycleAction, WorktreeRecycleStatus } from '../../shared/worktreeRecycle';
+import { listRecycleRecords, readRecycleRecord, writeRecycleRecord, worktreeGeneration } from './recycleJournal';
+import { isWorktreeRecycleRetrySuspended } from './recycleMaintenance';
+import { recyclePolicy } from './recyclePolicy';
+import { withWorktreeResourceLock, physicalWorktreeKey } from './resourceLock';
+import { notifyWorktreeRecycleOpportunity } from './recycleEvents';
+import * as store from './worktreeStore';
+import { throwIpcError } from '../utils/ipcValidate';
+
+function visibleReason(reason?: string): WorktreeRecycleStatus['reason'] {
+ if (!reason) return 'pending';
+ if (reason.startsWith('referenced')) return 'in-use';
+ if (reason.includes('changed')) return 'changed';
+ if (reason === 'keep-sentinel' || reason === 'user-kept') return 'kept';
+ if (reason === 'archive-integrity') return 'integrity';
+ if (['ENOSPC', 'EACCES', 'EPERM'].includes(reason)) return 'storage';
+ if (['directory-replaced', 'unmanaged-path', 'redirected-worktree-parent', 'legacy-quarantine-needs-review'].includes(reason)) return 'identity';
+ return 'failed';
+}
+
+async function listWorktreeRecycleStatusInner(): Promise<WorktreeRecycleStatus[]> {
+ return (await listRecycleRecords()).filter((record) => {
+ if (['removed', 'restoring', 'restored'].includes(record.phase) || record.meta.ephemeral) return false;
+ const current = store.get(record.meta.sessionId);
+ return !current || worktreeGeneration(current) === record.generation;
+ }).map((record) => ({
+ id: record.id, generation: record.generation, name: record.meta.name, path: record.meta.path,
+ state: recyclePolicy(record).state === 'retrying' && isWorktreeRecycleRetrySuspended(record) ? 'paused' : recyclePolicy(record).state, failures: recyclePolicy(record).failures,
+ reason: isWorktreeRecycleRetrySuspended(record) && !record.reason ? 'failed' : visibleReason(record.reason),
+ }));
+}
+
+/** Changes scheduling only. Actual recycling still revalidates live references and recovery evidence. */
+async function controlWorktreeRecycleInner(value: unknown): Promise<void> {
+ const input = value as Partial<WorktreeRecycleAction> | null;
+ if (!input || typeof input.id !== 'string' || !/^[a-f0-9]{64}$/.test(input.id)
+ || typeof input.generation !== 'string' || !input.generation
+ || !['retry', 'keep'].includes(input.action ?? '')) throwIpcError('INVALID_PARAMS', 'Invalid or stale worktree recycle request');
+ const candidate = (await listRecycleRecords()).find((record) => record.id === input!.id);
+ if (!candidate) throwIpcError('NOT_FOUND', 'Worktree recycle request not found');
+ await withWorktreeResourceLock(candidate.meta.path, async () => {
+ const record = await readRecycleRecord(candidate.meta.path);
+ const current = record && store.get(record.meta.sessionId);
+ if (!record || record.id !== input!.id || record.generation !== input!.generation
+ || (current && worktreeGeneration(current) !== record.generation)
+ || ['removed', 'restoring', 'restored'].includes(record.phase)) throwIpcError('INVALID_PARAMS', 'Invalid or stale worktree recycle request');
+ record.retryPolicy = { state: input!.action === 'keep' ? 'kept' : 'retrying', failures: 0, failedWorkMs: 0 };
+ record.reason = input!.action === 'keep' ? 'user-kept' : undefined;
+ record.attempts = 0;
+ record.nextAttemptAt = 0;
+ await writeRecycleRecord(record);
+ });
+ if (input!.action === 'retry') notifyWorktreeRecycleOpportunity(await physicalWorktreeKey(candidate.meta.path));
+}
+
+const log = createLogger('worktree-recycle-controls');
+async function ipcAction<T>(action: () => Promise<T>): Promise<T> {
+ try { return await action(); }
+ catch (error) {
+ if (isIpcError(error)) throw error;
+ log.warn('worktree recycle control failed', { code: (error as NodeJS.ErrnoException)?.code ?? 'unavailable' });
+ throwIpcError('INTERNAL', 'Worktree recycle control is unavailable');
+ }
+}
+export function listWorktreeRecycleStatus(): Promise<WorktreeRecycleStatus[]> {
+ return ipcAction(listWorktreeRecycleStatusInner);
+}
+export function controlWorktreeRecycle(value: unknown): Promise<void> {
+ return ipcAction(() => controlWorktreeRecycleInner(value));
+}
diff --git a/apps/desktop/src/main/worktree/recycleJournal.ts b/apps/desktop/src/main/worktree/recycleJournal.ts
index 23451b0d65..a4a7efe629 100644
--- a/apps/desktop/src/main/worktree/recycleJournal.ts
+++ b/apps/desktop/src/main/worktree/recycleJournal.ts
@@ -5,6 +5,7 @@ import path from 'node:path';
import { app } from 'electron';
import { physicalWorktreeKey, worktreeResourceId } from './resourceLock';
+import type { WorktreeRecyclePolicy } from './recyclePolicy';
import type { WorktreeMeta } from './types';
import type { WorktreeRecoveryArchive } from './recoveryArchive';
import { createLogger } from '../logger';
@@ -23,6 +24,7 @@ export interface WorktreeRecycleRecord {
attempts: number;
nextAttemptAt: number;
reason?: string;
+ retryPolicy?: WorktreeRecyclePolicy;
/** null is a durable marker that recovery has reserved a previously absent directory. */
directoryIdentity?: string | null;
snapshot?: { head: string; headRef?: string | null; tree: string; indexTree: string; commit: string; ref: string; indexHash: string };
@@ -63,6 +65,10 @@ function parseRecord(raw: string, id: string): WorktreeRecycleRecord {
&& (typeof record.restoreCheckoutPath !== 'string' || !path.isAbsolute(record.restoreCheckoutPath)))
|| typeof record.requestedAt !== 'string' || !Number.isFinite(Date.parse(record.requestedAt))
|| !Number.isInteger(record.attempts) || record.attempts < 0
+ || (record.retryPolicy !== undefined && (!record.retryPolicy
+ || !['retrying', 'waiting', 'paused', 'kept'].includes(record.retryPolicy.state)
+ || !Number.isInteger(record.retryPolicy.failures) || record.retryPolicy.failures < 0
+ || !Number.isFinite(record.retryPolicy.failedWorkMs) || record.retryPolicy.failedWorkMs < 0))
|| !Number.isFinite(record.nextAttemptAt)
|| !['pending', 'snapshotted', 'removing', 'removed', 'restoring', 'restored'].includes(record.phase)) {
throw new Error('invalid worktree recycle record');
diff --git a/apps/desktop/src/main/worktree/recycleMaintenance.ts b/apps/desktop/src/main/worktree/recycleMaintenance.ts
index b8e0a6eeed..b92bbf3860 100644
--- a/apps/desktop/src/main/worktree/recycleMaintenance.ts
+++ b/apps/desktop/src/main/worktree/recycleMaintenance.ts
@@ -1,3 +1,4 @@
+import { MAX_RECYCLE_FAILURES, recyclePolicy } from './recyclePolicy';
import fs from 'node:fs/promises';
import path from 'node:path';
import { app } from 'electron';
@@ -36,8 +37,9 @@ export class WorktreeRecycleMaintenance {
private watchFailures = 0;
private watchRetryAt = 0;
private scanFailures = 0;
+ private initialPass = true;
private readonly wakeIds = new Set<string>();
- private readonly attempts = new Map<string, { count: number; notBefore: number }>();
+ private readonly attempts = new Map<string, { count: number; checks: number; notBefore: number }>();
constructor(public options: WorktreeMaintenanceOptions) {}
@@ -112,17 +114,31 @@ export class WorktreeRecycleMaintenance {
private key(record: WorktreeRecycleRecord): string { return `${record.id}:${record.generation}`; }
- private eligible(record: WorktreeRecycleRecord): boolean {
+ private eligible(record: WorktreeRecycleRecord, opportunity = false): boolean {
+ const state = recyclePolicy(record).state;
+ if (state === 'paused' || state === 'kept' || (state === 'waiting' && !opportunity)) return false;
if (record.phase === 'restored' || record.phase === 'restoring' || record.meta.ephemeral) return false;
const current = store.get(record.meta.sessionId);
if (record.phase === 'removed' && !current) return false;
- // Attempts only control backoff. A directory may remain externally locked
- // longer than one backoff window; it must become eligible again when the
- // lock is released or the next deadline arrives.
+ // Runtime-release hints can wake reference waits, never a paused failure budget.
return !current || worktreeGeneration(current) === record.generation;
}
+ isRetrySuspended(record: WorktreeRecycleRecord): boolean {
+ return (this.attempts.get(this.key(record))?.count ?? 0) >= MAX_RECYCLE_FAILURES;
+ }
+
+ private chargeAttempt(record: WorktreeRecycleRecord): void {
+ const previous = this.attempts.get(this.key(record));
+ this.attempts.set(this.key(record), {
+ count: (previous?.count ?? 0) + 1,
+ checks: previous?.checks ?? 1,
+ notBefore: previous?.notBefore ?? Date.now() + retryDelay(1),
+ });
+ }
+
private deadline(record: WorktreeRecycleRecord): number {
+ if (this.isRetrySuspended(record)) return Infinity;
return Math.max(record.nextAttemptAt, this.attempts.get(this.key(record))?.notBefore ?? 0);
}
@@ -137,15 +153,25 @@ export class WorktreeRecycleMaintenance {
const records = await listRecycleRecords();
const wakeIds = new Set(this.wakeIds);
this.wakeIds.clear();
+ // A resource may have been released while Cindy was closed: recheck waits
+ // once on startup, but never reset a persisted fault/keep decision.
+ if (this.initialPass) {
+ for (const record of records) if (recyclePolicy(record).state === 'waiting') wakeIds.add(record.id);
+ this.initialPass = false;
+ }
for (const record of records) if (wakeIds.has(record.id)) this.attempts.delete(this.key(record));
- const due = records.filter((record) => this.eligible(record)
+ const due = records.filter((record) => this.eligible(record, wakeIds.has(record.id))
&& (wakeIds.has(record.id) || this.deadline(record) <= Date.now()));
// Empty queues and not-yet-due requests never open task databases.
if (due.length) {
for (const record of due) {
- const count = (this.attempts.get(this.key(record))?.count ?? 0) + 1;
- // Also back off errors before the removal core can persist nextAttemptAt.
- this.attempts.set(this.key(record), { count, notBefore: Date.now() + retryDelay(count) });
+ const previous = this.attempts.get(this.key(record));
+ const checks = (previous?.checks ?? 0) + 1;
+ // A missing owner is not a failed removal. Keep a bounded-rate metadata
+ // recheck so account/database visibility can recover without a resource event.
+ this.attempts.set(this.key(record), {
+ count: previous?.count ?? 0, checks, notBefore: Date.now() + retryDelay(checks),
+ });
}
await this.retry(due, wakeIds);
}
@@ -165,10 +191,11 @@ export class WorktreeRecycleMaintenance {
const rows = await db.readLocalWorktreeReferences();
for (const record of records) {
if (this.stopped || !this.options.isReady() || getDbClient() !== db) return;
+ let charged = false;
try {
const latest = await readRecycleRecord(record.meta.path);
if (this.stopped || !this.options.isReady() || getDbClient() !== db) return;
- if (!latest || latest.generation !== record.generation
+ if (!latest || !this.eligible(latest, wakeIds.has(record.id)) || latest.generation !== record.generation
|| latest.phase === 'restored' || latest.phase === 'restoring'
|| (latest.phase === 'removed' && !store.get(latest.meta.sessionId))
|| (!wakeIds.has(record.id) && latest.nextAttemptAt > Date.now())) continue;
@@ -176,6 +203,8 @@ export class WorktreeRecycleMaintenance {
// Unknown is not an orphan, including after switching the selected account.
if (!ownerRows.length || ownerRows.some((row) => row.source === 'bot'
|| (row.status !== 'archived' && row.status !== 'deleted'))) continue;
+ this.chargeAttempt(record);
+ charged = true;
attempted = true;
const currentRow = ownerRows.find((row) => row.currentDatabase);
if (currentRow) {
@@ -193,10 +222,12 @@ export class WorktreeRecycleMaintenance {
});
}
} catch (error) {
+ if (!charged) this.chargeAttempt(record);
log.warn('worktree request postponed', { resourceId: record.id, code: (error as NodeJS.ErrnoException).code ?? 'unavailable' });
}
}
} catch (error) {
+ for (const record of records) this.chargeAttempt(record);
log.warn('worktree references postponed', { code: (error as NodeJS.ErrnoException).code ?? 'unavailable' });
}
if (attempted && !this.stopped) await this.options.onAttemptComplete?.();
@@ -246,3 +277,8 @@ export async function auditRegisteredWorktrees(): Promise<void> {
await fs.writeFile(path.join(app.getPath('userData'), 'worktree-audit.json'), JSON.stringify({ at: new Date().toISOString(), summary, entries }), { mode: 0o600 });
log.info('worktree registry audit completed', summary);
}
+
+/** Fallback for failures before the journal can be written (for example a locked volume). */
+export function isWorktreeRecycleRetrySuspended(record: WorktreeRecycleRecord): boolean {
+ return maintenance?.isRetrySuspended(record) ?? false;
+}
diff --git a/apps/desktop/src/main/worktree/recyclePolicy.ts b/apps/desktop/src/main/worktree/recyclePolicy.ts
new file mode 100644
index 0000000000..66ff56af02
--- /dev/null
+++ b/apps/desktop/src/main/worktree/recyclePolicy.ts
@@ -0,0 +1,61 @@
+import type { WorktreeRecycleRecord } from './recycleJournal';
+
+export const MAX_RECYCLE_FAILURES = 3;
+export const MAX_RECYCLE_FAILED_WORK_MS = 30 * 60_000;
+export interface WorktreeRecyclePolicy {
+ state: 'retrying' | 'waiting' | 'paused' | 'kept';
+ failures: number;
+ failedWorkMs: number;
+}
+
+const waitingReasons = new Set([
+ 'referenced-or-runtime-unavailable', 'referenced-before-removal', 'referenced-before-fallback',
+ 'files-changed', 'files-changed-before-removal', 'git-baseline-changed',
+ 'git-baseline-changed-before-removal', 'residual-files-changed',
+]);
+const permanentReasons = new Set([
+ 'legacy-quarantine-needs-review', 'directory-replaced', 'unmanaged-path',
+ 'redirected-worktree-parent', 'recovery-evidence-missing', 'archive-integrity',
+ 'ENOSPC', 'EACCES', 'EPERM',
+]);
+const integrityMessages = new Set([
+ 'archive content does not match worktree inventory',
+ 'restored worktree files do not match recovery archive',
+ 'unsafe worktree archive entry', 'duplicate worktree archive entry',
+ 'invalid archive hard link', 'invalid archive symbolic link',
+ 'unsupported worktree archive entry',
+]);
+
+export function recycleFailureReason(error: unknown): string {
+ if (error instanceof Error && integrityMessages.has(error.message)) return 'archive-integrity';
+ const code = (error as NodeJS.ErrnoException | null)?.code;
+ return typeof code === 'string' ? code : 'recycle-failed';
+}
+
+/** Upgrade old counters conservatively, without charging live-reference waits as failures. */
+export function recyclePolicy(record: WorktreeRecycleRecord): WorktreeRecyclePolicy {
+ if (record.retryPolicy) return record.retryPolicy;
+ if (record.reason === 'keep-sentinel') return { state: 'kept', failures: 0, failedWorkMs: 0 };
+ if (record.reason && waitingReasons.has(record.reason)) return { state: 'waiting', failures: 0, failedWorkMs: 0 };
+ const failures = record.reason ? Math.min(record.attempts, MAX_RECYCLE_FAILURES) : 0;
+ return {
+ state: (record.reason && permanentReasons.has(record.reason)) || failures >= MAX_RECYCLE_FAILURES ? 'paused' : 'retrying',
+ failures, failedWorkMs: 0,
+ };
+}
+
+export function deferRecycle(record: WorktreeRecycleRecord, reason: string, elapsedMs: number, now = Date.now()): void {
+ const previous = recyclePolicy(record);
+ record.reason = reason;
+ record.attempts += 1;
+ if (reason === 'keep-sentinel' || waitingReasons.has(reason)) {
+ record.retryPolicy = { ...previous, state: reason === 'keep-sentinel' ? 'kept' : 'waiting' };
+ record.nextAttemptAt = 0;
+ return;
+ }
+ const failures = previous.failures + 1;
+ const failedWorkMs = previous.failedWorkMs + Math.max(0, elapsedMs);
+ const paused = permanentReasons.has(reason) || failures >= MAX_RECYCLE_FAILURES || failedWorkMs >= MAX_RECYCLE_FAILED_WORK_MS;
+ record.retryPolicy = { state: paused ? 'paused' : 'retrying', failures, failedWorkMs };
+ record.nextAttemptAt = paused ? 0 : now + Math.min(30 * 60_000, 5_000 * 2 ** failures);
+}
diff --git a/apps/desktop/src/preload/preload.ts b/apps/desktop/src/preload/preload.ts
index 903c0ed8bf..97bf3c433d 100644
--- a/apps/desktop/src/preload/preload.ts
+++ b/apps/desktop/src/preload/preload.ts
@@ -1,3 +1,4 @@
+import type { WorktreeRecycleAction, WorktreeRecycleStatus } from '../shared/worktreeRecycle';
import { FAVORITE_HOST_READY, FAVORITE_HOST_REQUEST, FAVORITE_HOST_REPLY, FAVORITE_HOST_CHANGED, type ModelFavoritesHostApi } from '../shared/modelFavoritesSync';
import { invokeOpenPath } from './openPath';
import { COPY_PNG_TO_CLIPBOARD_CHANNEL, type CopyPngToClipboardParams } from '../shared/pngClipboard';
@@ -4171,6 +4172,10 @@ contextBridge.exposeInMainWorld('electronAPI', {
ipcRenderer.invoke('image-cache:cleanup-files', urls),
// ── 媒体总仓存储管理(关于页存储空间卡片)──
+ worktreeRecycle: {
+ list: (): Promise<WorktreeRecycleStatus[]> => ipcRenderer.invoke('worktree-recycle:list'),
+ control: (input: WorktreeRecycleAction): Promise<void> => ipcRenderer.invoke('worktree-recycle:control', input),
+ },
// 占用统计 / 清理预检(报数)/ 执行清理 / 对账体检。scan 与 cleanup 的
// draftUrls 由 renderer 从 composerDraftStore 现场收集(main 读不到
// renderer 内存,草稿附件是合法的零引用 blob,必须随参取证防误删)。
diff --git a/apps/desktop/src/renderer/components/settings/SettingsView.tsx b/apps/desktop/src/renderer/components/settings/SettingsView.tsx
index 8a16e27c6c..dd90162bee 100644
--- a/apps/desktop/src/renderer/components/settings/SettingsView.tsx
+++ b/apps/desktop/src/renderer/components/settings/SettingsView.tsx
@@ -27,6 +27,7 @@ import { LanguageSection } from './LanguageSection';
import { LogoutSection } from './LogoutSection';
import { ImBotSection, isImBotSettingsGroup, type ImBotSettingsGroup } from './ImBotSection';
import { AboutSection } from './AboutSection';
+import { WorktreeRecycleCard } from './WorktreeRecycleCard';
import { StorageManagementCard } from './StorageManagementCard';
import { UserPromptSection } from './UserPromptSection';
import { MemorySection } from './MemorySection';
@@ -661,6 +662,7 @@ export function SettingsView() {
>
<section aria-label={t('settings.about.storage.title')}>
<StorageManagementCard />
+ <WorktreeRecycleCard />
</section>
</div>
)}
diff --git a/apps/desktop/src/renderer/components/settings/WorktreeRecycleCard.tsx b/apps/desktop/src/renderer/components/settings/WorktreeRecycleCard.tsx
new file mode 100644
index 0000000000..10a51ab5bf
--- /dev/null
+++ b/apps/desktop/src/renderer/components/settings/WorktreeRecycleCard.tsx
@@ -0,0 +1,68 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Button } from '@/components/ui/button';
+import { toast } from '@/lib/toast';
+import type { WorktreeRecycleStatus } from '../../../shared/worktreeRecycle';
+
+export function WorktreeRecycleCard() {
+ const { t } = useTranslation();
+ const [rows, setRows] = useState<WorktreeRecycleStatus[] | null>(null);
+ const [failed, setFailed] = useState(false);
+ const [busy, setBusy] = useState<string | null>(null);
+ const loading = useRef(false);
+ const refreshQueued = useRef(false);
+ const controlBusy = useRef(false);
+ const refresh = useCallback(async (): Promise<void> => {
+ if (loading.current) { refreshQueued.current = true; return; }
+ loading.current = true;
+ try {
+ setRows(await window.electronAPI.worktreeRecycle.list());
+ setFailed(false);
+ } catch { setFailed(true); }
+ finally {
+ loading.current = false;
+ if (refreshQueued.current) { refreshQueued.current = false; void refresh(); }
+ }
+ }, []);
+ useEffect(() => {
+ void refresh();
+ const onFocus = () => { void refresh(); };
+ window.addEventListener('focus', onFocus);
+ return () => window.removeEventListener('focus', onFocus);
+ }, [refresh]);
+ const control = async (row: WorktreeRecycleStatus, action: 'retry' | 'keep') => {
+ if (controlBusy.current) return;
+ controlBusy.current = true;
+ setBusy(row.id);
+ try {
+ await window.electronAPI.worktreeRecycle.control({ id: row.id, generation: row.generation, action });
+ await refresh();
+ } catch { toast.error(t('settings.worktreeRecycle.actionFailed')); }
+ finally { controlBusy.current = false; setBusy(null); }
+ };
+ return (
+ <div className="mt-6 rounded-xl border border-[var(--border-default)] p-4">
+ <div className="flex items-center justify-between gap-4">
+ <h3 className="text-sm font-medium text-[var(--text-primary)]">{t('settings.worktreeRecycle.title')}</h3>
+ <Button variant="secondary" size="md" onClick={() => { void refresh(); }}>{t('settings.worktreeRecycle.refresh')}</Button>
+ </div>
+ {failed ? <p role="alert" className="mt-3 text-sm text-[var(--text-secondary)]">{t('settings.worktreeRecycle.loadFailed')}</p>
+ : rows === null ? null : rows.length === 0 ? <p className="mt-3 text-sm text-[var(--text-secondary)]">{t('settings.worktreeRecycle.empty')}</p>
+ : <ul className="mt-3 divide-y divide-[var(--border-default)]">
+ {rows.map((row) => <li key={`${row.id}:${row.generation}`} className="flex flex-wrap items-center justify-between gap-3 py-3">
+ <div className="min-w-0 flex-1">
+ <p className="truncate text-sm text-[var(--text-primary)]" title={row.path}>{row.name}</p>
+ <p className="break-all text-xs text-[var(--text-secondary)]">{row.path}</p>
+ <p className="mt-1 text-xs text-[var(--text-secondary)]">
+ {t(`settings.worktreeRecycle.state.${row.state}`)} · {t(`settings.worktreeRecycle.reason.${row.reason}`)}
+ </p>
+ </div>
+ <div className="flex gap-2">
+ <Button variant="secondary" size="md" disabled={busy !== null} onClick={() => { void control(row, 'retry'); }}>{t('settings.worktreeRecycle.retry')}</Button>
+ <Button variant="secondary" size="md" disabled={busy !== null || row.state === 'kept'} onClick={() => { void control(row, 'keep'); }}>{t('settings.worktreeRecycle.keep')}</Button>
+ </div>
+ </li>)}
+ </ul>}
+ </div>
+ );
+}
diff --git a/apps/desktop/src/renderer/components/settings/__tests__/WorktreeRecycleCard.test.tsx b/apps/desktop/src/renderer/components/settings/__tests__/WorktreeRecycleCard.test.tsx
new file mode 100644
index 0000000000..2a31c835b6
--- /dev/null
+++ b/apps/desktop/src/renderer/components/settings/__tests__/WorktreeRecycleCard.test.tsx
@@ -0,0 +1,30 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { WorktreeRecycleCard } from '../WorktreeRecycleCard';
+vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key: string) => key }) }));
+vi.mock('@/lib/toast', () => ({ toast: { error: vi.fn() } }));
+afterEach(cleanup);
+it('shows the failure and sends a generation-bound retry, then refreshes', async () => {
+ const row = { id: 'resource', generation: 'g1', name: 'fixture', path: '/fixture', state: 'paused', reason: 'integrity', failures: 3 };
+ const list = vi.fn().mockResolvedValue([row]);
+ const control = vi.fn().mockResolvedValue(undefined);
+ Object.defineProperty(window, 'electronAPI', { value: { worktreeRecycle: { list, control } }, configurable: true });
+ render(<WorktreeRecycleCard />);
+ await screen.findByText('settings.worktreeRecycle.reason.integrity', { exact: false });
+ fireEvent.click(screen.getByRole('button', { name: 'settings.worktreeRecycle.retry' }));
+ await waitFor(() => expect(control).toHaveBeenCalledWith({ id: 'resource', generation: 'g1', action: 'retry' }));
+ await waitFor(() => expect(list).toHaveBeenCalledTimes(2));
+});
+describe('retained directories', () => {
+ it('keeps retry available but disables repeated keep', async () => {
+ Object.defineProperty(window, 'electronAPI', { value: { worktreeRecycle: {
+ list: vi.fn().mockResolvedValue([{ id: 'resource', generation: 'g1', name: 'fixture', path: '/fixture', state: 'kept', reason: 'kept', failures: 0 }]),
+ control: vi.fn(),
+ } }, configurable: true });
+ render(<WorktreeRecycleCard />);
+ await screen.findByText('fixture');
+ expect((screen.getByRole('button', { name: 'settings.worktreeRecycle.keep' }) as HTMLButtonElement).disabled).toBe(true);
+ expect((screen.getByRole('button', { name: 'settings.worktreeRecycle.retry' }) as HTMLButtonElement).disabled).toBe(false);
+ });
+});
diff --git a/apps/desktop/src/renderer/i18n/locales/en/common.json b/apps/desktop/src/renderer/i18n/locales/en/common.json
index 0414e55d79..9b328e27b1 100644
--- a/apps/desktop/src/renderer/i18n/locales/en/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/en/common.json
@@ -5773,6 +5773,31 @@
"versions": "Version Control",
"environment": "Environment"
}
+ },
+ "worktreeRecycle": {
+ "title": "Worktree cleanup",
+ "refresh": "Refresh",
+ "empty": "No worktrees awaiting cleanup",
+ "loadFailed": "Could not load cleanup status",
+ "actionFailed": "Could not update cleanup. Refresh and try again.",
+ "retry": "Retry cleanup",
+ "keep": "Keep directory",
+ "state": {
+ "retrying": "Awaiting cleanup",
+ "waiting": "Waiting for release",
+ "paused": "Automatic retries paused",
+ "kept": "Directory retained"
+ },
+ "reason": {
+ "in-use": "Still in use",
+ "changed": "Contents changed",
+ "kept": "Kept by request",
+ "integrity": "Backup verification failed",
+ "storage": "Check disk space and permissions",
+ "identity": "Directory identity needs review",
+ "failed": "Cleanup could not finish",
+ "pending": "Queued"
+ }
}
},
"remoteDevice": {
diff --git a/apps/desktop/src/renderer/i18n/locales/ja/common.json b/apps/desktop/src/renderer/i18n/locales/ja/common.json
index a46769c35c..e5431472a4 100644
--- a/apps/desktop/src/renderer/i18n/locales/ja/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ja/common.json
@@ -5771,6 +5771,31 @@
"versions": "バージョン管理",
"environment": "環境準備"
}
+ },
+ "worktreeRecycle": {
+ "title": "worktree のクリーンアップ",
+ "refresh": "更新",
+ "empty": "クリーンアップ待ちの worktree はありません",
+ "loadFailed": "状態を読み込めませんでした",
+ "actionFailed": "状態を更新できませんでした。更新して再試行してください",
+ "retry": "再試行",
+ "keep": "ディレクトリを保持",
+ "state": {
+ "retrying": "クリーンアップ待ち",
+ "waiting": "解放待ち",
+ "paused": "自動再試行を停止中",
+ "kept": "ディレクトリを保持"
+ },
+ "reason": {
+ "in-use": "使用中",
+ "changed": "内容が変更されました",
+ "kept": "保持が指定されています",
+ "integrity": "バックアップ検証に失敗",
+ "storage": "空き容量と権限を確認してください",
+ "identity": "ディレクトリの確認が必要",
+ "failed": "クリーンアップ未完了",
+ "pending": "待機中"
+ }
}
},
"remoteDevice": {
diff --git a/apps/desktop/src/renderer/i18n/locales/ko/common.json b/apps/desktop/src/renderer/i18n/locales/ko/common.json
index e1b2442b3c..7b05bc428e 100644
--- a/apps/desktop/src/renderer/i18n/locales/ko/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ko/common.json
@@ -5771,6 +5771,31 @@
"versions": "버전 관리",
"environment": "환경 준비"
}
+ },
+ "worktreeRecycle": {
+ "title": "worktree 정리",
+ "refresh": "새로 고침",
+ "empty": "정리 대기 중인 worktree가 없습니다",
+ "loadFailed": "정리 상태를 불러오지 못했습니다",
+ "actionFailed": "상태를 업데이트하지 못했습니다. 새로 고침 후 다시 시도하세요",
+ "retry": "정리 재시도",
+ "keep": "디렉터리 유지",
+ "state": {
+ "retrying": "정리 대기 중",
+ "waiting": "사용 종료 대기 중",
+ "paused": "자동 재시도 일시 중지",
+ "kept": "디렉터리 유지됨"
+ },
+ "reason": {
+ "in-use": "사용 중",
+ "changed": "내용이 변경됨",
+ "kept": "유지 요청됨",
+ "integrity": "백업 검증 실패",
+ "storage": "디스크 공간과 권한을 확인하세요",
+ "identity": "디렉터리 확인 필요",
+ "failed": "정리를 완료하지 못함",
+ "pending": "대기 중"
+ }
}
},
"remoteDevice": {
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
index c43ac3905d..94d721c561 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
@@ -5771,6 +5771,31 @@
"versions": "版本控制",
"environment": "环境准备"
}
+ },
+ "worktreeRecycle": {
+ "title": "worktree 回收",
+ "refresh": "刷新",
+ "empty": "没有等待回收的 worktree",
+ "loadFailed": "无法读取回收状态",
+ "actionFailed": "未能更新回收状态,请刷新后重试",
+ "retry": "重试回收",
+ "keep": "保留目录",
+ "state": {
+ "retrying": "等待回收",
+ "waiting": "等待释放",
+ "paused": "已暂停自动重试",
+ "kept": "已保留目录"
+ },
+ "reason": {
+ "in-use": "仍在使用",
+ "changed": "文件内容已变化",
+ "kept": "已要求保留",
+ "integrity": "备份校验失败",
+ "storage": "请检查磁盘空间和权限",
+ "identity": "目录身份需要检查",
+ "failed": "回收未能完成",
+ "pending": "已排队"
+ }
}
},
"remoteDevice": {
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
index a2156dd23d..8b3212914c 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
@@ -5771,6 +5771,31 @@
"versions": "版本控制",
"environment": "環境準備"
}
+ },
+ "worktreeRecycle": {
+ "title": "worktree 回收",
+ "refresh": "重新整理",
+ "empty": "沒有等待回收的 worktree",
+ "loadFailed": "無法讀取回收狀態",
+ "actionFailed": "未能更新回收狀態,請重新整理後再試",
+ "retry": "重試回收",
+ "keep": "保留目錄",
+ "state": {
+ "retrying": "等待回收",
+ "waiting": "等待釋放",
+ "paused": "已暫停自動重試",
+ "kept": "已保留目錄"
+ },
+ "reason": {
+ "in-use": "仍在使用",
+ "changed": "檔案內容已變更",
+ "kept": "已要求保留",
+ "integrity": "備份驗證失敗",
+ "storage": "請檢查磁碟空間和權限",
+ "identity": "目錄身分需要檢查",
+ "failed": "回收未能完成",
+ "pending": "已排入佇列"
+ }
}
},
"remoteDevice": {
diff --git a/apps/desktop/src/renderer/vite-env.d.ts b/apps/desktop/src/renderer/vite-env.d.ts
index 20efdf8245..bb4c225634 100644
--- a/apps/desktop/src/renderer/vite-env.d.ts
+++ b/apps/desktop/src/renderer/vite-env.d.ts
@@ -3676,6 +3676,10 @@ interface ElectronAPI {
/** Delete the files referenced by the given xdt-image:// URLs. */
cleanupCachedImages: (urls: string[]) => Promise<void>;
+ worktreeRecycle: {
+ list(): Promise<import('../shared/worktreeRecycle').WorktreeRecycleStatus[]>;
+ control(input: import('../shared/worktreeRecycle').WorktreeRecycleAction): Promise<void>;
+ };
/**
* 媒体总仓存储管理(关于页存储空间卡片):占用统计 / 清理
* 预检(报数)/ 执行清理 / 对账体检。draftUrls 由 renderer 从
diff --git a/apps/desktop/src/shared/worktreeRecycle.ts b/apps/desktop/src/shared/worktreeRecycle.ts
new file mode 100644
index 0000000000..e4739668b9
--- /dev/null
+++ b/apps/desktop/src/shared/worktreeRecycle.ts
@@ -0,0 +1,15 @@
+/** Local device storage controls; not a remote-workspace filesystem API. */
+export interface WorktreeRecycleStatus {
+ id: string;
+ generation: string;
+ name: string;
+ path: string;
+ state: 'retrying' | 'waiting' | 'paused' | 'kept';
+ failures: number;
+ reason: 'in-use' | 'changed' | 'kept' | 'integrity' | 'storage' | 'identity' | 'failed' | 'pending';
+}
+export interface WorktreeRecycleAction {
+ id: string;
+ generation: string;
+ action: 'retry' | 'keep';
+}
diff --git a/docs/design-rules/design-inventory.md b/docs/design-rules/design-inventory.md
index baa2d57e30..a4d8aa1bdc 100644
--- a/docs/design-rules/design-inventory.md
+++ b/docs/design-rules/design-inventory.md
@@ -38,7 +38,7 @@
| `desktop.overlay.toast` | desktop | Toast | App 常驻 ToastContainer(用户可见出口,不展开业务逻辑) | Toast, ToastContainer | apps/desktop/src/renderer/components/ui/toast/Toast.tsx, apps/desktop/src/renderer/components/ui/toast/ToastContainer.tsx, apps/desktop/src/renderer/components/ui/toast/index.ts | 8 | 4 | 4 |
| `desktop.plugins.app-main` | desktop | 插件主视图 | hash `/apps/:ghostId`(GhostMainViewFeatureLayout) | GhostMainViewFeatureLayout, GhostMainViewHost | apps/desktop/src/renderer/features/plugin/GhostMainViewFeatureLayout.tsx, apps/desktop/src/renderer/features/plugin/GhostMainViewHost.tsx | 0 | 0 | 0 |
| `desktop.plugins.installed` | desktop | 已装插件 | hash `/plugins`(GhostPluginPage) | AddMarketplaceDialog, GhostPluginDetailView, GhostPluginPage, MarketPluginDetailView, MyPublishesSection, PluginManagementLayout, PluginScopePicker, UpdateAllDialog | apps/desktop/src/renderer/features/plugin/AddMarketplaceDialog.tsx, apps/desktop/src/renderer/features/plugin/GhostPluginDetailView.tsx, apps/desktop/src/renderer/features/plugin/GhostPluginPage.tsx, apps/desktop/src/renderer/features/plugin/MarketPluginDetailView.tsx, apps/desktop/src/renderer/features/plugin/MyPublishesSection.tsx, apps/desktop/src/renderer/features/plugin/PluginManagementLayout.tsx, apps/desktop/src/renderer/features/plugin/PluginScopePicker.tsx, apps/desktop/src/renderer/features/plugin/UpdateAllDialog.tsx, apps/desktop/src/renderer/features/plugin/plugin-motion.css | 49 | 0 | 82 |
-| `desktop.settings` | desktop | 设置 | hash `/settings`(SettingsView;tab 含 general / personalization / providers / billing / usage / voice-input / im-bot / shortcuts / agent-island / import / remote-control / ghosts / builtin-tools / computer-use / help / about) | SettingsView | apps/desktop/src/renderer/components/settings/AboutSection.tsx, apps/desktop/src/renderer/components/settings/AccountDeletionSection.tsx, apps/desktop/src/renderer/components/settings/AddProviderWizard.tsx, apps/desktop/src/renderer/components/settings/AgentIslandSection.tsx, apps/desktop/src/renderer/components/settings/AgentResourceSection.tsx, apps/desktop/src/renderer/components/settings/AppearanceSection.tsx, apps/desktop/src/renderer/components/settings/AuxiliaryModelSection.tsx, apps/desktop/src/renderer/components/settings/BetaChannelCell.tsx, apps/desktop/src/renderer/components/settings/BrowserBackendSubsection.tsx, apps/desktop/src/renderer/components/settings/BrowserRealProfileSubsection.tsx, apps/desktop/src/renderer/components/settings/BuiltinToolsSection.tsx, apps/desktop/src/renderer/components/settings/ChatEmbeddingCell.tsx, apps/desktop/src/renderer/components/settings/ChipMetricsSection.tsx, apps/desktop/src/renderer/components/settings/CindyMakeSection.tsx, apps/desktop/src/renderer/components/settings/CollaborationSection.tsx, apps/desktop/src/renderer/components/settings/CompactionSection.tsx, apps/desktop/src/renderer/components/settings/ComposerSendShortcutSection.tsx, apps/desktop/src/renderer/components/settings/ComputerPermissionGuideWindow.tsx, apps/desktop/src/renderer/components/settings/ComputerPermissionRow.tsx, apps/desktop/src/renderer/components/settings/ComputerUseSection.tsx, apps/desktop/src/renderer/components/settings/CustomProviderRuntimeFillOverlay.tsx, apps/desktop/src/renderer/components/settings/DefaultOverrideControls.tsx, apps/desktop/src/renderer/components/settings/DingTalkBotSection.tsx, apps/desktop/src/renderer/components/settings/DiscordBotSection.tsx, apps/desktop/src/renderer/components/settings/DownloadMeter.tsx, apps/desktop/src/renderer/components/settings/ExperimentalSection.tsx, apps/desktop/src/renderer/components/settings/FeishuBotNotificationSection.tsx, apps/desktop/src/renderer/components/settings/FeishuBotSection.tsx, apps/desktop/src/renderer/components/settings/FontFamilyPicker.tsx, apps/desktop/src/renderer/components/settings/GenericGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/GitSafetySection.tsx, apps/desktop/src/renderer/components/settings/HelpAssistantPanel.tsx, apps/desktop/src/renderer/components/settings/HelpSection.tsx, apps/desktop/src/renderer/components/settings/HelpThreadView.tsx, apps/desktop/src/renderer/components/settings/HookConnectionsSection.tsx, apps/desktop/src/renderer/components/settings/HookWorkspacePrefsEditor.tsx, apps/desktop/src/renderer/components/settings/ImBotSection.tsx, apps/desktop/src/renderer/components/settings/ImChannelSettingsCard.tsx, apps/desktop/src/renderer/components/settings/ImDefaultSettingsSection.tsx, apps/desktop/src/renderer/components/settings/ImLifecycleAnnouncementSection.tsx, apps/desktop/src/renderer/components/settings/InputDeviceConnectionStatus.tsx, apps/desktop/src/renderer/components/settings/JoyConGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/KeyboardShortcutsSection.tsx, apps/desktop/src/renderer/components/settings/LanguageSection.tsx, apps/desktop/src/renderer/components/settings/LayoutResetControl.tsx, apps/desktop/src/renderer/components/settings/LinkOpenSection.tsx, apps/desktop/src/renderer/components/settings/LocalOllamaInstall.tsx, apps/desktop/src/renderer/components/settings/LocalPackagingTag.tsx, apps/desktop/src/renderer/components/settings/LogoutSection.tsx, apps/desktop/src/renderer/components/settings/LspBetaCell.tsx, apps/desktop/src/renderer/components/settings/McpServerDialog.tsx, apps/desktop/src/renderer/components/settings/McpServersSection.tsx, apps/desktop/src/renderer/components/settings/MemorySection.tsx, apps/desktop/src/renderer/components/settings/MessageNavRailCell.tsx, apps/desktop/src/renderer/components/settings/ModelAdvancedDrawer.tsx, apps/desktop/src/renderer/components/settings/ModelPriceOverrideDialog.tsx, apps/desktop/src/renderer/components/settings/MyDevicesPanel.tsx, apps/desktop/src/renderer/components/settings/NotificationSection.tsx, apps/desktop/src/renderer/components/settings/OAuthDeviceCodeCard.tsx, apps/desktop/src/renderer/components/settings/OllamaProviderDetail.tsx, apps/desktop/src/renderer/components/settings/PiPackagesSection.tsx, apps/desktop/src/renderer/components/settings/PlayStationGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/ProfileEditDialog.tsx, apps/desktop/src/renderer/components/settings/ProviderConnectionDialog.tsx, apps/desktop/src/renderer/components/settings/ProviderImportDialog.tsx, apps/desktop/src/renderer/components/settings/ProvidersSection.tsx, apps/desktop/src/renderer/components/settings/RemoteControlSection.tsx, apps/desktop/src/renderer/components/settings/RemoteDesktopPermissions.tsx, apps/desktop/src/renderer/components/settings/RemoteDesktopSetting.tsx, apps/desktop/src/renderer/components/settings/RemoteHostDetail.tsx, apps/desktop/src/renderer/components/settings/RemoteSection.tsx, apps/desktop/src/renderer/components/settings/SessionImportSection.tsx, apps/desktop/src/renderer/components/settings/SessionRuntimeFallbackCell.tsx, apps/desktop/src/renderer/components/settings/SessionShareImportWizard.tsx, apps/desktop/src/renderer/components/settings/SettingsCatalogPanel.tsx, apps/desktop/src/renderer/components/settings/SettingsSegmentedControl.tsx, apps/desktop/src/renderer/components/settings/SettingsSidebarNav.tsx, apps/desktop/src/renderer/components/settings/SettingsTextInput.tsx, apps/desktop/src/renderer/components/settings/SettingsView.tsx, apps/desktop/src/renderer/components/settings/SilentEncryptedRetryCell.tsx, apps/desktop/src/renderer/components/settings/SshKeySetupDialog.tsx, apps/desktop/src/renderer/components/settings/StorageManagementCard.tsx, apps/desktop/src/renderer/components/settings/StreamFadeSection.tsx, apps/desktop/src/renderer/components/settings/SubagentModelSection.tsx, apps/desktop/src/renderer/components/settings/SwitchProGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/TelegramBehaviorSettings.tsx, apps/desktop/src/renderer/components/settings/TelegramBotSection.tsx, apps/desktop/src/renderer/components/settings/TelegramRemoteDevices.tsx, apps/desktop/src/renderer/components/settings/TerminalShellSection.tsx, apps/desktop/src/renderer/components/settings/TipsSection.tsx, apps/desktop/src/renderer/components/settings/UnifiedModelList.tsx, apps/desktop/src/renderer/components/settings/UserProfileCard.tsx, apps/desktop/src/renderer/components/settings/UserPromptSection.tsx, apps/desktop/src/renderer/components/settings/VisionBridgeSection.tsx, apps/desktop/src/renderer/components/settings/VoiceInputSection.tsx, apps/desktop/src/renderer/components/settings/WechatBotSection.tsx, apps/desktop/src/renderer/components/settings/WecomBotSection.tsx, apps/desktop/src/renderer/components/settings/WindowBehaviorSection.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexKeyboardLayout.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexKeycapGlyphs.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexSettings.tsx, apps/desktop/src/renderer/components/settings/XUsageGuide.tsx, apps/desktop/src/renderer/components/settings/XboxGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/XboxGamepadSettings.tsx, apps/desktop/src/renderer/components/settings/androidStatusPresentation.ts, apps/desktop/src/renderer/components/settings/billingVisibility.ts, apps/desktop/src/renderer/components/settings/browserOpenForLoginError.ts, apps/desktop/src/renderer/components/settings/cindyMakeVisibility.ts, apps/desktop/src/renderer/components/settings/computerPermissionFlow.ts, apps/desktop/src/renderer/components/settings/contacts/ContactDetailPane.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsImportDialog.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsListPane.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsManagerDialog.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsSection.tsx, apps/desktop/src/renderer/components/settings/contacts/startContactsAiSession.ts, apps/desktop/src/renderer/components/settings/dualSenseSilhouette.ts, apps/desktop/src/renderer/components/settings/feishuBotPresentation.ts, apps/desktop/src/renderer/components/settings/fontFamilyValue.ts, apps/desktop/src/renderer/components/settings/gamepadLayoutPrimitives.tsx, apps/desktop/src/renderer/components/settings/gamepadSilhouetteGeom.ts, apps/desktop/src/renderer/components/settings/hookWorkspacePrefsLogic.ts, apps/desktop/src/renderer/components/settings/imBotVisibility.ts, apps/desktop/src/renderer/components/settings/imDefaultSettingsLogic.ts, apps/desktop/src/renderer/components/settings/joyConSilhouette.ts, apps/desktop/src/renderer/components/settings/modelManagementPresentation.ts, apps/desktop/src/renderer/components/settings/modelManagementState.ts, apps/desktop/src/renderer/components/settings/myDevicesModel.ts, apps/desktop/src/renderer/components/settings/providerAssetModule.ts, apps/desktop/src/renderer/components/settings/realProfilePermissionGuide.ts, apps/desktop/src/renderer/components/settings/switchProSilhouette.ts, apps/desktop/src/renderer/components/settings/ultimateC1Silhouette.ts, apps/desktop/src/renderer/components/settings/usage/UsageBreakdownTables.tsx, apps/desktop/src/renderer/components/settings/usage/UsageHistorySection.tsx, apps/desktop/src/renderer/components/settings/usage/UsageStatRow.tsx, apps/desktop/src/renderer/components/settings/usage/UsageTaskTable.tsx, apps/desktop/src/renderer/components/settings/usage/UsageTokenBars.tsx, apps/desktop/src/renderer/components/settings/usage/formatUsagePercent.ts, apps/desktop/src/renderer/components/settings/usage/usageCharts.css, apps/desktop/src/renderer/components/settings/usage/usageHistoryColors.ts, apps/desktop/src/renderer/components/settings/usage/usageHistoryStats.ts, apps/desktop/src/renderer/components/settings/usageVisibility.ts, apps/desktop/src/renderer/components/settings/useProviderSubscriptionCard.ts, apps/desktop/src/renderer/components/settings/wizardRecommend.ts, apps/desktop/src/renderer/components/settings/workLouderCodexCommandCopy.ts, apps/desktop/src/renderer/components/settings/xboxSeriesSilhouette.ts, apps/desktop/src/renderer/styles/sortable.css | 154 | 109 | 734 |
+| `desktop.settings` | desktop | 设置 | hash `/settings`(SettingsView;tab 含 general / personalization / providers / billing / usage / voice-input / im-bot / shortcuts / agent-island / import / remote-control / ghosts / builtin-tools / computer-use / help / about) | SettingsView | apps/desktop/src/renderer/components/settings/AboutSection.tsx, apps/desktop/src/renderer/components/settings/AccountDeletionSection.tsx, apps/desktop/src/renderer/components/settings/AddProviderWizard.tsx, apps/desktop/src/renderer/components/settings/AgentIslandSection.tsx, apps/desktop/src/renderer/components/settings/AgentResourceSection.tsx, apps/desktop/src/renderer/components/settings/AppearanceSection.tsx, apps/desktop/src/renderer/components/settings/AuxiliaryModelSection.tsx, apps/desktop/src/renderer/components/settings/BetaChannelCell.tsx, apps/desktop/src/renderer/components/settings/BrowserBackendSubsection.tsx, apps/desktop/src/renderer/components/settings/BrowserRealProfileSubsection.tsx, apps/desktop/src/renderer/components/settings/BuiltinToolsSection.tsx, apps/desktop/src/renderer/components/settings/ChatEmbeddingCell.tsx, apps/desktop/src/renderer/components/settings/ChipMetricsSection.tsx, apps/desktop/src/renderer/components/settings/CindyMakeSection.tsx, apps/desktop/src/renderer/components/settings/CollaborationSection.tsx, apps/desktop/src/renderer/components/settings/CompactionSection.tsx, apps/desktop/src/renderer/components/settings/ComposerSendShortcutSection.tsx, apps/desktop/src/renderer/components/settings/ComputerPermissionGuideWindow.tsx, apps/desktop/src/renderer/components/settings/ComputerPermissionRow.tsx, apps/desktop/src/renderer/components/settings/ComputerUseSection.tsx, apps/desktop/src/renderer/components/settings/CustomProviderRuntimeFillOverlay.tsx, apps/desktop/src/renderer/components/settings/DefaultOverrideControls.tsx, apps/desktop/src/renderer/components/settings/DingTalkBotSection.tsx, apps/desktop/src/renderer/components/settings/DiscordBotSection.tsx, apps/desktop/src/renderer/components/settings/DownloadMeter.tsx, apps/desktop/src/renderer/components/settings/ExperimentalSection.tsx, apps/desktop/src/renderer/components/settings/FeishuBotNotificationSection.tsx, apps/desktop/src/renderer/components/settings/FeishuBotSection.tsx, apps/desktop/src/renderer/components/settings/FontFamilyPicker.tsx, apps/desktop/src/renderer/components/settings/GenericGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/GitSafetySection.tsx, apps/desktop/src/renderer/components/settings/HelpAssistantPanel.tsx, apps/desktop/src/renderer/components/settings/HelpSection.tsx, apps/desktop/src/renderer/components/settings/HelpThreadView.tsx, apps/desktop/src/renderer/components/settings/HookConnectionsSection.tsx, apps/desktop/src/renderer/components/settings/HookWorkspacePrefsEditor.tsx, apps/desktop/src/renderer/components/settings/ImBotSection.tsx, apps/desktop/src/renderer/components/settings/ImChannelSettingsCard.tsx, apps/desktop/src/renderer/components/settings/ImDefaultSettingsSection.tsx, apps/desktop/src/renderer/components/settings/ImLifecycleAnnouncementSection.tsx, apps/desktop/src/renderer/components/settings/InputDeviceConnectionStatus.tsx, apps/desktop/src/renderer/components/settings/JoyConGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/KeyboardShortcutsSection.tsx, apps/desktop/src/renderer/components/settings/LanguageSection.tsx, apps/desktop/src/renderer/components/settings/LayoutResetControl.tsx, apps/desktop/src/renderer/components/settings/LinkOpenSection.tsx, apps/desktop/src/renderer/components/settings/LocalOllamaInstall.tsx, apps/desktop/src/renderer/components/settings/LocalPackagingTag.tsx, apps/desktop/src/renderer/components/settings/LogoutSection.tsx, apps/desktop/src/renderer/components/settings/LspBetaCell.tsx, apps/desktop/src/renderer/components/settings/McpServerDialog.tsx, apps/desktop/src/renderer/components/settings/McpServersSection.tsx, apps/desktop/src/renderer/components/settings/MemorySection.tsx, apps/desktop/src/renderer/components/settings/MessageNavRailCell.tsx, apps/desktop/src/renderer/components/settings/ModelAdvancedDrawer.tsx, apps/desktop/src/renderer/components/settings/ModelPriceOverrideDialog.tsx, apps/desktop/src/renderer/components/settings/MyDevicesPanel.tsx, apps/desktop/src/renderer/components/settings/NotificationSection.tsx, apps/desktop/src/renderer/components/settings/OAuthDeviceCodeCard.tsx, apps/desktop/src/renderer/components/settings/OllamaProviderDetail.tsx, apps/desktop/src/renderer/components/settings/PiPackagesSection.tsx, apps/desktop/src/renderer/components/settings/PlayStationGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/ProfileEditDialog.tsx, apps/desktop/src/renderer/components/settings/ProviderConnectionDialog.tsx, apps/desktop/src/renderer/components/settings/ProviderImportDialog.tsx, apps/desktop/src/renderer/components/settings/ProvidersSection.tsx, apps/desktop/src/renderer/components/settings/RemoteControlSection.tsx, apps/desktop/src/renderer/components/settings/RemoteDesktopPermissions.tsx, apps/desktop/src/renderer/components/settings/RemoteDesktopSetting.tsx, apps/desktop/src/renderer/components/settings/RemoteHostDetail.tsx, apps/desktop/src/renderer/components/settings/RemoteSection.tsx, apps/desktop/src/renderer/components/settings/SessionImportSection.tsx, apps/desktop/src/renderer/components/settings/SessionRuntimeFallbackCell.tsx, apps/desktop/src/renderer/components/settings/SessionShareImportWizard.tsx, apps/desktop/src/renderer/components/settings/SettingsCatalogPanel.tsx, apps/desktop/src/renderer/components/settings/SettingsSegmentedControl.tsx, apps/desktop/src/renderer/components/settings/SettingsSidebarNav.tsx, apps/desktop/src/renderer/components/settings/SettingsTextInput.tsx, apps/desktop/src/renderer/components/settings/SettingsView.tsx, apps/desktop/src/renderer/components/settings/SilentEncryptedRetryCell.tsx, apps/desktop/src/renderer/components/settings/SshKeySetupDialog.tsx, apps/desktop/src/renderer/components/settings/StorageManagementCard.tsx, apps/desktop/src/renderer/components/settings/StreamFadeSection.tsx, apps/desktop/src/renderer/components/settings/SubagentModelSection.tsx, apps/desktop/src/renderer/components/settings/SwitchProGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/TelegramBehaviorSettings.tsx, apps/desktop/src/renderer/components/settings/TelegramBotSection.tsx, apps/desktop/src/renderer/components/settings/TelegramRemoteDevices.tsx, apps/desktop/src/renderer/components/settings/TerminalShellSection.tsx, apps/desktop/src/renderer/components/settings/TipsSection.tsx, apps/desktop/src/renderer/components/settings/UnifiedModelList.tsx, apps/desktop/src/renderer/components/settings/UserProfileCard.tsx, apps/desktop/src/renderer/components/settings/UserPromptSection.tsx, apps/desktop/src/renderer/components/settings/VisionBridgeSection.tsx, apps/desktop/src/renderer/components/settings/VoiceInputSection.tsx, apps/desktop/src/renderer/components/settings/WechatBotSection.tsx, apps/desktop/src/renderer/components/settings/WecomBotSection.tsx, apps/desktop/src/renderer/components/settings/WindowBehaviorSection.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexKeyboardLayout.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexKeycapGlyphs.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexSettings.tsx, apps/desktop/src/renderer/components/settings/WorktreeRecycleCard.tsx, apps/desktop/src/renderer/components/settings/XUsageGuide.tsx, apps/desktop/src/renderer/components/settings/XboxGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/XboxGamepadSettings.tsx, apps/desktop/src/renderer/components/settings/androidStatusPresentation.ts, apps/desktop/src/renderer/components/settings/billingVisibility.ts, apps/desktop/src/renderer/components/settings/browserOpenForLoginError.ts, apps/desktop/src/renderer/components/settings/cindyMakeVisibility.ts, apps/desktop/src/renderer/components/settings/computerPermissionFlow.ts, apps/desktop/src/renderer/components/settings/contacts/ContactDetailPane.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsImportDialog.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsListPane.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsManagerDialog.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsSection.tsx, apps/desktop/src/renderer/components/settings/contacts/startContactsAiSession.ts, apps/desktop/src/renderer/components/settings/dualSenseSilhouette.ts, apps/desktop/src/renderer/components/settings/feishuBotPresentation.ts, apps/desktop/src/renderer/components/settings/fontFamilyValue.ts, apps/desktop/src/renderer/components/settings/gamepadLayoutPrimitives.tsx, apps/desktop/src/renderer/components/settings/gamepadSilhouetteGeom.ts, apps/desktop/src/renderer/components/settings/hookWorkspacePrefsLogic.ts, apps/desktop/src/renderer/components/settings/imBotVisibility.ts, apps/desktop/src/renderer/components/settings/imDefaultSettingsLogic.ts, apps/desktop/src/renderer/components/settings/joyConSilhouette.ts, apps/desktop/src/renderer/components/settings/modelManagementPresentation.ts, apps/desktop/src/renderer/components/settings/modelManagementState.ts, apps/desktop/src/renderer/components/settings/myDevicesModel.ts, apps/desktop/src/renderer/components/settings/providerAssetModule.ts, apps/desktop/src/renderer/components/settings/realProfilePermissionGuide.ts, apps/desktop/src/renderer/components/settings/switchProSilhouette.ts, apps/desktop/src/renderer/components/settings/ultimateC1Silhouette.ts, apps/desktop/src/renderer/components/settings/usage/UsageBreakdownTables.tsx, apps/desktop/src/renderer/components/settings/usage/UsageHistorySection.tsx, apps/desktop/src/renderer/components/settings/usage/UsageStatRow.tsx, apps/desktop/src/renderer/components/settings/usage/UsageTaskTable.tsx, apps/desktop/src/renderer/components/settings/usage/UsageTokenBars.tsx, apps/desktop/src/renderer/components/settings/usage/formatUsagePercent.ts, apps/desktop/src/renderer/components/settings/usage/usageCharts.css, apps/desktop/src/renderer/components/settings/usage/usageHistoryColors.ts, apps/desktop/src/renderer/components/settings/usage/usageHistoryStats.ts, apps/desktop/src/renderer/components/settings/usageVisibility.ts, apps/desktop/src/renderer/components/settings/useProviderSubscriptionCard.ts, apps/desktop/src/renderer/components/settings/wizardRecommend.ts, apps/desktop/src/renderer/components/settings/workLouderCodexCommandCopy.ts, apps/desktop/src/renderer/components/settings/xboxSeriesSilhouette.ts, apps/desktop/src/renderer/styles/sortable.css | 154 | 109 | 735 |
| `desktop.shell.main-layout` | desktop | 主窗口壳(标题栏 / 左右栏 / 内容区) | main BrowserWindow → renderer/index.tsx → main-entry.tsx → App → MainLayout (`#/` 受保护壳) | ChromeActions, DeviceSectionHeader, FeishuConflictDialogHost, GhostMediaLightboxHost, MainLayout, ProjectsSection, RightSidebar, RightSidebarShell, SessionShareImportWizard, Sidebar, UpdateNoticeDialog, WindowControls | apps/desktop/src/renderer/cindy-brain/GhostMediaLightboxHost.tsx, apps/desktop/src/renderer/components/UpdateNoticeDialog.tsx, apps/desktop/src/renderer/components/feishuBot/FeishuConflictDialog.tsx, apps/desktop/src/renderer/components/feishuBot/FeishuConflictDialogHost.tsx, apps/desktop/src/renderer/components/layout/AppBadgeAttentionSync.tsx, apps/desktop/src/renderer/components/layout/BrowserWebviewPool.tsx, apps/desktop/src/renderer/components/layout/ChromeActions.tsx, apps/desktop/src/renderer/components/layout/ContentHeader.tsx, apps/desktop/src/renderer/components/layout/CredentialStoreBanner.tsx, apps/desktop/src/renderer/components/layout/FadeSwitcher.tsx, apps/desktop/src/renderer/components/layout/GhostPanelWindowLayout.tsx, apps/desktop/src/renderer/components/layout/GlobalDropImportListener.tsx, apps/desktop/src/renderer/components/layout/MainEntryRedirect.tsx, apps/desktop/src/renderer/components/layout/MainLayout.tsx, apps/desktop/src/renderer/components/layout/RightSidebar.tsx, apps/desktop/src/renderer/components/layout/RightSidebarDetach.tsx, apps/desktop/src/renderer/components/layout/RightSidebarMaximize.tsx, apps/desktop/src/renderer/components/layout/RightSidebarToggle.tsx, apps/desktop/src/renderer/components/layout/SidebarWindowLayout.tsx, apps/desktop/src/renderer/components/layout/chromeActionsGeometry.ts, apps/desktop/src/renderer/components/layout/chromeActionsLayout.ts, apps/desktop/src/renderer/components/layout/railChromeActions.ts, apps/desktop/src/renderer/components/layout/windowDrag.tsx, apps/desktop/src/renderer/components/settings/SessionShareImportWizard.tsx, apps/desktop/src/renderer/components/sidebar/AccountSwitcherDialog.tsx, apps/desktop/src/renderer/components/sidebar/AttentionDot.tsx, apps/desktop/src/renderer/components/sidebar/DatabaseSizeWarningBanner.tsx, apps/desktop/src/renderer/components/sidebar/GhostMainViewNavEntries.tsx, apps/desktop/src/renderer/components/sidebar/MobileDownloadDialog.tsx, apps/desktop/src/renderer/components/sidebar/Sidebar.tsx, apps/desktop/src/renderer/components/sidebar/SidebarIconButton.tsx, apps/desktop/src/renderer/components/sidebar/SidebarTopNav.tsx, apps/desktop/src/renderer/components/sidebar/SortableList.tsx, apps/desktop/src/renderer/components/sidebar/UpdateBanner.tsx, apps/desktop/src/renderer/components/sidebar/UserInfoSection.tsx, apps/desktop/src/renderer/components/sidebar/VendorIcon.tsx, apps/desktop/src/renderer/components/sidebar/VendorReadinessBadge.tsx, apps/desktop/src/renderer/components/sidebar/WorktreeBadge.tsx, apps/desktop/src/renderer/components/title-bar/ChromeIconButton.tsx, apps/desktop/src/renderer/components/title-bar/MenuButton.tsx, apps/desktop/src/renderer/components/title-bar/WindowControls.tsx, apps/desktop/src/renderer/features/cc-agent/sidebar/DeviceSectionHeader.tsx, apps/desktop/src/renderer/features/cc-agent/sidebar/sections/ProjectsSection.tsx, apps/desktop/src/renderer/features/right-sidebar/AddTabDropdown.tsx, apps/desktop/src/renderer/features/right-sidebar/EmptyState.tsx, apps/desktop/src/renderer/features/right-sidebar/RightSidebarShell.tsx, apps/desktop/src/renderer/features/right-sidebar/TabBar.tsx, apps/desktop/src/renderer/features/right-sidebar/TabBodyErrorBoundary.tsx, apps/desktop/src/renderer/features/right-sidebar/hooks/useBrowserWebview.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useNativePopupSurface.ts, apps/desktop/src/renderer/features/right-sidebar/iosSimulatorPluginAvailability.ts, apps/desktop/src/renderer/features/right-sidebar/lib/browserPartition.ts, apps/desktop/src/renderer/features/right-sidebar/lib/browserWebviewPool.ts, apps/desktop/src/renderer/features/right-sidebar/lib/detachedSidebarRouting.ts, apps/desktop/src/renderer/features/right-sidebar/lib/executeSidebarCommand.ts, apps/desktop/src/renderer/features/right-sidebar/lib/iosSimulatorFocusBridge.ts, apps/desktop/src/renderer/features/right-sidebar/lib/lastTurnChangedFiles.ts, apps/desktop/src/renderer/features/right-sidebar/lib/nativePopupTabs.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openBackgroundTasksTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openInSidebarBrowser.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openInSidebarFileBrowser.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openRoutinesTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openSubagentsTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openTerminalShortcut.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openTurnReview.ts, apps/desktop/src/renderer/features/right-sidebar/lib/popupRouter.ts, apps/desktop/src/renderer/features/right-sidebar/lib/popupTabs.ts, apps/desktop/src/renderer/features/right-sidebar/lib/rsbBrowserBridge.ts, apps/desktop/src/renderer/features/right-sidebar/lib/sidebarCommands.ts, apps/desktop/src/renderer/features/right-sidebar/lib/sidebarHostSession.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/BackgroundTasksBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/WorkflowAgentStrip.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/WorkflowProgressTree.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/chatTaskFocusIntent.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/listSessionTasks.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/workflowProgressModel.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/cindy-make/CindyMakeTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/cindy-make/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.css, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/dropExternalFile.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/fileTreeImagePreview.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/useSessionScopedTreeWidth.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/index.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/ios-simulator/IOSSimulatorInstanceGrid.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/ios-simulator/IOSSimulatorTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/ios-simulator/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/ios-simulator/iosSimulatorH264Decoder.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/OrcaWorkersAttentionIcon.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/OrcaWorkersTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/actions.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/closeDecision.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/ResourceUsageBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/resource-usage.css, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/subscription.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/ImageDiffPreview.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/MarkdownDiffPreview.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/PlainUnifiedDiff.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/diffRows.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/highlight.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/inlineDiff.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/useDiffHighlights.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/ReviewTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/diffExpansionPreference.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/fileTree.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/gitApplyCommand.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/markdownPreview.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useLastTurnFilter.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useReviewGitState.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useReviewSource.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/routines/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/ConversationStream.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/DetailView.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/RunList.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentChrome.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentToolCard.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentsBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentChangeFence.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentConversation.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentFormat.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/TerminalTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/lib/xtermPool.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserChrome.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserCommentPopover.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/browserCommentEditorDraft.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/lib/parseOmnibox.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/useBrowserComment.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/useLocalHtmlAutoReload.ts, apps/desktop/src/renderer/features/right-sidebar/registry.ts, apps/desktop/src/renderer/features/right-sidebar/store.ts, apps/desktop/src/renderer/features/right-sidebar/types.ts, apps/desktop/src/renderer/layout/LayoutRoot.tsx, apps/desktop/src/renderer/layout/PanelDragController.tsx, apps/desktop/src/renderer/layout/PanelDragPrototype.tsx, apps/desktop/src/renderer/layout/collapsePrefs.ts, apps/desktop/src/renderer/layout/layoutDevTools.ts, apps/desktop/src/renderer/layout/panePlacement.tsx, apps/desktop/src/renderer/layout/paneWidths.tsx, apps/desktop/src/renderer/layout/panelMaximize.tsx, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css | 153 | 46 | 297 |
| `desktop.skillhub.local` | desktop | SkillHub 本地技能 | hash `/skillhub/local` 及详情 `/skillhub/local/:kind/global/:name`、`/skillhub/local/:kind/project/:projectHash/:name` | InstallTargetPicker, PluginManagementLayout, SkillhubDetailView, SkillhubFeatureLayout, SkillhubHomeView, SkillhubMarketPreviewPanel | apps/desktop/src/renderer/features/plugin/PluginManagementLayout.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubDetailView.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubFeatureLayout.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubHomeView.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubMarketPreviewPanel.tsx, apps/desktop/src/renderer/features/skillhub/components/InstallTargetPicker.tsx | 46 | 0 | 66 |
| `desktop.skillhub.market` | desktop | SkillHub 市场 | hash `/skillhub/market`(SkillhubMarketListView) | InstallTargetPicker, MarketCard, MarketInfoEditDialog, SkillhubMarketListView, SkillhubMarketPreviewPanel, VisibilityEditorDialog | apps/desktop/src/renderer/features/skillhub/SkillhubMarketListView.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubMarketPreviewPanel.tsx, apps/desktop/src/renderer/features/skillhub/components/HomeMarketCard.tsx, apps/desktop/src/renderer/features/skillhub/components/InstallTargetPicker.tsx, apps/desktop/src/renderer/features/skillhub/components/LocalSkillControls.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketCard.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketInfoEditDialog.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketLocalSkills.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketPreviewTree.tsx, apps/desktop/src/renderer/features/skillhub/components/PlatformTagSelector.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillCategoryFilterBar.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillIcon.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillTagList.tsx, apps/desktop/src/renderer/features/skillhub/components/TeamScopePicker.tsx, apps/desktop/src/renderer/features/skillhub/components/VisibilityEditorDialog.tsx | 52 | 0 | 63 |
diff --git a/docs/dev-rules/worktree-recycle-boundaries.md b/docs/dev-rules/worktree-recycle-boundaries.md
new file mode 100644
index 0000000000..afe10350a1
--- /dev/null
+++ b/docs/dev-rules/worktree-recycle-boundaries.md
@@ -0,0 +1,30 @@
+# 本机 worktree 回收的执行边界
+
+归档只产生回收意图,不授权绕过活引用、物理目录身份、Git 身份或恢复证据检查。回收失败保留原目录和已经生成的恢复证据。
+
+## 等待与失败
+
+- 活引用、运行期仍在使用、内容发生变化:进入 waiting,不消耗故障预算,不安排定时重试。运行期释放资源的既有事件可重新唤醒;启动时只复查一次,补偿应用关闭期间已释放的资源,也可手动重试。
+- 用户要求保留:进入 kept,不被后台事件自动恢复。池复用同样不能重置这个目录。
+- 校验失败、磁盘空间/权限错误、目录身份异常:进入 paused,停止自动尝试。用户排除原因后手动重试。
+- 其它临时故障:退避重试;同一 generation 最多 3 次失败,失败处理累计达到 30 分钟也暂停。预算是内部常量,不增加高级数值配置。
+
+`retryPolicy` 作为 version 1 journal 的可选字段记录状态、失败次数与失败处理耗时,正常重启不重置。历史记录没有新字段时,用 reason 区分等待和失败:旧的活引用等待不能被历史 attempts 判为失败;已反复失败的记录则先暂停。
+
+本地数据库暂时没有可处理的 owner 时,不消耗失败预算、不显示故障暂停;仅按指数退避复查元数据,间隔最长 30 分钟,不执行归档或删除。恢复可处理的 owner 后自动继续。前置读取抛错或实际进入回收才消耗进程内兜底预算,同一次回收抛错不重复计数。
+
+如果失败发生在核心写 journal 之前(例如资源锁/卷不可用),维护器另有每进程最多 3 次的轻量兜底,避免无法写入预算时仍不断轮询;能读取状态时同样展示暂停。它不能冒充已经持久化的预算,应用重启后允许重新检测不可用的存储。
+
+## 用户入口
+
+设置 → 存储空间 → worktree 回收:显示原目录、状态和归类原因,提供刷新、重试回收、保留目录。
+
+手动动作携带资源 ID 与 generation,主进程查自己的 journal 并在资源锁内复查;不接受调用者传入任意路径。重试只重置这一 generation 的预算并唤醒既有队列,不直接删除;保留只改变回收策略,不丢弃备份或 Git 快照。已经完成恢复/删除或被新 generation 占用的旧操作无效。
+
+此入口管理当前桌面设备的本地持久回收 journal,与本地磁盘存储设置相同。SSH 的远端 worktree 不在此 journal 中;本机 IPC 不列入 device-link 白名单,手机/另一台设备不获得这个本机存储管理入口。没有 device-link 重连行为改动。
+
+## 与单次归档超时的关系
+
+有限重试治理不依赖归档实现的 worker 拆分,可独立合入。ASAR 物理读取与 worker 生命周期修复负责单次执行的终止请求;本策略负责执行失败后是否还应继续。只合前者仍可能反复重试,只有后者不能修复底层 ASAR 校验或终止阻塞 I/O;两者合入才能覆盖这两类故障,不要求合并顺序。
+
+本策略不清理旧 archive/history/recovery ref,也不把恢复证据当作可丢弃缓存;恢复副本容量与保留期限需要独立数据保留策略。