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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
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.jsxindex 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.jsxindex 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.jsxnew file mode 100644index 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.jsindex 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 Jobsexport const getCosJobs = (options = {}) => request('/cos/jobs', options);diff --git a/docs/API.md b/docs/API.mdindex 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.mdindex 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 retirethem. A failed or empty Git checkout listing is unknown evidence and prevents acompleted 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.jsindex 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.jsindex 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.jsindex 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsindex 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