@yu_robotics/remote-cli 1.6.190 → 1.6.193

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/README.md +117 -14
  2. package/dist/client/MessageHandler.d.ts.map +1 -1
  3. package/dist/client/MessageHandler.js +2 -1
  4. package/dist/client/MessageHandler.js.map +1 -1
  5. package/dist/commands/delegationStorage.d.ts +15 -0
  6. package/dist/commands/delegationStorage.d.ts.map +1 -0
  7. package/dist/commands/delegationStorage.js +59 -0
  8. package/dist/commands/delegationStorage.js.map +1 -0
  9. package/dist/commands/start.d.ts +2 -0
  10. package/dist/commands/start.d.ts.map +1 -1
  11. package/dist/commands/start.js +42 -18
  12. package/dist/commands/start.js.map +1 -1
  13. package/dist/delegation/DelegatedWorkerSessionStore.d.ts +6 -0
  14. package/dist/delegation/DelegatedWorkerSessionStore.d.ts.map +1 -1
  15. package/dist/delegation/DelegatedWorkerSessionStore.js +25 -2
  16. package/dist/delegation/DelegatedWorkerSessionStore.js.map +1 -1
  17. package/dist/delegation/DelegatedWorkspaceManager.d.ts +119 -2
  18. package/dist/delegation/DelegatedWorkspaceManager.d.ts.map +1 -1
  19. package/dist/delegation/DelegatedWorkspaceManager.js +551 -65
  20. package/dist/delegation/DelegatedWorkspaceManager.js.map +1 -1
  21. package/dist/delegation/DelegationManager.d.ts +20 -0
  22. package/dist/delegation/DelegationManager.d.ts.map +1 -1
  23. package/dist/delegation/DelegationManager.js +267 -41
  24. package/dist/delegation/DelegationManager.js.map +1 -1
  25. package/dist/delegation/DelegationOwnership.d.ts +33 -0
  26. package/dist/delegation/DelegationOwnership.d.ts.map +1 -0
  27. package/dist/delegation/DelegationOwnership.js +397 -0
  28. package/dist/delegation/DelegationOwnership.js.map +1 -0
  29. package/dist/delegation/GitCheckpoint.d.ts.map +1 -1
  30. package/dist/delegation/GitCheckpoint.js +14 -5
  31. package/dist/delegation/GitCheckpoint.js.map +1 -1
  32. package/dist/delegation/LegacyWorkspaceCleanup.d.ts +100 -0
  33. package/dist/delegation/LegacyWorkspaceCleanup.d.ts.map +1 -0
  34. package/dist/delegation/LegacyWorkspaceCleanup.js +864 -0
  35. package/dist/delegation/LegacyWorkspaceCleanup.js.map +1 -0
  36. package/dist/delegation/OwnershipRuntime.d.ts +50 -0
  37. package/dist/delegation/OwnershipRuntime.d.ts.map +1 -0
  38. package/dist/delegation/OwnershipRuntime.js +411 -0
  39. package/dist/delegation/OwnershipRuntime.js.map +1 -0
  40. package/dist/delegation/WorkspaceDisposal.d.ts +23 -0
  41. package/dist/delegation/WorkspaceDisposal.d.ts.map +1 -0
  42. package/dist/delegation/WorkspaceDisposal.js +212 -0
  43. package/dist/delegation/WorkspaceDisposal.js.map +1 -0
  44. package/dist/delegation/contract.d.ts +1 -1
  45. package/dist/delegation/contract.d.ts.map +1 -1
  46. package/dist/delegation/contract.js +2 -1
  47. package/dist/delegation/contract.js.map +1 -1
  48. package/dist/executor/AcpExecutor.d.ts +2 -0
  49. package/dist/executor/AcpExecutor.d.ts.map +1 -1
  50. package/dist/executor/AcpExecutor.js +14 -1
  51. package/dist/executor/AcpExecutor.js.map +1 -1
  52. package/dist/executor/AgyExecutor.d.ts +2 -0
  53. package/dist/executor/AgyExecutor.d.ts.map +1 -1
  54. package/dist/executor/AgyExecutor.js +11 -1
  55. package/dist/executor/AgyExecutor.js.map +1 -1
  56. package/dist/executor/ClaudePersistentExecutor.d.ts +2 -0
  57. package/dist/executor/ClaudePersistentExecutor.d.ts.map +1 -1
  58. package/dist/executor/ClaudePersistentExecutor.js +13 -3
  59. package/dist/executor/ClaudePersistentExecutor.js.map +1 -1
  60. package/dist/executor/CodexAppServerClient.d.ts +4 -0
  61. package/dist/executor/CodexAppServerClient.d.ts.map +1 -1
  62. package/dist/executor/CodexAppServerClient.js +15 -3
  63. package/dist/executor/CodexAppServerClient.js.map +1 -1
  64. package/dist/executor/CodexAppServerExecutor.d.ts +2 -0
  65. package/dist/executor/CodexAppServerExecutor.d.ts.map +1 -1
  66. package/dist/executor/CodexAppServerExecutor.js +7 -0
  67. package/dist/executor/CodexAppServerExecutor.js.map +1 -1
  68. package/dist/executor/DshExecutor.d.ts.map +1 -1
  69. package/dist/executor/DshExecutor.js +2 -1
  70. package/dist/executor/DshExecutor.js.map +1 -1
  71. package/dist/executor/IExecutor.d.ts +5 -1
  72. package/dist/executor/IExecutor.d.ts.map +1 -1
  73. package/dist/executor/ManagedProcessGroups.d.ts +30 -0
  74. package/dist/executor/ManagedProcessGroups.d.ts.map +1 -0
  75. package/dist/executor/ManagedProcessGroups.js +144 -0
  76. package/dist/executor/ManagedProcessGroups.js.map +1 -0
  77. package/dist/executor/PiExecutor.d.ts +2 -0
  78. package/dist/executor/PiExecutor.d.ts.map +1 -1
  79. package/dist/executor/PiExecutor.js +15 -0
  80. package/dist/executor/PiExecutor.js.map +1 -1
  81. package/dist/executor/ZCodeExecutor.d.ts.map +1 -1
  82. package/dist/executor/ZCodeExecutor.js +1 -0
  83. package/dist/executor/ZCodeExecutor.js.map +1 -1
  84. package/dist/executor/acp/AcpClient.d.ts +5 -0
  85. package/dist/executor/acp/AcpClient.d.ts.map +1 -1
  86. package/dist/executor/acp/AcpClient.js +13 -2
  87. package/dist/executor/acp/AcpClient.js.map +1 -1
  88. package/dist/executor/dsh/DshAcpClient.d.ts +1 -1
  89. package/dist/executor/dsh/DshAcpClient.d.ts.map +1 -1
  90. package/dist/executor/dsh/DshAcpClient.js +2 -2
  91. package/dist/executor/dsh/DshAcpClient.js.map +1 -1
  92. package/dist/executor/pi/PiClient.d.ts +2 -0
  93. package/dist/executor/pi/PiClient.d.ts.map +1 -1
  94. package/dist/executor/pi/PiClient.js +12 -2
  95. package/dist/executor/pi/PiClient.js.map +1 -1
  96. package/dist/executor/pi/PiTypes.d.ts +1 -0
  97. package/dist/executor/pi/PiTypes.d.ts.map +1 -1
  98. package/dist/executor/pi/PiTypes.js.map +1 -1
  99. package/dist/executor/zcode/ZCodeClient.d.ts +4 -0
  100. package/dist/executor/zcode/ZCodeClient.d.ts.map +1 -1
  101. package/dist/executor/zcode/ZCodeClient.js +13 -2
  102. package/dist/executor/zcode/ZCodeClient.js.map +1 -1
  103. package/dist/index.js +13 -5
  104. package/dist/index.js.map +1 -1
  105. package/dist/maintenance/release-notes.json +1 -1
  106. package/dist/utils/ProcessShutdown.d.ts +25 -0
  107. package/dist/utils/ProcessShutdown.d.ts.map +1 -0
  108. package/dist/utils/ProcessShutdown.js +54 -0
  109. package/dist/utils/ProcessShutdown.js.map +1 -0
  110. package/package.json +5 -4
