Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

feat(cos): retire held checkouts under a scoped, archived release (#12002)

[._.]/ Adam Eivyed57c8c47867
diff --git a/client/src/components/cos/tabs/schedule/AppTaskCard.test.jsx b/client/src/components/cos/tabs/schedule/AppTaskCard.test.jsx
index 7980eeb7a2..8eb73f9fa2 100644
--- a/client/src/components/cos/tabs/schedule/AppTaskCard.test.jsx
+++ b/client/src/components/cos/tabs/schedule/AppTaskCard.test.jsx
@@ -63,9 +63,9 @@ describe('AppTaskCard', () => {
expect(screen.getByText('Lock: <script>owner handoff</script>')).toBeVisible();
expect(document.querySelector('script')).toBeNull();
expect(screen.getByText('Outside managed worktree roots')).toBeVisible();
- expect(screen.getByText(/Checkout recovery requires verified owner authority/)).toBeVisible();
+ expect(screen.getByText(/Retiring a checkout is a scoped release/)).toBeVisible();
expect(screen.getByText('Resolve the listed holds and run again.')).toBeVisible();
- expect(screen.queryByRole('button', { name: /Remove|Unlock|Retire/i })).toBeNull();
+ expect(screen.getByRole('button', { name: 'Archive and retire checkout…' })).toBeVisible();
});
it('distinguishes an unreadable inventory from a completed empty scan', () => {
diff --git a/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.jsx b/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.jsx
index 37265ca7aa..07b92ff49d 100644
--- a/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.jsx
+++ b/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.jsx
@@ -1,42 +1,111 @@
+import { useState } from 'react';
import { formatCount, formatDateTime } from '../../../../utils/formatters';
+import { retireBranchReconcileCheckout } from '../../../../services/api';
const STATUS_LABELS = { drained: 'No remaining work in last scan', incomplete: 'Incomplete', running: 'Sweep running' };
+// Only a post-cleanup inventory row carries the exact checkout identity a
+// scoped release must name; branch-only holds have nothing to release.
+const isInventoriedCheckout = entry => Boolean(entry.path && entry.head && typeof entry.locked === 'boolean');
+
+// The confirmation IS the scoped release: it names this row's path, HEAD,
+// branch and lock text, and the server refuses if any of them changed since.
+function RetireCheckout({ appId, entry, onRetired }) {
+ const [state, setState] = useState('idle');
+ const [error, setError] = useState(null);
+ const retire = async () => {
+ setState('pending');
+ setError(null);
+ const result = await retireBranchReconcileCheckout({
+ appId, path: entry.path, head: entry.head, branch: entry.branch ?? null, locked: entry.locked, lockReason: entry.lockReason ?? null,
+ }, { silent: true }).catch(err => {
+ setError(err?.message || 'Checkout retirement failed');
+ return null;
+ });
+ if (!result) {
+ setState('idle');
+ return;
+ }
+ onRetired(entry.path);
+ };
+ if (state === 'idle') {
+ return (
+ <div className="pt-1">
+ <button type="button" className="text-port-accent hover:underline" onClick={() => setState('confirming')}>Archive and retire checkout…</button>
+ {error && <p role="alert" className="text-port-error break-words">{error}</p>}
+ </div>
+ );
+ }
+ return (
+ <div className="mt-1 space-y-1 rounded border border-port-warning/50 p-2">
+ <p className="text-gray-300">
+ Release this exact checkout{entry.locked ? ' and its lock' : ''}? Tracked edits, untracked and ignored files are archived first
+ {entry.branch ? `, then the checkout and branch ${entry.branch} are removed` : ', then the checkout is removed'}. A changed lock, HEAD or a live owner keeps everything in place.
+ </p>
+ <div className="flex gap-2">
+ <button type="button" className="rounded border border-port-border px-2 py-1" disabled={state === 'pending'} onClick={() => setState('idle')}>Cancel</button>
+ <button type="button" className="rounded bg-port-error/80 px-2 py-1 text-white disabled:opacity-50" disabled={state === 'pending'} onClick={retire}>
+ {state === 'pending' ? 'Archiving…' : 'Yes, archive and retire'}
+ </button>
+ </div>
+ </div>
+ );
+}
+
// A persisted scan describes convergence independently of coordinator success.
// Paths and lock text are display data, never executable recovery instructions.
export default function BranchReconcileOutcome({ outcomes, apps }) {
+ // Hides a retired row at once; the schedule socket event replaces the outcome.
+ const [retiredPaths, setRetiredPaths] = useState(() => new Set());
if (!outcomes || !Object.keys(outcomes).length) return null;
+ const markRetired = path => setRetiredPaths(current => new Set(current).add(path));
return (
<div className="mx-4 mb-3 space-y-2 text-xs">
- {Object.entries(outcomes).map(([appId, outcome]) => (
- <details key={appId} className="rounded border border-port-border p-2">
- <summary className="cursor-pointer text-gray-300">
- {apps?.find(app => app.id === appId)?.name || (appId === 'null' ? 'Repository' : appId)}
- {' · '}{STATUS_LABELS[outcome.status] || 'Outcome unavailable'}
- {Array.isArray(outcome.remaining) && ` · ${formatCount(outcome.remaining.length)} remaining`}
- </summary>
- <div className="mt-2 space-y-2 text-gray-400">
- <p>{outcome.observedAt ? `Last inventory: ${formatDateTime(outcome.observedAt)}` : 'No readable inventory yet.'}</p>
- {outcome.reason && <p className="break-words">Reason: {outcome.reason}</p>}
- {outcome.nextAction && <p>{outcome.nextAction}</p>}
- {!Array.isArray(outcome.remaining) && <p>Remaining work is unknown.</p>}
- <ul className="space-y-2 max-h-64 overflow-y-auto">
- {(outcome.remaining || []).map((entry, index) => (
- <li key={`${entry.path || entry.branch || entry.issue || entry.reason}:${index}`} className="break-words border-t border-port-border pt-2">
- <p className="text-gray-300">{entry.branch || (entry.detached ? 'Detached checkout' : entry.issue ? `Issue #${entry.issue}` : 'Repository scan')}: {entry.reason}</p>
- {entry.path && <p className="break-all">{entry.path}</p>}
- {entry.head && <p className="break-all">HEAD: {entry.head}</p>}
- {entry.locked && <p>Lock: {entry.lockReason || 'No reason recorded'}</p>}
- {entry.managed === false && <p>Outside managed worktree roots</p>}
- </li>
- ))}
- </ul>
- {(outcome.remaining || []).some(entry => entry.path) && (
- <p>Checkout recovery requires verified owner authority or a scoped release, fresh ownership and merge checks, and a verified archive of unique tracked, untracked and ignored content. Lock age, an absent process, and lock text do not prove release. Keep active owners and manual handoffs protected.</p>
- )}
- </div>
- </details>
- ))}
+ {Object.entries(outcomes).map(([appId, outcome]) => {
+ const remaining = Array.isArray(outcome.remaining) ? outcome.remaining.filter(entry => !retiredPaths.has(entry.path)) : null;
+ return (
+ <details key={appId} className="rounded border border-port-border p-2">
+ <summary className="cursor-pointer text-gray-300">
+ {apps?.find(app => app.id === appId)?.name || (appId === 'null' ? 'Repository' : appId)}
+ {' · '}{STATUS_LABELS[outcome.status] || 'Outcome unavailable'}
+ {remaining && ` · ${formatCount(remaining.length)} remaining`}
+ </summary>
+ <div className="mt-2 space-y-2 text-gray-400">
+ <p>{outcome.observedAt ? `Last inventory: ${formatDateTime(outcome.observedAt)}` : 'No readable inventory yet.'}</p>
+ {outcome.reason && <p className="break-words">Reason: {outcome.reason}</p>}
+ {outcome.nextAction && <p>{outcome.nextAction}</p>}
+ {!remaining && <p>Remaining work is unknown.</p>}
+ <ul className="space-y-2 max-h-64 overflow-y-auto">
+ {(remaining || []).map((entry, index) => (
+ <li key={`${entry.path || entry.branch || entry.issue || entry.reason}:${index}`} className="break-words border-t border-port-border pt-2">
+ <p className="text-gray-300">{entry.branch || (entry.detached ? 'Detached checkout' : entry.issue ? `Issue #${entry.issue}` : 'Repository scan')}: {entry.reason}</p>
+ {entry.path && <p className="break-all">{entry.path}</p>}
+ {entry.head && <p className="break-all">HEAD: {entry.head}</p>}
+ {entry.locked && <p>Lock: {entry.lockReason || 'No reason recorded'}</p>}
+ {entry.managed === false && <p>Outside managed worktree roots</p>}
+ {appId !== 'null' && isInventoriedCheckout(entry) && <RetireCheckout appId={appId} entry={entry} onRetired={markRetired} />}
+ </li>
+ ))}
+ </ul>
+ {(remaining || []).some(entry => entry.path) && (
+ <p>Retiring a checkout is a scoped release of the exact row shown. It needs merged work, no live owner or manual handoff, and a verified archive of unique tracked, untracked and ignored content. Lock age, an absent process, and lock text never release a checkout on their own.</p>
+ )}
+ {Array.isArray(outcome.retired) && outcome.retired.length > 0 && (
+ <div>
+ <p className="text-gray-300">Recently retired</p>
+ <ul className="space-y-1">
+ {outcome.retired.map(item => (
+ <li key={`${item.path}:${item.retiredAt}`} className="break-all">
+ {item.branch || 'Detached checkout'} · {formatDateTime(item.retiredAt)} · archive {item.archiveDir}
+ </li>
+ ))}
+ </ul>
+ </div>
+ )}
+ </div>
+ </details>
+ );
+ })}
</div>
);
}
diff --git a/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.test.jsx b/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.test.jsx
new file mode 100644
index 0000000000..116469d634
--- /dev/null
+++ b/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.test.jsx
@@ -0,0 +1,47 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+
+const retire = vi.hoisted(() => vi.fn());
+vi.mock('../../../../services/api', () => ({ retireBranchReconcileCheckout: retire }));
+
+import BranchReconcileOutcome from './BranchReconcileOutcome';
+
+const held = {
+ path: '/example/held', branch: 'fix/example', head: 'a'.repeat(40), locked: true, lockReason: 'owner handoff',
+ managed: false, reason: 'worktree-locked',
+};
+const outcomes = { 'app-1': { status: 'incomplete', observedAt: '2026-10-01T00:00:00Z', remaining: [held, { branch: 'other', reason: 'actionable' }] } };
+
+function open() {
+ render(<BranchReconcileOutcome outcomes={outcomes} apps={[{ id: 'app-1', name: 'Example App' }]} />);
+ fireEvent.click(screen.getByText(/Example App · Incomplete · 2 remaining/));
+ fireEvent.click(screen.getByRole('button', { name: 'Archive and retire checkout…' }));
+}
+
+describe('BranchReconcileOutcome checkout retirement', () => {
+ beforeEach(() => { retire.mockReset(); });
+
+ it('sends the exact inventory row as the scoped release and drops the row once retired', async () => {
+ retire.mockResolvedValue({ ok: true, archiveDir: '/example/archive', branchDeleted: true });
+ open();
+ expect(screen.getByText(/Release this exact checkout and its lock\?/)).toBeVisible();
+ fireEvent.click(screen.getByRole('button', { name: 'Yes, archive and retire' }));
+
+ await waitFor(() => expect(screen.queryByText('/example/held')).toBeNull());
+ expect(retire).toHaveBeenCalledWith({
+ appId: 'app-1', path: held.path, head: held.head, branch: held.branch, locked: true, lockReason: 'owner handoff',
+ }, { silent: true });
+ expect(screen.getByText(/Example App · Incomplete · 1 remaining/)).toBeVisible();
+ expect(screen.queryByRole('button', { name: 'Archive and retire checkout…' })).toBeNull();
+ });
+
+ it('keeps the row and shows why the server kept the checkout', async () => {
+ retire.mockRejectedValue(new Error('Checkout kept: checkout-lock-changed'));
+ open();
+ fireEvent.click(screen.getByRole('button', { name: 'Yes, archive and retire' }));
+
+ expect(await screen.findByRole('alert')).toHaveTextContent('Checkout kept: checkout-lock-changed');
+ expect(screen.getByText('/example/held')).toBeVisible();
+ expect(screen.getByRole('button', { name: 'Archive and retire checkout…' })).toBeVisible();
+ });
+});
diff --git a/client/src/services/apiAgents.js b/client/src/services/apiAgents.js
index 6f8ce411a4..6a62e81714 100644
--- a/client/src/services/apiAgents.js
+++ b/client/src/services/apiAgents.js
@@ -396,6 +396,12 @@ export const triggerCosOnDemandTask = (taskType, appId = null, options = {}) =>
body: JSON.stringify({ taskType, appId }),
...options
});
+// Archive and retire one held checkout named exactly as the last branch-reconcile inventory reported it.
+export const retireBranchReconcileCheckout = ({ appId, path, head, branch = null, locked, lockReason = null }, options = {}) => request('/cos/schedule/branch-reconcile/checkouts/retire', {
+ method: 'POST',
+ body: JSON.stringify({ appId, path, head, branch, locked, lockReason }),
+ ...options
+});
// Autonomous Jobs
export const getCosJobs = (options = {}) => request('/cos/jobs', options);
diff --git a/docs/API.md b/docs/API.md
index 2aabf5d864..018a059954 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -313,6 +313,7 @@ Context tools remain read-only. Semantic reads and writes are independent, defau
| GET | `/cos/schedule/task/:taskType` | Get interval and schedule settings for a task type |
| PUT | `/cos/schedule/task/:taskType` | Update schedule settings for a task type (`type`: `on-demand` \| `cron`; `cronExpression`: 5-field or null; `perpetual`: boolean drain flag, orthogonal to `type`; `autoStart`: set false for manual-only on-demand drains, omitted preserves legacy automatic starts/rechecks) |
| POST | `/cos/schedule/trigger` | Trigger an on-demand task run |
+| POST | `/cos/schedule/branch-reconcile/checkouts/retire` | Archive and retire one held checkout named exactly as the last branch-reconcile inventory reported it (operator only) |
| GET | `/cos/schedule/maintenance-runs` | List manual maintenance runs (the Schedule tab's "Run maintenance now"; running first, then recent history) |
| POST | `/cos/schedule/maintenance-runs` | Start a manual maintenance run for one app (`appId`, `providerId`, `model`, optional `effort`); returns the run and its first dispatch or hold reason. Independent of Quota Burn |
| POST | `/cos/schedule/maintenance-runs/:id/stop` | Stop a run from dispatching further steps (a task already queued or running is not recalled) |
diff --git a/docs/features/branch-reconciliation.md b/docs/features/branch-reconciliation.md
index aa85ffc449..bca9c4915f 100644
--- a/docs/features/branch-reconciliation.md
+++ b/docs/features/branch-reconciliation.md
@@ -18,17 +18,27 @@ unmerged work are included, even though merged-checkout cleanup cannot retire
them. A failed or empty Git checkout listing is unknown evidence and prevents a
completed empty-scan outcome. Lock text is descriptive data, never authority.
-This is a recovery inventory, not an unlock or retirement control. Retained
-checkouts remain protected. Before a future recovery action can retire one, it
-must prove existing owner authority or an explicit scoped release, recheck the
-exact checkout/HEAD, merge evidence and ownership immediately before mutation,
-and verify a recoverable archive of all unique tracked, untracked and ignored
-content. An archive failure must leave the checkout and branch intact. Lock age,
-an absent process, and natural-language lock text do not prove release; live
-owners and manual handoffs remain protected.
+Lock age, an absent process, and natural-language lock text never release a
+checkout on their own. Long-lived protected branches and the primary checkout
+remain governed by the existing reconciliation policy; an empty reported work
+list is not permission to remove them.
-The remaining scope of #12002 is an enforceable scoped release and archived
-retirement workflow with ownership-change and archive-failure integration tests.
-The inventory does not grant that authority. Long-lived protected branches and
-the primary checkout remain governed by the existing reconciliation policy;
-an empty reported work list is not permission to remove them.
+## Retiring a held checkout
+
+A row with a checkout path and HEAD offers **Archive and retire checkout**. The
+inline confirmation is a scoped release of that exact row: its path, HEAD,
+branch and lock text. The server refuses unless the row is in the app's last
+persisted inventory and a fresh Git read still matches it — a changed lock,
+HEAD or branch is an ownership change. It then requires merge evidence on the
+default branch and no live owner, claim binding or manual completion handoff.
+
+Before any mutation, every unique byte is archived under
+`data/cos/held-checkout-archives/`: commits not on the default branch, the
+tracked diff, verbatim copies of untracked and ignored files (hash-verified),
+and symlink targets. A nested repository, an oversized file or a write during
+archiving fails the archive, which leaves the checkout, its lock and its
+branch untouched and removes the partial archive. The lock is released only
+after a second fresh match, and ownership, HEAD and content are rechecked
+immediately before removal; if that recheck refuses, the original lock is
+restored. A retired row leaves the inventory and appears under *Recently
+retired* with its archive path; only the next sweep can report convergence.
diff --git a/server/lib/hostControlRoutes.js b/server/lib/hostControlRoutes.js
index 6d2a5a0a2d..23b40ed4be 100644
--- a/server/lib/hostControlRoutes.js
+++ b/server/lib/hostControlRoutes.js
@@ -384,6 +384,8 @@ export const HOST_CONTROL_ROUTES = Object.freeze([
'PUT /api/tools/:id',
'PUT /api/cos/schedule/task/:taskType',
'POST /api/cos/schedule/trigger',
+ // Archives and removes a checkout and its merged branch under a scoped release.
+ 'POST /api/cos/schedule/branch-reconcile/checkouts/retire',
'POST /api/cos/schedule/maintenance-runs',
// Editing a pending stage changes the provider used by deferred host work.
'PATCH /api/cos/schedule/maintenance-runs/:id/steps/:stepId',
diff --git a/server/lib/validation.js b/server/lib/validation.js
index a5e2b63eb4..2209e5232d 100644
--- a/server/lib/validation.js
+++ b/server/lib/validation.js
@@ -2833,6 +2833,15 @@ export const cosAgentFeedbackBodySchema = z.object({
export const cosAgentBtwBodySchema = z.object({ message: z.string().trim().min(1).max(5000) });
export const cosTaskReorderBodySchema = z.object({ taskIds: z.array(nonEmptyString) });
export const cosScheduleTargetBodySchema = z.object({ taskType: nonEmptyString, appId: nullishString });
+// A scoped release names the exact inventory row the operator saw (#12002).
+export const heldCheckoutRetireBodySchema = z.object({
+ appId: nonEmptyString,
+ path: nonEmptyString,
+ head: z.string().regex(/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/),
+ branch: z.string().min(1).nullable(),
+ locked: z.boolean(),
+ lockReason: z.string().nullable(),
+});
// Per-app task-type overrides (routes/apps/taskTypes.js)
export const appTaskTypeToggleBodySchema = z.object({ enabled: z.boolean() });
diff --git a/server/routes/cosScheduleRoutes.js b/server/routes/cosScheduleRoutes.js
index 5800db4e71..5eac1776e8 100644
--- a/server/routes/cosScheduleRoutes.js
+++ b/server/routes/cosScheduleRoutes.js
@@ -9,7 +9,7 @@ import { z } from 'zod';
import * as taskSchedule from '../services/taskSchedule.js';
import { logCosScheduleUpdate } from '../services/userActionScheduleLog.js';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
-import { sanitizeTaskMetadata, taskDataInputsSchema, validateRequest, parsePagination, cosScheduleTargetBodySchema } from '../lib/validation.js';
+import { sanitizeTaskMetadata, taskDataInputsSchema, validateRequest, parsePagination, cosScheduleTargetBodySchema, heldCheckoutRetireBodySchema } from '../lib/validation.js';
import { promptSourceSchema, PROMPT_SOURCES, scheduleExecutionFieldsSchema } from '../lib/cosValidation.js';
import { EFFORT_LEVELS } from '../lib/providerModels.js';
import { INTERVAL_TYPES, decodeIntervalType, isCronExpression, isKnownIntervalType } from '../services/taskScheduleConstants.js';
@@ -289,6 +289,20 @@ router.post('/schedule/trigger', asyncHandler(async (req, res) => {
res.json({ success: true, request });
}));
+// POST /api/cos/schedule/branch-reconcile/checkouts/retire - Archive and retire
+// one held checkout from the last branch-reconcile inventory (#12002)
+router.post('/schedule/branch-reconcile/checkouts/retire', asyncHandler(async (req, res) => {
+ const { appId, ...release } = validateRequest(heldCheckoutRetireBodySchema, req.body);
+ const { retireInventoriedCheckout } = await import('../services/heldCheckoutRecovery.js');
+ const result = await retireInventoriedCheckout({ appId, release });
+ if (!result.ok) {
+ throw new ServerError(`Checkout kept: ${result.reason}${result.detail ? ` (${result.detail})` : ''}`, {
+ status: result.reason === 'app-not-found' ? 404 : 409, code: 'CHECKOUT_RETIREMENT_REFUSED', context: { reason: result.reason },
+ });
+ }
+ res.json(result);
+}));
+
// Manual maintenance runs — the Schedule tab's "Run maintenance now"; see
// services/maintenanceRun.js for why this is not a quota burn.
router.get('/schedule/deep-audits/:id', asyncHandler(async (req, res) => {
diff --git a/server/services/heldCheckoutRecovery.js b/server/services/heldCheckoutRecovery.js
new file mode 100644
index 0000000000..9bb85fcd67
--- /dev/null
+++ b/server/services/heldCheckoutRecovery.js
@@ -0,0 +1,254 @@
+/**
+ * Operator-scoped retirement of a merged checkout that branch reconciliation
+ * reported but cannot retire on its own (#12002): one outside the managed
+ * worktree roots, or one behind a `git worktree lock`.
+ *
+ * Authority is a scoped release, never an inference. The operator names the
+ * exact inventory row they saw — checkout path, HEAD, branch and lock state —
+ * and that release only applies while a fresh read of the repository still
+ * matches it. A lock's age, an absent process or its prose never establish
+ * release: a changed lock, HEAD or branch is an ownership change and refuses.
+ *
+ * Before any mutation every unique byte is archived under
+ * `data/cos/held-checkout-archives/`: commits not on the default branch, the
+ * tracked diff, and verbatim copies of untracked AND ignored files (symlinks as
+ * recorded targets). The archive is verified by hash against the checkout, and
+ * the checkout's content fingerprint must not move between archive and
+ * removal. A live owner, manual completion handoff, unreadable state or archive
+ * failure leaves the checkout, its lock and its branch exactly as found.
+ */
+
+import { lstat, readlink } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { atomicWrite, copyFileGuarded, ensureDir, PATHS, rmGuarded, sha256File, writeFileGuarded } from '../lib/fileUtils.js';
+import { execGit } from '../lib/execGit.js';
+import { PROTECTED_BRANCHES } from '../lib/gitArgs.js';
+import { claimCheckoutOwnerReason } from '../lib/claimContinuation.js';
+import { backupSlug } from './supersededBackup.js';
+import { listWorktrees, forceRemoveWorktreeDir } from './worktreeManager.js';
+import { getDefaultBranch, hasBranchMergeEvidence, deleteBranch } from './git.js';
+import { withClaimOwnershipLock, readClaimOwnershipAgents } from './cosClaimOwnership.js';
+
+export const heldCheckoutArchiveRoot = (cosDir = PATHS.cos) => join(cosDir, 'held-checkout-archives');
+
+// Refuse rather than archive a subset: a partial archive followed by removal
+// would delete the rest. Larger than the superseded reap's caps because this is
+// an explicit operator action, but still bounded so a build tree cannot fill
+// the disk.
+const MAX_FILE_BYTES = 25 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 250 * 1024 * 1024;
+const GIT_OUTPUT_BYTES = 64 * 1024 * 1024;
+
+const shortBranch = (ref) => (ref ? String(ref).replace(/^refs\/heads\//, '') : null);
+const zLines = (stdout) => (stdout || '').split('\0').filter(Boolean);
+const git = (args, cwd) => execGit(args, cwd, { maxBuffer: GIT_OUTPUT_BYTES }).then(r => r.stdout || '');
+
+/** Untracked and ignored paths, excluding nothing but Git's own metadata. */
+const otherPaths = async (path) => zLines(await git(['ls-files', '--others', '-z'], path));
+
+/**
+ * One hash over everything the archive preserves, so a write that lands after
+ * the archive (or during it) is detected before removal.
+ */
+async function contentFingerprint(path) {
+ const hash = createHash('sha256');
+ hash.update(await git(['status', '--porcelain=v1', '-z', '--untracked-files=all', '--ignored=matching', '--ignore-submodules=none'], path));
+ hash.update('\0diff\0');
+ hash.update(await git(['diff', 'HEAD', '--binary'], path));
+ for (const rel of await otherPaths(path)) {
+ const info = await lstat(join(path, rel));
+ hash.update(`\0${rel}\0${info.size}\0${info.mtimeMs}\0${info.isSymbolicLink()}`);
+ }
+ return hash.digest('hex');
+}
+
+/**
+ * Write and verify the archive. Throws on anything that would leave it
+ * incomplete; the caller then retires nothing.
+ */
+async function archiveCheckout(input) {
+ const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+ const dir = join(heldCheckoutArchiveRoot(input.cosDir), `${backupSlug(input.branch || `detached-${input.tree.head}`)}-${stamp}`);
+ // An incomplete archive must not read as a restore point.
+ return writeArchive(dir, input).catch(async (error) => {
+ await rmGuarded(dir, { recursive: true, force: true }).catch(() => {});
+ throw error;
+ });
+}
+
+async function writeArchive(dir, { repoPath, tree, branch, defaultBranch, release }) {
+ const fingerprint = await contentFingerprint(tree.path);
+ await ensureDir(dir);
+
+ const commits = await git(['format-patch', `${defaultBranch}..${tree.head}`, '--stdout', '--binary'], repoPath);
+ if (commits.trim()) await writeFileGuarded(join(dir, 'commits.patch'), commits);
+ const diff = await git(['diff', 'HEAD', '--binary'], tree.path);
+ if (diff.trim()) await writeFileGuarded(join(dir, 'worktree.diff'), diff);
+
+ const files = [];
+ const symlinks = [];
+ let total = 0;
+ for (const rel of await otherPaths(tree.path)) {
+ // `ls-files --others` names a nested repository as `dir/` without its files.
+ if (rel.endsWith('/')) throw new Error(`nested repository at ${rel} cannot be archived`);
+ const source = join(tree.path, rel);
+ const info = await lstat(source);
+ if (info.isSymbolicLink()) {
+ symlinks.push({ path: rel, target: await readlink(source) });
+ continue;
+ }
+ if (!info.isFile()) throw new Error(`${rel} is not a regular file`);
+ total += info.size;
+ if (info.size > MAX_FILE_BYTES || total > MAX_TOTAL_BYTES) throw new Error(`${rel} exceeds the archive size limit`);
+ const destination = join(dir, 'files', rel);
+ await ensureDir(dirname(destination));
+ await copyFileGuarded(source, destination);
+ const [expected, actual] = await Promise.all([sha256File(source), sha256File(destination)]);
+ if (expected !== actual) throw new Error(`archived copy of ${rel} does not match`);
+ files.push({ path: rel, bytes: info.size, sha256: actual });
+ }
+ if (await contentFingerprint(tree.path) !== fingerprint) throw new Error('checkout content changed while archiving');
+
+ await atomicWrite(join(dir, 'manifest.json'), {
+ repoPath, defaultBranch, path: tree.path, head: tree.head, branch,
+ release, archivedAt: new Date().toISOString(),
+ captured: { commitsPatch: Boolean(commits.trim()), worktreeDiff: Boolean(diff.trim()), files, symlinks },
+ restore: [
+ `git -C <repo> worktree add <checkout> ${tree.head}`,
+ diff.trim() ? 'git -C <checkout> apply worktree.diff' : null,
+ files.length ? 'cp -R files/. <checkout>/' : null,
+ symlinks.length ? 'recreate manifest.captured.symlinks with ln -s' : null,
+ ].filter(Boolean),
+ });
+ return { dir, fingerprint };
+}
+
+const isAncestor = (repoPath, sha, ref) => execGit(['merge-base', '--is-ancestor', sha, ref], repoPath, { ignoreExitCode: true })
+ .then(r => r.exitCode === 0, () => false);
+
+async function ownerReason({ repoPath, tree, branch, readAgents }) {
+ const agents = await readAgents().catch(() => null);
+ if (!Array.isArray(agents)) return 'claim-ownership-unreadable';
+ const claim = claimCheckoutOwnerReason({ branchName: branch || 'HEAD', holderPath: tree.path, sourceWorkspace: repoPath, agents });
+ if (claim) return claim;
+ const [{ buildActiveOwnerIds, resolveLiveOwnerReason }, { getActiveAgentIds }] = await Promise.all([
+ import('./branchReconcile.js'), import('./agentState.js'),
+ ]);
+ // The released lock is excluded here on purpose: it was matched against the
+ // release above, and a NEW lock is caught by the registration recheck.
+ const live = resolveLiveOwnerReason({ branch, path: tree.path, locked: false, activeAgentIds: buildActiveOwnerIds(getActiveAgentIds(), agents) });
+ if (live) return live;
+ if (!branch) return null;
+ const { readBranchCompletionHold } = await import('./branchCompletionPolicy.js');
+ return readBranchCompletionHold({ repoPath, branch, retirement: true }).catch(() => 'pr-completion-policy-unavailable');
+}
+
+/** Fresh registration that still matches the release, or the reason it does not. */
+async function matchRelease(repoPath, release) {
+ const trees = await listWorktrees(repoPath).catch(() => null);
+ if (!trees?.length) return { reason: 'worktree-ownership-unreadable' };
+ const index = trees.findIndex(tree => tree.path === release.path);
+ if (index === -1) return { reason: 'checkout-not-found' };
+ const tree = trees[index];
+ if (index === 0 || tree.bare) return { reason: 'checkout-primary' };
+ if (tree.prunable) return { reason: 'worktree-prunable' };
+ if (tree.head !== release.head) return { reason: 'checkout-head-changed' };
+ if (shortBranch(tree.branch) !== (release.branch ?? null)) return { reason: 'checkout-branch-changed' };
+ if (Boolean(tree.locked) !== release.locked || (tree.lockReason ?? null) !== (release.lockReason ?? null)) {
+ return { reason: 'checkout-lock-changed' };
+ }
+ return { tree };
+}
+
+/**
+ * Archive and retire one held checkout under an operator's scoped release.
+ *
+ * @param {{ repoPath: string, release: { path: string, head: string, branch: string|null, locked: boolean, lockReason: string|null } }} input
+ * @param {{ cosDir?: string, readAgents?: () => Promise<object[]|null> }} [opts]
+ * @returns {Promise<{ ok: true, archiveDir: string, branchDeleted: boolean, branchRetainedReason?: string } | { ok: false, reason: string, detail?: string, archiveDir?: string }>}
+ */
+async function retireHeldCheckout({ repoPath, release }, { cosDir = PATHS.cos, readAgents = readClaimOwnershipAgents } = {}) {
+ const branch = release.branch ?? null;
+ if (branch && PROTECTED_BRANCHES.includes(branch)) return { ok: false, reason: 'protected-branch' };
+ const defaultBranch = await getDefaultBranch(repoPath, { allowRemote: false, strict: true }).catch(() => null);
+ if (!defaultBranch) return { ok: false, reason: 'default-branch-unavailable' };
+ if (branch === defaultBranch) return { ok: false, reason: 'protected-branch' };
+
+ return withClaimOwnershipLock(async () => {
+ const first = await matchRelease(repoPath, release);
+ if (!first.tree) return { ok: false, reason: first.reason };
+ const { tree } = first;
+ const merged = branch
+ ? await hasBranchMergeEvidence(repoPath, branch, defaultBranch).catch(() => false)
+ : await isAncestor(repoPath, tree.head, defaultBranch);
+ if (!merged) return { ok: false, reason: 'not-merged-on-recheck' };
+ const owner = await ownerReason({ repoPath, tree, branch, readAgents });
+ if (owner) return { ok: false, reason: owner };
+
+ const archive = await archiveCheckout({ repoPath, tree, branch, defaultBranch, release, cosDir })
+ .catch(error => ({ error }));
+ if (archive.error) {
+ console.error(`❌ held-checkout recovery: archive failed for ${tree.path}, checkout kept: ${archive.error.message}`);
+ return { ok: false, reason: 'archive-failed', detail: archive.error.message };
+ }
+
+ // Archiving takes time; never unlock a lock that changed hands meanwhile.
+ const second = await matchRelease(repoPath, release);
+ if (!second.tree) return { ok: false, reason: second.reason, archiveDir: archive.dir };
+ if (release.locked) {
+ const unlocked = await execGit(['worktree', 'unlock', tree.path], repoPath).then(() => true, () => false);
+ if (!unlocked) return { ok: false, reason: 'worktree-unlock-failed', archiveDir: archive.dir };
+ }
+ const verifyRemoval = async (holder) => {
+ if (!holder || holder.head !== tree.head || shortBranch(holder.branch) !== branch) return 'worktree-holder-changed';
+ const reason = await ownerReason({ repoPath, tree, branch, readAgents });
+ if (reason) return reason;
+ return await contentFingerprint(tree.path).catch(() => null) === archive.fingerprint ? null : 'checkout-content-changed';
+ };
+ const removal = await forceRemoveWorktreeDir(repoPath, tree.path, {
+ label: '🧹 held-checkout recovery: remove checkout', log: 'all', verifyRemoval,
+ });
+ if (!removal.removed) {
+ // Hand the lock back exactly as released. A lock someone took in the
+ // meantime makes this fail, which is the outcome we want anyway.
+ if (release.locked) {
+ const args = ['worktree', 'lock', ...(release.lockReason != null ? ['--reason', release.lockReason] : []), tree.path];
+ await execGit(args, repoPath).catch(err => console.warn(`⚠️ held-checkout recovery: could not restore lock on ${tree.path}: ${err.message}`));
+ }
+ return { ok: false, reason: removal.reason || 'worktree-remove-failed', archiveDir: archive.dir };
+ }
+ console.log(`🧹 held-checkout recovery: retired ${tree.path} (archive: ${archive.dir})`);
+ if (!branch) return { ok: true, archiveDir: archive.dir, branchDeleted: false };
+
+ const hold = await ownerReason({ repoPath, tree: { ...tree, path: null }, branch, readAgents });
+ if (hold) return { ok: true, archiveDir: archive.dir, branchDeleted: false, branchRetainedReason: hold };
+ const deleted = await deleteBranch(repoPath, branch, { local: true }).catch(err => ({ error: err.message }));
+ const failure = deleted?.error || (deleted?.results?.local?.startsWith?.('failed') ? deleted.results.local : null);
+ if (failure) return { ok: true, archiveDir: archive.dir, branchDeleted: false, branchRetainedReason: `delete-failed: ${failure}` };
+ return { ok: true, archiveDir: archive.dir, branchDeleted: true };
+ });
+}
+
+const sameRelease = (entry, release) => entry.path === release.path && entry.head === release.head
+ && (entry.branch ?? null) === (release.branch ?? null) && Boolean(entry.locked) === release.locked
+ && (entry.lockReason ?? null) === (release.lockReason ?? null);
+
+/**
+ * The Schedule view's entry point: the release must name a row of the app's
+ * last persisted inventory exactly, so it binds to evidence the operator saw.
+ */
+export async function retireInventoriedCheckout({ appId, release }, opts) {
+ const [{ getAppById }, taskSchedule] = await Promise.all([import('./apps.js'), import('./taskSchedule.js')]);
+ const app = await getAppById(appId);
+ if (!app?.repoPath) return { ok: false, reason: 'app-not-found' };
+ const outcome = await taskSchedule.getBranchReconcileOutcome(appId);
+ if (!outcome?.remaining?.some?.(entry => sameRelease(entry, release))) return { ok: false, reason: 'release-not-in-inventory' };
+ const result = await retireHeldCheckout({ repoPath: app.repoPath, release }, opts);
+ if (result.ok) {
+ await taskSchedule.recordHeldCheckoutRetirement(appId, {
+ path: release.path, branch: release.branch ?? null, head: release.head, branchDeleted: result.branchDeleted, archiveDir: result.archiveDir,
+ });
+ }
+ return result;
+}
diff --git a/server/services/heldCheckoutRecovery.test.js b/server/services/heldCheckoutRecovery.test.js
new file mode 100644
index 0000000000..c2ec041cb0
--- /dev/null
+++ b/server/services/heldCheckoutRecovery.test.js
@@ -0,0 +1,190 @@
+/**
+ * Scoped retirement of held checkouts through real Git (#12002): a release
+ * binds to the exact inventory row, every unique byte is archived before any
+ * mutation, and an ownership change or archive failure leaves the checkout,
+ * its lock and its branch as found.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtemp, mkdir, rm, writeFile, readFile, readdir, symlink } from 'fs/promises';
+import { existsSync, realpathSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { execGit } from '../lib/execGit.js';
+import { materializeGitRepo, SKIP_HEAVY_INTEGRATION } from '../lib/gitTestRepo.js';
+
+const SYMLINKS = process.platform !== 'win32';
+const injected = vi.hoisted(() => ({ policies: [], schedule: null, app: null }));
+
+vi.mock('./branchCompletionPolicy.js', async (importOriginal) => {
+ const actual = await importOriginal();
+ return { ...actual, readBranchCompletionHold: input => actual.readBranchCompletionHold(input, {
+ readPolicies: async () => injected.policies,
+ }) };
+});
+vi.mock('./taskScheduleStore.js', async (importOriginal) => ({
+ ...await importOriginal(),
+ loadSchedule: async () => injected.schedule,
+ updateSchedule: async (mutate) => (await mutate(injected.schedule)).result,
+}));
+vi.mock('./apps.js', () => ({ getAppById: async (id) => (injected.app?.id === id ? injected.app : null) }));
+
+const { retireInventoriedCheckout, heldCheckoutArchiveRoot } = await import('./heldCheckoutRecovery.js');
+const { recordBranchReconcileOutcome, getBranchReconcileOutcome } = await import('./taskSchedule.js');
+
+describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', () => {
+ let scratch;
+ let repo;
+ let external;
+ let cosDir;
+ const noOwners = async () => [];
+
+ beforeEach(async () => {
+ Object.assign(injected, { policies: [], schedule: { executions: {} }, app: { id: 'app-1', repoPath: null } });
+ scratch = realpathSync(await mkdtemp(join(tmpdir(), 'portos-held-checkout-')));
+ const safeRepo = join(scratch, 'repo');
+ await mkdir(safeRepo);
+ await materializeGitRepo(safeRepo, { identity: { email: '[email protected]', name: 'Test' } });
+ repo = (await execGit(['rev-parse', '--show-toplevel'], safeRepo)).stdout.trim() || safeRepo;
+ external = join(scratch, 'elsewhere');
+ cosDir = join(scratch, 'cos');
+ await mkdir(external);
+ injected.app.repoPath = repo;
+ });
+ afterEach(async () => {
+ await rm(scratch, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+ });
+
+ /** A locked checkout outside the managed roots holding unique uncommitted work. */
+ async function heldCheckout(name, { branch = null, lockReason = 'synthetic external owner' } = {}) {
+ const path = join(external, name);
+ await execGit(['worktree', 'add', ...(branch ? ['-b', branch, path] : ['--detach', path]), 'main'], repo);
+ await writeFile(join(path, '.gitignore'), 'ignored.txt\nlinked\n');
+ await writeFile(join(path, 'initial.txt'), 'tracked edit\n');
+ await writeFile(join(path, 'untracked.txt'), 'untracked work\n');
+ await writeFile(join(path, 'ignored.txt'), 'ignored work\n');
+ // Windows runners may lack symlink privilege; the archive contract is the same.
+ if (SYMLINKS) await symlink('../shared-target', join(path, 'linked'));
+ await execGit(['worktree', 'lock', '--reason', lockReason, path], repo);
+ const gitPath = (await execGit(['rev-parse', '--show-toplevel'], path)).stdout.trim();
+ const head = (await execGit(['rev-parse', 'HEAD'], path)).stdout.trim();
+ return { path, release: { path: gitPath, head, branch, locked: true, lockReason } };
+ }
+
+ const registered = async (path) => (await execGit(['worktree', 'list', '--porcelain'], repo)).stdout.includes(`worktree ${path}`);
+ const lockText = async (path) => (await execGit(['worktree', 'list', '--porcelain'], repo)).stdout
+ .split('\n\n').find(block => block.startsWith(`worktree ${path}\n`))?.match(/^locked ?(.*)$/m)?.[1] ?? null;
+ /** The operator confirms a row the last sweep persisted. */
+ async function retire(release, opts = {}) {
+ await recordBranchReconcileOutcome('app-1', { status: 'incomplete', remaining: [{ ...release, reason: 'worktree-locked' }] });
+ return retireInventoriedCheckout({ appId: 'app-1', release }, { cosDir, readAgents: noOwners, ...opts });
+ }
+ const archives = async () => (existsSync(heldCheckoutArchiveRoot(cosDir)) ? readdir(heldCheckoutArchiveRoot(cosDir)) : []);
+
+ it('archives tracked, untracked, ignored and symlinked content, then retires a locked detached checkout', async () => {
+ const { path, release } = await heldCheckout('detached-held');
+
+ const result = await retire(release);
+
+ expect(result).toMatchObject({ ok: true, branchDeleted: false });
+ expect(existsSync(path)).toBe(false);
+ expect(await registered(release.path)).toBe(false);
+ const manifest = JSON.parse(await readFile(join(result.archiveDir, 'manifest.json'), 'utf8'));
+ expect(manifest.release).toEqual(release);
+ expect(manifest.captured.files.map(file => file.path).sort()).toEqual(['.gitignore', 'ignored.txt', 'untracked.txt']);
+ expect(manifest.captured.symlinks).toEqual(SYMLINKS ? [{ path: 'linked', target: '../shared-target' }] : []);
+ expect(await readFile(join(result.archiveDir, 'files', 'ignored.txt'), 'utf8')).toBe('ignored work\n');
+ expect(await readFile(join(result.archiveDir, 'worktree.diff'), 'utf8')).toContain('+tracked edit');
+ });
+
+ it('retires a merged branch checkout and its branch, and drops it from the persisted inventory', async () => {
+ const { path, release } = await heldCheckout('branch-held', { branch: 'feature/held' });
+ await recordBranchReconcileOutcome('app-1', {
+ status: 'incomplete', reason: 'holds-remaining', nextAction: 'Recover held checkouts.',
+ remaining: [{ ...release, managed: false, reason: 'worktree-locked' }, { branch: 'other', reason: 'actionable' }],
+ });
+
+ const result = await retireInventoriedCheckout({ appId: 'app-1', release }, { cosDir, readAgents: noOwners });
+
+ expect(result).toMatchObject({ ok: true, branchDeleted: true });
+ expect(existsSync(path)).toBe(false);
+ expect((await execGit(['branch', '--list', 'feature/held'], repo)).stdout.trim()).toBe('');
+ const outcome = await getBranchReconcileOutcome('app-1');
+ expect(outcome.status).toBe('incomplete');
+ expect(outcome.remaining).toEqual([{ branch: 'other', reason: 'actionable' }]);
+ expect(outcome.retired[0]).toMatchObject({ path: release.path, branch: 'feature/held', branchDeleted: true, archiveDir: result.archiveDir });
+ });
+
+ it('refuses a release that does not name a row of the last inventory', async () => {
+ const { path, release } = await heldCheckout('not-inventoried');
+ await recordBranchReconcileOutcome('app-1', { status: 'incomplete', remaining: [{ ...release, lockReason: 'older lock text' }] });
+
+ expect(await retireInventoriedCheckout({ appId: 'app-1', release }, { cosDir, readAgents: noOwners }))
+ .toEqual({ ok: false, reason: 'release-not-in-inventory' });
+ expect(existsSync(path)).toBe(true);
+ });
+
+ it.each([
+ ['a changed lock', async (path) => {
+ await execGit(['worktree', 'unlock', path], repo);
+ await execGit(['worktree', 'lock', '--reason', 'new owner took over', path], repo);
+ }, 'checkout-lock-changed'],
+ ['a moved HEAD', async (path) => {
+ await writeFile(join(path, 'next.txt'), 'more\n');
+ await execGit(['add', 'next.txt'], path);
+ await execGit(['commit', '-m', 'chore: synthetic owner commit'], path);
+ }, 'checkout-head-changed'],
+ ])('treats %s since the inventory as an ownership change', async (_label, change, reason) => {
+ const { path, release } = await heldCheckout('changed-owner');
+ await change(path);
+
+ expect(await retire(release)).toEqual({ ok: false, reason });
+ expect(existsSync(join(path, 'ignored.txt'))).toBe(true);
+ expect(await archives()).toEqual([]);
+ });
+
+ it('keeps the checkout, its content and its original lock when an owner appears after the archive', async () => {
+ const { path, release } = await heldCheckout('owner-arrives', { lockReason: 'handoff pending' });
+ let reads = 0;
+ // Clear for the pre-archive check; a live run occupies the checkout by the removal recheck.
+ const readAgents = async () => (++reads === 1 ? [] : [{ id: 'agent-live', status: 'running', workspacePath: release.path }]);
+
+ const result = await retire(release, { readAgents });
+
+ expect(result).toMatchObject({ ok: false, reason: 'claim-owner-active' });
+ expect(await registered(release.path)).toBe(true);
+ expect(await lockText(release.path)).toBe('handoff pending');
+ for (const name of ['initial.txt', 'untracked.txt', 'ignored.txt']) expect(existsSync(join(path, name))).toBe(true);
+ expect(existsSync(join(result.archiveDir, 'manifest.json'))).toBe(true);
+ });
+
+ it('keeps everything and leaves no partial archive when the archive cannot be completed', async () => {
+ const { path, release } = await heldCheckout('archive-fails');
+ // A nested repository is listed without its files, so it cannot be archived faithfully.
+ await mkdir(join(path, 'nested'));
+ await execGit(['init', '-q'], join(path, 'nested'));
+
+ const result = await retire(release);
+
+ expect(result).toMatchObject({ ok: false, reason: 'archive-failed' });
+ expect(await lockText(release.path)).toBe('synthetic external owner');
+ expect(existsSync(join(path, 'nested', '.git'))).toBe(true);
+ expect(await archives()).toEqual([]);
+ });
+
+ it('refuses unmerged work and a manual completion handoff before archiving anything', async () => {
+ const unmerged = await heldCheckout('unmerged');
+ await execGit(['worktree', 'unlock', unmerged.path], repo);
+ await execGit(['commit', '--allow-empty', '-m', 'feat: synthetic unmerged work'], unmerged.path);
+ const head = (await execGit(['rev-parse', 'HEAD'], unmerged.path)).stdout.trim();
+ expect(await retire({ ...unmerged.release, head, locked: false, lockReason: null }))
+ .toEqual({ ok: false, reason: 'not-merged-on-recheck' });
+
+ const handoff = await heldCheckout('handoff', { branch: 'feature/handoff' });
+ injected.policies = [{ id: 'agent-done', status: 'completed', startedAt: '2026-01-01T00:00:00.000Z',
+ metadata: { sourceWorkspace: repo, worktreeBranch: 'feature/handoff', prCompletionPolicy: 'leave-open' } }];
+ expect(await retire(handoff.release))
+ .toEqual({ ok: false, reason: 'pr-completion-human-handoff' });
+ expect(existsSync(handoff.path)).toBe(true);
+ expect(await archives()).toEqual([]);
+ });
+});
diff --git a/server/services/taskSchedule.js b/server/services/taskSchedule.js
index 5aafc4ece6..ddce1ecac6 100644
--- a/server/services/taskSchedule.js
+++ b/server/services/taskSchedule.js
@@ -753,6 +753,36 @@ export async function recordBranchReconcileOutcome(appId, { status, reason, rema
});
}
+export async function getBranchReconcileOutcome(appId) {
+ const schedule = await loadSchedule();
+ return resolveExecutionRecord(schedule, 'branch-reconcile', appId)?.branchReconcileOutcome ?? null;
+}
+
+const RETIRED_CHECKOUTS_KEPT = 20;
+
+/**
+ * Drop a retired checkout from the last inventory and keep a short record of
+ * where its archive went. Status is untouched: only the next sweep can say the
+ * repository converged.
+ */
+export async function recordHeldCheckoutRetirement(appId, { path, branch, branchDeleted, head, archiveDir }) {
+ return updateSchedule(async (schedule) => {
+ const record = ensureExecutionRecord(schedule, 'branch-reconcile', appId);
+ const outcome = record.branchReconcileOutcome || {};
+ const retiredAt = new Date().toISOString();
+ record.branchReconcileOutcome = {
+ ...outcome,
+ updatedAt: retiredAt,
+ remaining: Array.isArray(outcome.remaining)
+ ? outcome.remaining.filter(entry => entry.path !== path && !(branchDeleted && branch && entry.branch === branch))
+ : outcome.remaining ?? null,
+ retired: [{ path, ...(branch && { branch }), head, branchDeleted, archiveDir, retiredAt }, ...(outcome.retired || [])]
+ .slice(0, RETIRED_CHECKOUTS_KEPT),
+ };
+ return { result: record.branchReconcileOutcome, changed: true };
+ });
+}
+
/**
* A perpetual drain's convergence state, read in ONE pass: the actionable
* signature its last dispatch was handed, and how many times it has dispatched