@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.DelegatedWorkspaceManager = void 0;
6
+ exports.DelegatedWorkspaceManager = exports.WORKSPACE_INVENTORY_PAGE_LIMIT = void 0;
7
+ const async_hooks_1 = require("async_hooks");
7
8
  const crypto_1 = require("crypto");
8
9
  const fs_1 = require("fs");
9
10
  const promises_1 = __importDefault(require("fs/promises"));
@@ -11,8 +12,15 @@ const os_1 = __importDefault(require("os"));
11
12
  const path_1 = __importDefault(require("path"));
12
13
  const GitCheckpoint_1 = require("./GitCheckpoint");
13
14
  const BoundedFileChecks_1 = require("./BoundedFileChecks");
15
+ const LegacyWorkspaceCleanup_1 = require("./LegacyWorkspaceCleanup");
16
+ const WorkspaceDisposal_1 = require("./WorkspaceDisposal");
14
17
  const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
15
18
  const RECORD_BYTES = 128 * 1024;
19
+ const INVENTORY_LIMIT = 10_000;
20
+ /** At most one bounded artifact listing plus the exact tasks of the bounded lane listing. */
21
+ exports.WORKSPACE_INVENTORY_PAGE_LIMIT = INVENTORY_LIMIT * 2;
22
+ const INVENTORY_BYTES = 32 * 1024 * 1024;
23
+ const CLEANUP_ATTEMPTS = 3;
16
24
  function inside(root, child) {
17
25
  const relative = path_1.default.relative(root, child);
18
26
  return relative === '' || (!path_1.default.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path_1.default.sep}`));
@@ -20,9 +28,18 @@ function inside(root, child) {
20
28
  /** Worktrees isolate checkout files, not process permissions. Artifacts are never expired with task diagnostics. */
21
29
  class DelegatedWorkspaceManager {
22
30
  directory;
31
+ disposalSupported;
23
32
  static operations = new Map();
24
- constructor(directory = path_1.default.join(os_1.default.homedir(), '.remote-cli', 'delegation-workspaces')) {
33
+ ownership;
34
+ beforeMutation;
35
+ repositoryContext = new async_hooks_1.AsyncLocalStorage();
36
+ setOwnership(ownership, beforeMutation) {
37
+ this.ownership = ownership;
38
+ this.beforeMutation = beforeMutation;
39
+ }
40
+ constructor(directory = path_1.default.join(os_1.default.homedir(), '.remote-cli', 'delegation-workspaces'), disposalSupported = process.platform === 'linux') {
25
41
  this.directory = directory;
42
+ this.disposalSupported = disposalSupported;
26
43
  }
27
44
  async discover(cwd) {
28
45
  // Avoid starting Git for ordinary directories (including environments without Git).
@@ -69,7 +86,8 @@ class DelegatedWorkspaceManager {
69
86
  continue;
70
87
  try {
71
88
  const record = await this.read('lanes', id);
72
- if (!record || record.blocked || record.pendingTaskId)
89
+ if (!record || record.blocked || record.pendingTaskId || record.cleanup
90
+ && !(record.checkoutState === 'reclaiming' && record.cleanup.retryable))
73
91
  blocked.add(id);
74
92
  else
75
93
  this.assertLifecycle(record);
@@ -81,7 +99,7 @@ class DelegatedWorkspaceManager {
81
99
  return blocked;
82
100
  }
83
101
  async prepare(lane, source, input, taskId) {
84
- return this.withLane(lane.id, () => this.prepareLocked(lane, source, input, taskId));
102
+ return this.withLane(lane.id, () => this.withRepository(source, () => this.prepareLocked(lane, source, input, taskId)));
85
103
  }
86
104
  async prepareLocked(lane, source, input, taskId) {
87
105
  this.assertId(taskId);
@@ -97,7 +115,9 @@ class DelegatedWorkspaceManager {
97
115
  if (previous) {
98
116
  await this.validateWorkspaceRecord(previous);
99
117
  if (previous.laneId !== lane.id || previous.threadId !== lane.threadId || previous.workspaceGeneration !== lane.workspaceGeneration
100
- || previous.source.cwd !== source.cwd || previous.blocked || previous.pendingTaskId) {
118
+ || previous.source.cwd !== source.cwd || previous.blocked || previous.pendingTaskId
119
+ || previous.disposalPolicy === 1 && previous.cleanup
120
+ && !(previous.checkoutState === 'reclaiming' && previous.cleanup.retryable)) {
101
121
  throw new Error('Worker workspace has unresolved artifacts or a changed identity');
102
122
  }
103
123
  previous = await this.resolveReclamation(previous);
@@ -132,57 +152,115 @@ class DelegatedWorkspaceManager {
132
152
  }
133
153
  await (0, GitCheckpoint_1.runGit)(source.root, ['update-ref', this.inputRef(taskId), input.commit]);
134
154
  await (0, GitCheckpoint_1.runGit)(source.root, ['update-ref', taskRef, input.commit]);
155
+ const identity = await promises_1.default.lstat(directory);
156
+ // Reusing a legacy checkout must not adopt its pre-existing ignored files as
157
+ // disposable data. Only a newly created checkout opts into the new policy.
158
+ const disposalPolicy = this.disposalSupported
159
+ ? previous && previous.checkoutState !== 'reclaimed' ? previous.disposalPolicy : 1 : undefined;
135
160
  const workspace = { laneId: lane.id, threadId: lane.threadId,
136
161
  workspaceGeneration: lane.workspaceGeneration, source, directory,
137
- cwd: path_1.default.join(directory, source.relativeCwd), taskId, taskRef, input, checkoutState: 'present' };
162
+ cwd: path_1.default.join(directory, source.relativeCwd), taskId, taskRef, input, checkoutState: 'present',
163
+ disposalPolicy, checkoutIdentity: { dev: identity.dev, ino: identity.ino } };
138
164
  await this.write('lanes', lane.id, workspace);
139
165
  await this.validateWorkspace(workspace);
140
166
  return workspace;
141
167
  }
142
- async collect(workspace, successful) {
143
- return this.withLane(workspace.laneId, () => this.collectLocked(workspace, successful));
168
+ async collect(workspace, successful, options = {}) {
169
+ return this.withLane(workspace.laneId, async () => {
170
+ try {
171
+ return await this.collectLocked(workspace, successful, options);
172
+ }
173
+ catch (error) {
174
+ await this.recordHold(workspace.laneId, workspace.taskId, error, 'capture-failed');
175
+ throw error;
176
+ }
177
+ });
144
178
  }
145
- async collectLocked(workspace, successful) {
179
+ async collectLocked(workspace, successful, options) {
146
180
  const record = await this.read('lanes', workspace.laneId);
147
181
  if (!record || record.taskId !== workspace.taskId || record.blocked
148
182
  || record.checkoutState && record.checkoutState !== 'present') {
149
183
  throw new Error('Worker workspace task changed before collection');
150
184
  }
151
185
  await this.validateWorkspace(workspace);
152
- const checkpoint = await (0, GitCheckpoint_1.captureCheckpoint)(workspace.directory);
153
- const opaque = (await (0, GitCheckpoint_1.runGit)(workspace.directory, ['ls-tree', '-r', '-z', workspace.input.tree]))
154
- .toString('utf8').split('\0').filter(entry => entry.startsWith('160000 commit '))
155
- .map(entry => entry.slice(entry.indexOf('\t') + 1));
156
- const changed = (await (0, GitCheckpoint_1.runGit)(workspace.directory, ['diff', '--name-only', '--no-renames', '-z',
157
- workspace.input.tree, checkpoint.tree, '--'])).toString('utf8').split('\0').filter(Boolean);
158
- const opaqueChange = opaque.find(name => changed.some(file => file === name || file.startsWith(`${name}/`)));
159
- const nestedChange = checkpoint.repositories?.[0]?.path;
160
- const unsupported = nestedChange !== undefined || opaqueChange !== undefined;
161
- const output = await (0, GitCheckpoint_1.createCheckpointCommit)(workspace.directory, checkpoint.tree, workspace.input.commit, `Remote CLI worker artifact ${workspace.taskId}`);
162
- await (0, GitCheckpoint_1.runGit)(workspace.directory, ['update-ref', this.outputRef(workspace.taskId), output]);
163
- await (0, GitCheckpoint_1.runGit)(workspace.directory, ['update-ref', `refs/remote-cli/worker-history/${workspace.taskId}`, checkpoint.head]);
164
- const artifact = { taskId: workspace.taskId, laneId: workspace.laneId,
165
- threadId: workspace.threadId, workspaceGeneration: workspace.workspaceGeneration,
166
- source: workspace.source, input: workspace.input, output, tree: checkpoint.tree,
167
- originalHead: checkpoint.head, successful: successful && !unsupported,
168
- disposition: !unsupported && checkpoint.tree === workspace.input.tree ? 'applied' : 'pending', createdAt: Date.now() };
169
- // Durable artifact + refs precede any index/branch update in the owned checkout.
170
- await this.write('artifacts', artifact.taskId, artifact);
171
- if (unsupported) {
172
- await this.write('lanes', workspace.laneId, { ...workspace, blocked: true, pendingTaskId: artifact.taskId });
173
- throw new Error(`${nestedChange !== undefined ? 'Worker created nested Git metadata' : 'Worker changed an uninitialized submodule'} at ${JSON.stringify(nestedChange ?? opaqueChange)}; files and history were retained for manual recovery`);
174
- }
175
- const currentBranch = await (0, GitCheckpoint_1.gitText)(workspace.directory, ['branch', '--show-current']);
176
- if (currentBranch || checkpoint.head !== await (0, GitCheckpoint_1.gitText)(workspace.directory, ['rev-parse', 'HEAD'])) {
177
- await this.write('lanes', workspace.laneId, { ...workspace, blocked: true, pendingTaskId: artifact.taskId });
178
- throw new Error('Worker changed its branch during execution; the artifact is preserved for manual recovery');
179
- }
180
- // Mixed reset only updates OUR index/branch to the preserved working files. Never touches the parent index.
181
- await (0, GitCheckpoint_1.runGit)(workspace.directory, ['reset', '--mixed', output]);
182
- await (0, GitCheckpoint_1.runGit)(workspace.directory, ['update-ref', workspace.taskRef, output]);
183
- await this.assertClean(workspace.directory);
184
- await this.write('lanes', workspace.laneId, { ...workspace,
185
- pendingTaskId: artifact.disposition === 'pending' ? artifact.taskId : undefined });
186
+ const saved = await this.read('artifacts', workspace.taskId);
187
+ if (saved && record.disposalPolicy === 1) {
188
+ await this.validateArtifact(saved, { threadId: record.threadId, cwd: record.source.cwd, workspaceGeneration: record.workspaceGeneration });
189
+ if (saved.laneId !== record.laneId || saved.successful !== successful
190
+ || await (0, GitCheckpoint_1.gitText)(record.source.root, ['rev-parse', record.taskRef]) !== saved.output
191
+ || await (0, GitCheckpoint_1.gitText)(record.source.root, ['rev-parse', `refs/remote-cli/worker-history/${saved.taskId}`]) !== saved.originalHead) {
192
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('capture-receipt-incomplete');
193
+ }
194
+ // Retrying proof/export must never rewrite immutable output or native history refs.
195
+ return this.finishCollection(record, saved, options);
196
+ }
197
+ const artifact = await this.withRepository(workspace.source, async () => {
198
+ const checkpoint = await (0, GitCheckpoint_1.captureCheckpoint)(workspace.directory);
199
+ const opaque = (await (0, GitCheckpoint_1.runGit)(workspace.directory, ['ls-tree', '-r', '-z', workspace.input.tree]))
200
+ .toString('utf8').split('\0').filter(entry => entry.startsWith('160000 commit '))
201
+ .map(entry => entry.slice(entry.indexOf('\t') + 1));
202
+ const changed = (await (0, GitCheckpoint_1.runGit)(workspace.directory, ['diff', '--name-only', '--no-renames', '-z',
203
+ workspace.input.tree, checkpoint.tree, '--'])).toString('utf8').split('\0').filter(Boolean);
204
+ const opaqueChange = opaque.find(name => changed.some(file => file === name || file.startsWith(`${name}/`)));
205
+ const nestedChange = checkpoint.repositories?.[0]?.path;
206
+ const unsupported = nestedChange !== undefined || opaqueChange !== undefined;
207
+ const output = await (0, GitCheckpoint_1.createCheckpointCommit)(workspace.directory, checkpoint.tree, workspace.input.commit, `Remote CLI worker artifact ${workspace.taskId}`);
208
+ await (0, GitCheckpoint_1.runGit)(workspace.directory, ['update-ref', this.outputRef(workspace.taskId), output]);
209
+ await (0, GitCheckpoint_1.runGit)(workspace.directory, ['update-ref', `refs/remote-cli/worker-history/${workspace.taskId}`, checkpoint.head]);
210
+ const artifact = { taskId: workspace.taskId, laneId: workspace.laneId,
211
+ threadId: workspace.threadId, workspaceGeneration: workspace.workspaceGeneration,
212
+ source: workspace.source, input: workspace.input, output, tree: checkpoint.tree,
213
+ originalHead: checkpoint.head, successful: successful && !unsupported,
214
+ disposition: !unsupported && checkpoint.tree === workspace.input.tree ? 'applied' : 'pending', createdAt: Date.now(),
215
+ ...(record.disposalPolicy === 1 ? { disposalPolicy: 1,
216
+ ...(options.exitConfirmed === true ? { closeout: { taskId: workspace.taskId, output, tree: checkpoint.tree,
217
+ exitConfirmedAt: Date.now(), recoverable: false } } : {}) } : {}) };
218
+ // Durable artifact + refs precede any index/branch update in the owned checkout.
219
+ await this.write('artifacts', artifact.taskId, artifact);
220
+ if (unsupported) {
221
+ await this.write('lanes', workspace.laneId, { ...workspace, blocked: true, pendingTaskId: artifact.taskId });
222
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('nested-repository', false, `${nestedChange !== undefined ? 'Worker created nested Git metadata' : 'Worker changed an uninitialized submodule'}; files and history were retained for manual recovery`);
223
+ }
224
+ const currentBranch = await (0, GitCheckpoint_1.gitText)(workspace.directory, ['branch', '--show-current']);
225
+ if (currentBranch || checkpoint.head !== await (0, GitCheckpoint_1.gitText)(workspace.directory, ['rev-parse', 'HEAD'])) {
226
+ await this.write('lanes', workspace.laneId, { ...workspace, blocked: true, pendingTaskId: artifact.taskId });
227
+ throw new Error('Worker changed its branch during execution; the artifact is preserved for manual recovery');
228
+ }
229
+ // Mixed reset only updates OUR index/branch to the preserved working files. Never touches the parent index.
230
+ await (0, GitCheckpoint_1.runGit)(workspace.directory, ['reset', '--mixed', output]);
231
+ await (0, GitCheckpoint_1.runGit)(workspace.directory, ['update-ref', workspace.taskRef, output]);
232
+ await this.assertClean(workspace.directory);
233
+ // Persist pending before proof/export, so a failed proof cannot hide changed output.
234
+ await this.write('lanes', workspace.laneId, { ...record,
235
+ pendingTaskId: artifact.disposition === 'pending' ? artifact.taskId : undefined });
236
+ return artifact;
237
+ });
238
+ return this.finishCollection(record, artifact, options);
239
+ }
240
+ async finishCollection(record, saved, options) {
241
+ let artifact = saved;
242
+ if (artifact.disposalPolicy === 1 && options.exitConfirmed === true && !artifact.closeout) {
243
+ artifact = { ...artifact, closeout: { taskId: artifact.taskId, output: artifact.output, tree: artifact.tree,
244
+ exitConfirmedAt: Date.now(), recoverable: false } };
245
+ await this.write('artifacts', artifact.taskId, artifact);
246
+ }
247
+ if (artifact.disposalPolicy === 1 && artifact.closeout) {
248
+ const closeout = artifact.closeout;
249
+ if (options.exports !== undefined) {
250
+ const directory = await this.exportDirectory(artifact.taskId, true);
251
+ artifact = { ...artifact, exports: await (0, WorkspaceDisposal_1.exportWorkspaceFiles)(record.directory, directory, options.exports) };
252
+ await this.write('artifacts', artifact.taskId, artifact);
253
+ }
254
+ await this.verifyCheckout(record, artifact);
255
+ artifact = { ...artifact, closeout: { ...closeout, recoverable: true },
256
+ disposition: !artifact.successful && artifact.disposition === 'pending' ? 'retained' : artifact.disposition };
257
+ await this.write('artifacts', artifact.taskId, artifact);
258
+ await this.write('lanes', record.laneId, { ...record, cleanup: undefined,
259
+ pendingTaskId: artifact.disposition === 'pending' ? artifact.taskId : undefined });
260
+ }
261
+ else if (artifact.disposalPolicy === 1) {
262
+ await this.recordHold(record.laneId, record.taskId, new WorkspaceDisposal_1.WorkspaceCleanupError('child-exit-unconfirmed'));
263
+ }
186
264
  return this.view(artifact);
187
265
  }
188
266
  async integrate(owner, taskId, action, expectedRevision) {
@@ -190,8 +268,8 @@ class DelegatedWorkspaceManager {
190
268
  const artifact = await this.read('artifacts', taskId);
191
269
  if (!artifact)
192
270
  throw new Error('Worker artifact not found');
193
- const result = await this.withLane(artifact.laneId, () => this.integrateLocked(owner, taskId, action, expectedRevision));
194
- if (action === 'apply' || action === 'inspect' && result.deliveredAtHead) {
271
+ const result = await this.withLane(artifact.laneId, () => this.withRepository(artifact.source, () => this.integrateLocked(owner, taskId, action, expectedRevision)));
272
+ if (action === 'apply' || action === 'retain' || action === 'inspect' && result.deliveredAtHead) {
195
273
  await this.reclaim(taskId);
196
274
  }
197
275
  return result;
@@ -242,7 +320,7 @@ class DelegatedWorkspaceManager {
242
320
  return view;
243
321
  if (action === 'retain') {
244
322
  owner.checkActive?.();
245
- // Intentional non-integration is not deletion. The immutable artifact remains inspectable.
323
+ // Retain preserves the immutable artifact. Opted-in disposable checkouts can close out.
246
324
  await this.resolveArtifact(artifact, 'retained');
247
325
  return this.view({ ...artifact, disposition: 'retained' });
248
326
  }
@@ -338,6 +416,290 @@ class DelegatedWorkspaceManager {
338
416
  const artifact = await this.read('artifacts', taskId);
339
417
  return artifact ? this.view(artifact) : undefined;
340
418
  }
419
+ /** Metadata inventory only: no mkdir, worker-store initialization, Git commands or record repair. */
420
+ async enumerateArtifacts(options = {}) {
421
+ const records = new Map();
422
+ const workspaces = new Map();
423
+ const missingArtifacts = new Set();
424
+ let incomplete = false;
425
+ let bytes = 0;
426
+ const matches = (record) => (options.threadId === undefined || record.threadId === options.threadId)
427
+ && (options.cwd === undefined || record.source?.cwd === options.cwd)
428
+ && (options.workspaceGeneration === undefined || record.workspaceGeneration === options.workspaceGeneration)
429
+ && (options.laneId === undefined || record.laneId === options.laneId);
430
+ // Read current ownership before historical artifacts can exhaust the global budget.
431
+ // Scope filtering bounds retained memory, while the read budget still bounds total I/O.
432
+ for (const kind of ['lanes', 'artifacts']) {
433
+ const listing = await this.snapshotNames(kind);
434
+ incomplete ||= listing.incomplete;
435
+ bytes = 0;
436
+ const charge = (size) => {
437
+ bytes += size;
438
+ if (bytes > INVENTORY_BYTES)
439
+ throw new Error('Inventory byte budget exhausted');
440
+ };
441
+ for (const name of listing.names) {
442
+ try {
443
+ if (kind === 'artifacts') {
444
+ if (records.has(name))
445
+ continue;
446
+ const artifact = await this.readSnapshot(kind, name, charge);
447
+ if (!artifact || artifact.taskId !== name || !this.validSummaryArtifact(artifact))
448
+ throw new Error('Invalid artifact');
449
+ if (matches(artifact))
450
+ records.set(name, artifact);
451
+ }
452
+ else {
453
+ const workspace = await this.readSnapshot(kind, name, charge);
454
+ if (!workspace || workspace.laneId !== name || !UUID.test(workspace.taskId)
455
+ || typeof workspace.threadId !== 'string' || typeof workspace.source?.cwd !== 'string'
456
+ || !Number.isSafeInteger(workspace.workspaceGeneration))
457
+ throw new Error('Invalid workspace');
458
+ if (matches(workspace))
459
+ workspaces.set(workspace.taskId, workspace);
460
+ }
461
+ }
462
+ catch {
463
+ if (kind === 'artifacts')
464
+ missingArtifacts.delete(name);
465
+ incomplete = true;
466
+ if (bytes > INVENTORY_BYTES)
467
+ break;
468
+ }
469
+ }
470
+ if (kind === 'lanes') {
471
+ // Exact current task IDs remain obligations even if historical enumeration
472
+ // is truncated. This bounded pass never scans the entire store again.
473
+ let currentBytes = 0;
474
+ for (const workspace of workspaces.values()) {
475
+ try {
476
+ const artifact = await this.readSnapshot('artifacts', workspace.taskId, size => {
477
+ currentBytes += size;
478
+ if (currentBytes > INVENTORY_BYTES)
479
+ throw new Error('Current artifact byte budget exhausted');
480
+ });
481
+ if (!artifact) {
482
+ missingArtifacts.add(workspace.taskId);
483
+ continue;
484
+ }
485
+ if (!this.validSummaryArtifact(artifact) || artifact.taskId !== workspace.taskId
486
+ || artifact.laneId !== workspace.laneId || !matches(artifact))
487
+ throw new Error('Invalid current artifact');
488
+ records.set(artifact.taskId, artifact);
489
+ }
490
+ catch {
491
+ incomplete = true;
492
+ if (currentBytes > INVENTORY_BYTES)
493
+ break;
494
+ }
495
+ }
496
+ }
497
+ }
498
+ const items = [];
499
+ for (const taskId of new Set([...records.keys(), ...workspaces.keys()])) {
500
+ const artifact = records.get(taskId);
501
+ const workspace = workspaces.get(taskId);
502
+ const item = this.summary(artifact, workspace);
503
+ if (!artifact && workspace && missingArtifacts.has(taskId)) {
504
+ item.discarded = await (0, LegacyWorkspaceCleanup_1.completedLegacyDiscard)(this.directory, workspace.laneId, taskId);
505
+ }
506
+ if (options.threadId !== undefined && item.threadId !== options.threadId
507
+ || options.cwd !== undefined && item.cwd !== options.cwd
508
+ || options.workspaceGeneration !== undefined && item.workspaceGeneration !== options.workspaceGeneration)
509
+ continue;
510
+ if (options.laneId !== undefined && item.laneId !== options.laneId)
511
+ continue;
512
+ if (options.unresolvedOnly && item.disposition !== 'pending' && !item.recovery
513
+ && (item.disposition !== undefined || item.discarded))
514
+ continue;
515
+ items.push(item);
516
+ }
517
+ items.sort((a, b) => a.taskId.localeCompare(b.taskId));
518
+ const offset = Number.isSafeInteger(options.offset) ? Math.max(0, options.offset) : 0;
519
+ const limit = Number.isSafeInteger(options.limit) ? Math.max(0, Math.min(exports.WORKSPACE_INVENTORY_PAGE_LIMIT, options.limit)) : 100;
520
+ return { items: items.slice(offset, offset + limit), total: items.length, incomplete };
521
+ }
522
+ /** A caller must still hold its admission reservation; this is not an inactivity proof. */
523
+ async getLaneCloseout(laneId) {
524
+ const workspace = await this.readSnapshot('lanes', laneId);
525
+ if (!workspace)
526
+ return undefined;
527
+ const artifact = await this.readSnapshot('artifacts', workspace.taskId);
528
+ if (artifact && (!this.validSummaryArtifact(artifact) || artifact.laneId !== laneId))
529
+ throw new Error('Invalid lane artifact');
530
+ const item = this.summary(artifact, workspace);
531
+ if (!artifact)
532
+ item.discarded = await (0, LegacyWorkspaceCleanup_1.completedLegacyDiscard)(this.directory, laneId, workspace.taskId);
533
+ return item;
534
+ }
535
+ async getArtifactExports(taskId) {
536
+ const artifact = await this.readSnapshot('artifacts', taskId);
537
+ if (!artifact || !this.validSummaryArtifact(artifact))
538
+ throw new Error('Artifact is unavailable');
539
+ const directory = await this.exportDirectory(taskId);
540
+ await (0, WorkspaceDisposal_1.verifyWorkspaceExports)(directory, artifact.exports ?? []);
541
+ return (artifact.exports ?? []).map(entry => ({ ...entry, file: path_1.default.join(directory, entry.sha256) }));
542
+ }
543
+ async enumerateIntegrationScratch() {
544
+ const listing = await this.snapshotNames('scratch');
545
+ const items = [];
546
+ let incomplete = listing.incomplete;
547
+ for (const id of listing.names) {
548
+ try {
549
+ const record = await this.readSnapshot('scratch', id);
550
+ if (!record || record.id !== id || !UUID.test(record.taskId) || !UUID.test(record.laneId)
551
+ || record.directory !== path_1.default.join(this.directory, `integration-${id}`)
552
+ || !['allocating', 'present', 'conflict', 'cleanup-pending', 'reclaimed'].includes(record.state))
553
+ throw new Error('Invalid scratch receipt');
554
+ items.push(record);
555
+ }
556
+ catch {
557
+ incomplete = true;
558
+ }
559
+ }
560
+ return { items, incomplete };
561
+ }
562
+ /** Owner-only retry. The owner must reserve these lanes and exclude every live/setup lane. */
563
+ async retryReclamation(options = {}) {
564
+ const inventory = await this.enumerateArtifacts({ limit: INVENTORY_LIMIT });
565
+ const result = { attempted: 0, reclaimed: 0, held: 0, incomplete: inventory.incomplete };
566
+ if (inventory.total > inventory.items.length)
567
+ result.incomplete = true;
568
+ if (result.incomplete)
569
+ return result;
570
+ const limit = Number.isSafeInteger(options.limit) ? Math.max(0, Math.min(100, options.limit)) : 10;
571
+ for (const item of inventory.items) {
572
+ if (result.attempted >= limit)
573
+ break;
574
+ if (item.disposalPolicy !== 1 || !item.exitConfirmed || !item.recoverable || item.blocked
575
+ || item.pendingTaskId || item.recovery || !['applied', 'retained'].includes(item.disposition ?? '')
576
+ || item.checkoutState === undefined || item.checkoutState === 'reclaimed' || options.excludedLaneIds?.has(item.laneId)
577
+ || item.cleanup && (!item.cleanup.retryable || item.cleanup.attempts >= CLEANUP_ATTEMPTS
578
+ || (item.cleanup.nextRetryAt ?? 0) > Date.now()))
579
+ continue;
580
+ result.attempted++;
581
+ if (await this.reclaim(item.taskId))
582
+ result.reclaimed++;
583
+ else
584
+ result.held++;
585
+ }
586
+ return result;
587
+ }
588
+ validSummaryArtifact(artifact) {
589
+ return UUID.test(artifact.taskId) && UUID.test(artifact.laneId) && typeof artifact.threadId === 'string'
590
+ && Number.isSafeInteger(artifact.workspaceGeneration) && typeof artifact.source?.cwd === 'string'
591
+ && GitCheckpoint_1.GIT_OID.test(artifact.input?.commit) && GitCheckpoint_1.GIT_OID.test(artifact.input?.tree) && GitCheckpoint_1.GIT_OID.test(artifact.output)
592
+ && GitCheckpoint_1.GIT_OID.test(artifact.tree) && typeof artifact.successful === 'boolean'
593
+ && ['pending', 'applied', 'retained'].includes(artifact.disposition);
594
+ }
595
+ summary(artifact, workspace) {
596
+ const owner = artifact ?? workspace;
597
+ return { taskId: owner.taskId, laneId: owner.laneId, threadId: owner.threadId,
598
+ workspaceGeneration: owner.workspaceGeneration, cwd: owner.source.cwd,
599
+ disposition: artifact?.disposition, successful: artifact?.successful,
600
+ outputCommit: artifact?.output, baseCommit: artifact?.input?.commit, exports: artifact?.exports,
601
+ disposalPolicy: workspace?.disposalPolicy, checkoutState: workspace?.checkoutState,
602
+ blocked: workspace?.blocked, pendingTaskId: workspace?.pendingTaskId,
603
+ exitConfirmed: artifact?.closeout?.taskId === artifact?.taskId && Number.isFinite(artifact?.closeout?.exitConfirmedAt),
604
+ recoverable: artifact?.closeout?.recoverable === true, recovery: artifact?.recovery,
605
+ cleanup: workspace?.cleanup,
606
+ holdReason: workspace?.cleanup?.reason ?? (workspace?.blocked ? 'preserved-for-recovery'
607
+ : !artifact ? 'artifact-unavailable' : !workspace ? 'workspace-unavailable' : undefined) };
608
+ }
609
+ async snapshotNames(kind) {
610
+ const names = [];
611
+ try {
612
+ const directory = path_1.default.join(this.directory, kind);
613
+ if (await promises_1.default.realpath(directory) !== directory || await promises_1.default.realpath(this.directory) !== this.directory) {
614
+ return { names, incomplete: true };
615
+ }
616
+ const handle = await promises_1.default.opendir(directory);
617
+ let count = 0;
618
+ let incomplete = false;
619
+ for await (const entry of handle) {
620
+ if (++count > INVENTORY_LIMIT) {
621
+ incomplete = true;
622
+ break;
623
+ }
624
+ if (!entry.name.endsWith('.json'))
625
+ continue;
626
+ const id = entry.name.slice(0, -5);
627
+ if (!UUID.test(id) || !entry.isFile() || entry.isSymbolicLink()) {
628
+ incomplete = true;
629
+ continue;
630
+ }
631
+ names.push(id);
632
+ }
633
+ return { names: names.sort(), incomplete };
634
+ }
635
+ catch (error) {
636
+ return { names, incomplete: error.code !== 'ENOENT' };
637
+ }
638
+ }
639
+ async readSnapshot(kind, id, charge) {
640
+ this.assertId(id);
641
+ const directory = path_1.default.join(this.directory, kind);
642
+ try {
643
+ if (await promises_1.default.realpath(this.directory) !== this.directory || await promises_1.default.realpath(directory) !== directory)
644
+ throw new Error('Unsafe inventory path');
645
+ const file = path_1.default.join(directory, `${id}.json`);
646
+ const stat = await promises_1.default.lstat(file);
647
+ if (!stat.isFile() || stat.isSymbolicLink() || stat.size > RECORD_BYTES)
648
+ throw new Error('Invalid inventory record');
649
+ charge?.(stat.size);
650
+ const handle = await promises_1.default.open(file, fs_1.constants.O_RDONLY | (fs_1.constants.O_NOFOLLOW ?? 0));
651
+ try {
652
+ const opened = await handle.stat();
653
+ if (opened.ino !== stat.ino || opened.dev !== stat.dev || opened.size !== stat.size)
654
+ throw new Error('Inventory changed');
655
+ const buffer = Buffer.alloc(RECORD_BYTES + 1);
656
+ const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
657
+ const after = await handle.stat();
658
+ if (bytesRead !== stat.size || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs)
659
+ throw new Error('Inventory changed');
660
+ return JSON.parse(buffer.subarray(0, bytesRead).toString('utf8'));
661
+ }
662
+ finally {
663
+ await handle.close();
664
+ }
665
+ }
666
+ catch (error) {
667
+ if (error.code === 'ENOENT')
668
+ return undefined;
669
+ throw error;
670
+ }
671
+ }
672
+ async exportDirectory(taskId, create = false) {
673
+ this.assertId(taskId);
674
+ const root = path_1.default.join(this.directory, 'exports');
675
+ const directory = path_1.default.join(root, taskId);
676
+ if (create) {
677
+ await this.initialize();
678
+ await this.safeDirectory(root);
679
+ await this.safeDirectory(directory);
680
+ }
681
+ return directory;
682
+ }
683
+ async recordHold(laneId, taskId, error, fallback = 'verification-failed') {
684
+ try {
685
+ const workspace = await this.read('lanes', laneId);
686
+ if (!workspace || workspace.taskId !== taskId || workspace.disposalPolicy !== 1)
687
+ return;
688
+ const detail = error instanceof Error ? error.message : '';
689
+ const reason = error instanceof WorkspaceDisposal_1.WorkspaceCleanupError ? error.reason
690
+ : /checkout file|Saved checkout|file mode|blob|bytes/i.test(detail) ? 'tracked-files-changed'
691
+ : /identity|reference|registration|receipt|locked|no longer/.test(detail) ? 'identity-or-registration-changed' : fallback;
692
+ if (reason === 'preserved-for-recovery' && workspace.cleanup)
693
+ return;
694
+ const attempts = Math.min(CLEANUP_ATTEMPTS, (workspace.cleanup?.attempts ?? 0) + 1);
695
+ const retryable = error instanceof WorkspaceDisposal_1.WorkspaceCleanupError && error.retryable;
696
+ await this.write('lanes', laneId, { ...workspace, cleanup: { reason, attempts, retryable, updatedAt: Date.now(),
697
+ ...(retryable && attempts < CLEANUP_ATTEMPTS ? { nextRetryAt: Date.now() + 1000 * 2 ** attempts } : {}) } });
698
+ }
699
+ catch {
700
+ console.warn('[Delegation] Cleanup hold could not be persisted; the checkout remains protected');
701
+ }
702
+ }
341
703
  /** Closeout needs a fresh, owned receipt, not a cached result or an absent record. */
342
704
  async inspectCloseout(owner, taskId) {
343
705
  const saved = await this.read('artifacts', taskId);
@@ -350,6 +712,11 @@ class DelegatedWorkspaceManager {
350
712
  throw new Error('Invalid worker artifact receipt');
351
713
  await this.validateArtifact(artifact, owner);
352
714
  owner.checkActive?.();
715
+ if (artifact.disposalPolicy === 1 && (!artifact.closeout?.recoverable
716
+ || artifact.closeout.taskId !== artifact.taskId || artifact.closeout.output !== artifact.output
717
+ || artifact.closeout.tree !== artifact.tree || !Number.isFinite(artifact.closeout.exitConfirmedAt))) {
718
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('recovery-unverified');
719
+ }
353
720
  const workspace = await this.read('lanes', artifact.laneId);
354
721
  if (artifact.disposition !== 'retained' && workspace?.taskId === taskId && workspace.blocked) {
355
722
  throw new Error('Worker artifact collection requires recovery');
@@ -367,8 +734,10 @@ class DelegatedWorkspaceManager {
367
734
  async preserveLane(laneId) {
368
735
  await this.withLane(laneId, async () => {
369
736
  const workspace = await this.read('lanes', laneId);
370
- if (workspace)
737
+ if (workspace) {
371
738
  await this.write('lanes', laneId, { ...workspace, blocked: true });
739
+ await this.recordHold(laneId, workspace.taskId, new WorkspaceDisposal_1.WorkspaceCleanupError('preserved-for-recovery'));
740
+ }
372
741
  });
373
742
  }
374
743
  /** Called only after worker exit or a durable delivery receipt; never races a cleanup deadline. */
@@ -378,7 +747,15 @@ class DelegatedWorkspaceManager {
378
747
  const artifact = await this.read('artifacts', taskId);
379
748
  if (!artifact)
380
749
  return false;
381
- return await this.withLane(artifact.laneId, () => this.reclaimLocked(taskId, artifact.laneId));
750
+ return await this.withLane(artifact.laneId, async () => {
751
+ try {
752
+ return await this.reclaimLocked(taskId, artifact.laneId);
753
+ }
754
+ catch (error) {
755
+ await this.recordHold(artifact.laneId, taskId, error, 'verification-failed');
756
+ return false;
757
+ }
758
+ });
382
759
  }
383
760
  catch {
384
761
  // Physical cleanup is optional. Do not turn a delivered result into a failed task.
@@ -389,12 +766,26 @@ class DelegatedWorkspaceManager {
389
766
  async reclaimLocked(taskId, laneId) {
390
767
  const workspace = await this.read('lanes', laneId);
391
768
  const artifact = await this.read('artifacts', taskId);
392
- if (!workspace || workspace.taskId !== taskId || !artifact || workspace.blocked || workspace.pendingTaskId
393
- || artifact.successful !== true || artifact.disposition !== 'applied' || artifact.recovery)
769
+ if (!workspace || workspace.taskId !== taskId || !artifact)
394
770
  return false;
395
- await this.validateReclamationArtifact(workspace, artifact);
396
771
  if (workspace.checkoutState === 'reclaimed')
397
772
  return false;
773
+ if (!this.disposalSupported && (workspace.disposalPolicy === 1 || artifact.disposalPolicy === 1)) {
774
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('disposal-platform-unsupported');
775
+ }
776
+ if (workspace.blocked)
777
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('preserved-for-recovery');
778
+ if (artifact.recovery)
779
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('parent-application-unresolved');
780
+ if (workspace.pendingTaskId || artifact.disposition === 'pending')
781
+ return false;
782
+ await this.validateReclamationArtifact(workspace, artifact);
783
+ if (workspace.checkoutState === 'reclaiming' && !await this.pathExists(workspace.directory)) {
784
+ if (await this.registration(workspace.source, workspace.directory))
785
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('partial-registration');
786
+ await this.write('lanes', laneId, { ...workspace, checkoutState: 'reclaimed', cleanup: undefined });
787
+ return true;
788
+ }
398
789
  await this.verifyCheckout(workspace, artifact);
399
790
  const intent = { ...workspace, checkoutState: 'reclaiming',
400
791
  reclamation: { taskId, output: artifact.output, tree: artifact.tree } };
@@ -409,11 +800,22 @@ class DelegatedWorkspaceManager {
409
800
  if (!registered || registered.locked || registered.head !== artifact.output) {
410
801
  throw new Error('Worker registration changed before removal');
411
802
  }
412
- await (0, GitCheckpoint_1.runGit)(workspace.source.root, ['worktree', 'remove', workspace.directory]);
803
+ try {
804
+ await (0, GitCheckpoint_1.runGit)(workspace.source.root, ['worktree', 'remove',
805
+ ...(workspace.disposalPolicy === 1 ? ['--force'] : []), workspace.directory]);
806
+ }
807
+ catch {
808
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('removal-failed', true);
809
+ }
413
810
  if (await this.pathExists(workspace.directory) || await this.registration(workspace.source, workspace.directory)) {
414
811
  throw new Error('Worker checkout removal was not confirmed');
415
812
  }
416
- await this.write('lanes', laneId, { ...intent, checkoutState: 'reclaimed' });
813
+ try {
814
+ await this.write('lanes', laneId, { ...intent, checkoutState: 'reclaimed', cleanup: undefined });
815
+ }
816
+ catch {
817
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('receipt-write-failed', true);
818
+ }
417
819
  return true;
418
820
  });
419
821
  }
@@ -421,9 +823,30 @@ class DelegatedWorkspaceManager {
421
823
  await this.validateWorkspaceRecord(workspace);
422
824
  await this.validateArtifact(artifact, { threadId: workspace.threadId, cwd: workspace.source.cwd,
423
825
  workspaceGeneration: workspace.workspaceGeneration });
826
+ if (workspace.disposalPolicy === 1 || artifact.disposalPolicy !== undefined) {
827
+ if (workspace.disposalPolicy !== 1 || artifact.disposalPolicy !== 1)
828
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('policy-mismatch');
829
+ if (!artifact.closeout)
830
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('child-exit-unconfirmed');
831
+ const receipt = artifact.closeout;
832
+ if (receipt.taskId !== artifact.taskId || receipt.output !== artifact.output || receipt.tree !== artifact.tree
833
+ || !Number.isFinite(receipt.exitConfirmedAt) || receipt.exitConfirmedAt <= 0)
834
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('invalid-exit-receipt');
835
+ if (receipt.recoverable !== true)
836
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('recovery-unverified');
837
+ if (artifact.disposition !== 'applied' && artifact.disposition !== 'retained')
838
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('delivery-pending');
839
+ if (!artifact.successful && artifact.disposition === 'applied' && artifact.tree !== artifact.input.tree) {
840
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('invalid-failed-disposition');
841
+ }
842
+ await (0, WorkspaceDisposal_1.verifyWorkspaceExports)(await this.exportDirectory(artifact.taskId), artifact.exports ?? []);
843
+ }
844
+ else if (artifact.successful !== true || artifact.disposition !== 'applied') {
845
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('legacy-policy');
846
+ }
424
847
  if (artifact.laneId !== workspace.laneId || artifact.taskId !== workspace.taskId
425
848
  || artifact.input.commit !== workspace.input.commit || artifact.input.tree !== workspace.input.tree
426
- || artifact.successful !== true || artifact.disposition !== 'applied' || artifact.recovery
849
+ || artifact.recovery
427
850
  || workspace.blocked || workspace.pendingTaskId
428
851
  || !GitCheckpoint_1.GIT_OID.test(artifact.originalHead)
429
852
  || await (0, GitCheckpoint_1.gitText)(workspace.source.root, ['rev-parse', workspace.taskRef]) !== artifact.output
@@ -446,14 +869,14 @@ class DelegatedWorkspaceManager {
446
869
  const exists = await this.pathExists(workspace.directory);
447
870
  const registered = await this.registration(workspace.source, workspace.directory);
448
871
  if (!exists && !registered) {
449
- const reclaimed = { ...workspace, checkoutState: 'reclaimed' };
872
+ const reclaimed = { ...workspace, checkoutState: 'reclaimed', cleanup: undefined };
450
873
  await this.write('lanes', workspace.laneId, reclaimed);
451
874
  return reclaimed;
452
875
  }
453
876
  if (workspace.checkoutState === 'reclaiming' && exists && registered) {
454
877
  // A fully intact checkout can cancel an interrupted intent. Partial/foreign paths cannot.
455
878
  await this.verifyCheckout(workspace, artifact);
456
- const present = { ...workspace, checkoutState: 'present', reclamation: undefined };
879
+ const present = { ...workspace, checkoutState: 'present', reclamation: undefined, cleanup: undefined };
457
880
  await this.write('lanes', workspace.laneId, present);
458
881
  return present;
459
882
  }
@@ -461,6 +884,7 @@ class DelegatedWorkspaceManager {
461
884
  }
462
885
  async verifyCheckout(workspace, artifact) {
463
886
  await this.validateWorkspace(workspace);
887
+ const disposable = workspace.disposalPolicy === 1 && artifact.disposalPolicy === 1;
464
888
  const registered = await this.registration(workspace.source, workspace.directory);
465
889
  if (!registered || registered.locked || registered.head !== artifact.output
466
890
  || await (0, GitCheckpoint_1.gitText)(workspace.directory, ['branch', '--show-current'])
@@ -468,7 +892,16 @@ class DelegatedWorkspaceManager {
468
892
  || (await (0, GitCheckpoint_1.runGit)(workspace.directory, ['ls-files', '-u', '-z'])).length) {
469
893
  throw new Error('Worker checkout is locked, unresolved, or no longer at its saved output');
470
894
  }
471
- await this.assertClean(workspace.directory);
895
+ if (disposable) {
896
+ if ((await (0, GitCheckpoint_1.runGit)(workspace.directory, ['status', '--porcelain=v1', '-z', '--untracked-files=no'])).length) {
897
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('tracked-files-changed');
898
+ }
899
+ const entries = (await (0, GitCheckpoint_1.runGit)(workspace.directory, ['ls-files', '-v', '-z'])).toString('utf8').split('\0').filter(Boolean);
900
+ if (entries.some(entry => !entry.startsWith('H ')))
901
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('hidden-index-state');
902
+ }
903
+ else
904
+ await this.assertClean(workspace.directory);
472
905
  // Git status and a copied index can hide changed bytes behind assume-unchanged,
473
906
  // skip-worktree, or stat-cache flags. Hash actual bytes without filters or index metadata.
474
907
  const files = new Map();
@@ -493,6 +926,17 @@ class DelegatedWorkspaceManager {
493
926
  parent = path_1.default.posix.dirname(parent);
494
927
  }
495
928
  }
929
+ if (disposable) {
930
+ const attributes = (await (0, GitCheckpoint_1.runGit)(workspace.directory, ['check-attr', '-z', '--stdin', 'filter'], Buffer.from([...files.keys()].join('\0') + '\0'))).toString('utf8').split('\0');
931
+ for (let index = 2; index < attributes.length; index += 3) {
932
+ if (attributes[index] === 'lfs')
933
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('lfs-payload-unverified');
934
+ if (!['unspecified', 'unset'].includes(attributes[index]))
935
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('unsupported-filter');
936
+ }
937
+ await (0, WorkspaceDisposal_1.assertDisposableTree)(workspace.directory);
938
+ await (0, WorkspaceDisposal_1.verifyWorkspaceExports)(await this.exportDirectory(artifact.taskId), artifact.exports ?? [], workspace.directory);
939
+ }
496
940
  const walk = async (relative) => {
497
941
  const absolute = path_1.default.join(workspace.directory, relative);
498
942
  if (await promises_1.default.realpath(absolute) !== absolute)
@@ -513,6 +957,8 @@ class DelegatedWorkspaceManager {
513
957
  files.delete(child);
514
958
  return;
515
959
  }
960
+ if (!expected && disposable)
961
+ return; // The complete boundary walk above validated disposable extras.
516
962
  if (!expected || (expected.mode === '120000' ? !stat.isSymbolicLink() : !stat.isFile())) {
517
963
  throw new Error('Checkout contains unknown, ignored, or unsupported files');
518
964
  }
@@ -627,12 +1073,21 @@ class DelegatedWorkspaceManager {
627
1073
  }
628
1074
  // Compatible with Git 2.34: merge in an owned scratch checkout, never in the user's worktree.
629
1075
  const wrapper = await (0, GitCheckpoint_1.createCheckpointCommit)(artifact.source.root, current.tree, artifact.input.commit, `Remote CLI integration input ${artifact.taskId}`);
630
- const integrationDirectory = await promises_1.default.mkdtemp(path_1.default.join(this.directory, 'integration-'));
1076
+ const scratchId = (0, crypto_1.randomUUID)();
1077
+ const integrationDirectory = path_1.default.join(this.directory, `integration-${scratchId}`);
1078
+ const scratch = { id: scratchId, taskId: artifact.taskId, laneId: artifact.laneId,
1079
+ directory: integrationDirectory, source: artifact.source, state: 'allocating', updatedAt: Date.now() };
1080
+ await this.write('scratch', scratchId, scratch);
1081
+ const recordScratch = async (state, holdReason) => {
1082
+ await this.write('scratch', scratchId, { ...scratch, state, holdReason, updatedAt: Date.now() });
1083
+ };
1084
+ await promises_1.default.mkdir(integrationDirectory, { mode: 0o700 });
631
1085
  let created = false;
632
1086
  let preserve = false;
633
1087
  try {
634
1088
  await this.withRepository(artifact.source, () => (0, GitCheckpoint_1.runGit)(artifact.source.root, ['worktree', 'add', '--detach', integrationDirectory, wrapper]));
635
1089
  created = true;
1090
+ await recordScratch('present');
636
1091
  try {
637
1092
  await (0, GitCheckpoint_1.runGit)(integrationDirectory, ['-c', 'user.name=Remote CLI', '-c', 'user.email=remote-cli@example.com',
638
1093
  'merge', '--no-commit', '--no-ff', '--no-edit', artifact.output]);
@@ -643,6 +1098,7 @@ class DelegatedWorkspaceManager {
643
1098
  if (!conflicts.length)
644
1099
  throw error;
645
1100
  preserve = true;
1101
+ await recordScratch('conflict', 'integration-conflict');
646
1102
  return { ...await this.view(artifact), applied: false, conflicts: conflicts.slice(0, 60),
647
1103
  conflictsTruncated: conflicts.length > 60, recoveryDirectory: integrationDirectory,
648
1104
  detail: 'Merge conflicts are isolated here. The delivery workspace has not been changed.' };
@@ -681,13 +1137,25 @@ class DelegatedWorkspaceManager {
681
1137
  finally {
682
1138
  if (created && !preserve) {
683
1139
  // This directory contains only captured integration input and a reproducible merge result.
684
- await this.withRepository(artifact.source, () => (0, GitCheckpoint_1.runGit)(artifact.source.root, ['worktree', 'remove', '--force', integrationDirectory]))
685
- .catch(() => console.warn('[Delegation] Integration scratch worktree retained for manual cleanup'));
1140
+ try {
1141
+ await this.withRepository(artifact.source, () => (0, GitCheckpoint_1.runGit)(artifact.source.root, ['worktree', 'remove', '--force', integrationDirectory]));
1142
+ await recordScratch('reclaimed');
1143
+ }
1144
+ catch {
1145
+ await recordScratch('cleanup-pending', 'scratch-removal-failed').catch(() => undefined);
1146
+ console.warn('[Delegation] Integration scratch worktree retained for manual cleanup');
1147
+ }
686
1148
  }
687
1149
  else if (!created) {
688
1150
  // Failed setup can leave partial files; preserve them without masking the setup error.
689
- await promises_1.default.rmdir(integrationDirectory)
690
- .catch(() => console.warn('[Delegation] Partial integration directory retained for manual cleanup'));
1151
+ try {
1152
+ await promises_1.default.rmdir(integrationDirectory);
1153
+ await recordScratch('reclaimed');
1154
+ }
1155
+ catch {
1156
+ await recordScratch('cleanup-pending', 'scratch-setup-incomplete').catch(() => undefined);
1157
+ console.warn('[Delegation] Partial integration directory retained for manual cleanup');
1158
+ }
691
1159
  }
692
1160
  }
693
1161
  }
@@ -705,7 +1173,8 @@ class DelegatedWorkspaceManager {
705
1173
  baseCommit: artifact.input.commit, outputCommit: artifact.output,
706
1174
  changedFiles: files.slice(0, 60), filesTruncated: files.length > 60,
707
1175
  ...(artifact.deliveredAtHead ? { deliveredAtHead: artifact.deliveredAtHead } : {}),
708
- ...(artifact.recovery ? { recovery: artifact.recovery } : {}) };
1176
+ ...(artifact.recovery ? { recovery: artifact.recovery } : {}),
1177
+ ...(artifact.exports ? { exports: artifact.exports } : {}) };
709
1178
  }
710
1179
  async assertSelectedScope(artifact) {
711
1180
  // Rename detection hides the removed source path from --name-only; validate BOTH endpoints.
@@ -750,9 +1219,18 @@ class DelegatedWorkspaceManager {
750
1219
  }
751
1220
  if (!inside(workspace.directory, await promises_1.default.realpath(workspace.cwd)))
752
1221
  throw new Error('Worker directory escapes its worktree');
1222
+ if (workspace.disposalPolicy === 1) {
1223
+ const stat = await promises_1.default.lstat(workspace.directory);
1224
+ if (!stat.isDirectory() || stat.isSymbolicLink() || !workspace.checkoutIdentity
1225
+ || workspace.checkoutIdentity.dev !== stat.dev || workspace.checkoutIdentity.ino !== stat.ino) {
1226
+ throw new WorkspaceDisposal_1.WorkspaceCleanupError('checkout-identity-changed');
1227
+ }
1228
+ }
753
1229
  }
754
1230
  assertLifecycle(workspace) {
755
1231
  const state = workspace.checkoutState ?? 'present';
1232
+ if (workspace.disposalPolicy !== undefined && workspace.disposalPolicy !== 1)
1233
+ throw new Error('Unknown workspace disposal policy');
756
1234
  if (!['present', 'reclaiming', 'reclaimed'].includes(state)
757
1235
  || (state === 'present' ? workspace.reclamation !== undefined : !workspace.reclamation)) {
758
1236
  throw new Error('Invalid worker checkout lifecycle');
@@ -790,7 +1268,14 @@ class DelegatedWorkspaceManager {
790
1268
  return this.serialize(`lane:${path_1.default.resolve(this.directory)}:${laneId}`, operation);
791
1269
  }
792
1270
  withRepository(source, operation) {
793
- return this.serialize(`repository:${source.commonDirectory}`, operation);
1271
+ const held = this.repositoryContext.getStore();
1272
+ if (held?.has(source.commonDirectory))
1273
+ return operation();
1274
+ return this.serialize(`repository:${source.commonDirectory}`, async () => {
1275
+ await this.beforeMutation?.();
1276
+ const run = () => this.repositoryContext.run(new Set([...(held ?? []), source.commonDirectory]), operation);
1277
+ return this.ownership ? this.ownership.withRepository(source.commonDirectory, run) : run();
1278
+ });
794
1279
  }
795
1280
  async serialize(key, operation) {
796
1281
  const previous = DelegatedWorkspaceManager.operations.get(key) ?? Promise.resolve();
@@ -808,8 +1293,9 @@ class DelegatedWorkspaceManager {
808
1293
  }
809
1294
  }
810
1295
  async initialize() {
1296
+ await this.beforeMutation?.();
811
1297
  await this.safeDirectory(this.directory);
812
- await Promise.all(['lanes', 'artifacts', 'trees'].map(name => this.safeDirectory(path_1.default.join(this.directory, name))));
1298
+ await Promise.all(['lanes', 'artifacts', 'trees', 'scratch'].map(name => this.safeDirectory(path_1.default.join(this.directory, name))));
813
1299
  }
814
1300
  async safeDirectory(directory) {
815
1301
  await promises_1.default.mkdir(directory, { recursive: true, mode: 0o700 });