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

fix(cos): archive staged blobs and hash content before retiring a held checkout (#12002)

[._.]/ Adam Eivy707614a545f5
diff --git a/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.jsx b/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.jsx
index 07b92ff49d..b057e6079e 100644
--- a/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.jsx
+++ b/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.jsx
@@ -7,6 +7,8 @@ const STATUS_LABELS = { drained: 'No remaining work in last scan', incomplete: '
// 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');
+const checkoutKey = (appId, entry) => `${appId}\0${entry.path}\0${entry.head}`;
+const NONE = new Set();
// 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.
@@ -26,7 +28,7 @@ function RetireCheckout({ appId, entry, onRetired }) {
setState('idle');
return;
}
- onRetired(entry.path);
+ onRetired(checkoutKey(appId, entry));
};
if (state === 'idle') {
return (
@@ -55,14 +57,18 @@ function RetireCheckout({ appId, entry, onRetired }) {
// 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());
+ // Hides a retired row at once. Scoped to the outcomes it was retired from:
+ // the schedule event's fresh inventory is authoritative once it arrives.
+ const [retired, setRetired] = useState({ source: outcomes, keys: NONE });
+ const retiredKeys = retired.source === outcomes ? retired.keys : NONE;
if (!outcomes || !Object.keys(outcomes).length) return null;
- const markRetired = path => setRetiredPaths(current => new Set(current).add(path));
+ const markRetired = key => setRetired(current => ({
+ source: outcomes, keys: new Set(current.source === outcomes ? current.keys : NONE).add(key),
+ }));
return (
<div className="mx-4 mb-3 space-y-2 text-xs">
{Object.entries(outcomes).map(([appId, outcome]) => {
- const remaining = Array.isArray(outcome.remaining) ? outcome.remaining.filter(entry => !retiredPaths.has(entry.path)) : null;
+ const remaining = Array.isArray(outcome.remaining) ? outcome.remaining.filter(entry => !retiredKeys.has(checkoutKey(appId, entry))) : null;
return (
<details key={appId} className="rounded border border-port-border p-2">
<summary className="cursor-pointer text-gray-300">
diff --git a/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.test.jsx b/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.test.jsx
index 116469d634..aaba42e319 100644
--- a/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.test.jsx
+++ b/client/src/components/cos/tabs/schedule/BranchReconcileOutcome.test.jsx
@@ -13,17 +13,18 @@ const held = {
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' }]} />);
+ const view = 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…' }));
+ return view;
}
describe('BranchReconcileOutcome checkout retirement', () => {
beforeEach(() => { retire.mockReset(); });
- it('sends the exact inventory row as the scoped release and drops the row once retired', async () => {
+ it('sends the exact inventory row as the scoped release and hides the row until a fresh inventory arrives', async () => {
retire.mockResolvedValue({ ok: true, archiveDir: '/example/archive', branchDeleted: true });
- open();
+ const { rerender } = open();
expect(screen.getByText(/Release this exact checkout and its lock\?/)).toBeVisible();
fireEvent.click(screen.getByRole('button', { name: 'Yes, archive and retire' }));
@@ -33,6 +34,10 @@ describe('BranchReconcileOutcome checkout retirement', () => {
}, { silent: true });
expect(screen.getByText(/Example App · Incomplete · 1 remaining/)).toBeVisible();
expect(screen.queryByRole('button', { name: 'Archive and retire checkout…' })).toBeNull();
+
+ // A checkout recreated at the same path is new evidence, not the retired row.
+ rerender(<BranchReconcileOutcome outcomes={{ ...outcomes }} apps={[{ id: 'app-1', name: 'Example App' }]} />);
+ expect(screen.getByText('/example/held')).toBeVisible();
});
it('keeps the row and shows why the server kept the checkout', async () => {
diff --git a/docs/features/branch-reconciliation.md b/docs/features/branch-reconciliation.md
index bca9c4915f..e0ad5d781e 100644
--- a/docs/features/branch-reconciliation.md
+++ b/docs/features/branch-reconciliation.md
@@ -34,9 +34,9 @@ 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
+staged and unstaged diffs, verbatim copies of untracked and ignored files
+(hash-verified), and symlink targets. A nested repository, unmerged or hidden
+index entries, 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
diff --git a/server/services/heldCheckoutRecovery.js b/server/services/heldCheckoutRecovery.js
index 9bb85fcd67..fec5fd055c 100644
--- a/server/services/heldCheckoutRecovery.js
+++ b/server/services/heldCheckoutRecovery.js
@@ -11,9 +11,9 @@
*
* 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
+ * staged and unstaged diffs, 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 hashes 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.
*/
@@ -44,23 +44,39 @@ const shortBranch = (ref) => (ref ? String(ref).replace(/^refs\/heads\//, '') :
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.
+ * Everything the archive must preserve, read in one pass: the staged and
+ * unstaged diffs (separately, so a staged blob whose working copy is gone
+ * survives) and every untracked or ignored file by content hash, symlinks by
+ * target. Throws on anything that cannot be archived faithfully, before any
+ * copy is made. The fingerprint is compared again immediately 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()}`);
+async function snapshotContent(path) {
+ if ((await git(['ls-files', '-u', '-z'], path)).length) throw new Error('unmerged index entries cannot be archived');
+ // Assume-unchanged (lowercase tag) and skip-worktree (S) entries hide edits from diff.
+ const hidden = zLines(await git(['ls-files', '-v', '-z'], path)).find(line => /^[a-zS]/.test(line));
+ if (hidden) throw new Error(`${hidden.slice(2)} hides working-tree changes from Git`);
+ const indexDiff = await git(['diff', '--cached', '--binary'], path);
+ const worktreeDiff = await git(['diff', '--binary'], path);
+ const others = [];
+ let total = 0;
+ for (const rel of zLines(await git(['ls-files', '--others', '-z'], 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(path, rel);
+ const info = await lstat(source);
+ if (info.isSymbolicLink()) {
+ others.push({ path: rel, symlink: 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`);
+ others.push({ path: rel, bytes: info.size, sha256: await sha256File(source) });
}
- return hash.digest('hex');
+ const fingerprint = createHash('sha256').update(indexDiff).update('\0').update(worktreeDiff).update('\0')
+ .update(JSON.stringify(others)).digest('hex');
+ return { indexDiff, worktreeDiff, others, fingerprint };
}
/**
@@ -78,50 +94,37 @@ async function archiveCheckout(input) {
}
async function writeArchive(dir, { repoPath, tree, branch, defaultBranch, release }) {
- const fingerprint = await contentFingerprint(tree.path);
+ const snapshot = await snapshotContent(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);
+ if (commits) await writeFileGuarded(join(dir, 'commits.patch'), commits);
+ if (snapshot.indexDiff) await writeFileGuarded(join(dir, 'index.diff'), snapshot.indexDiff);
+ if (snapshot.worktreeDiff) await writeFileGuarded(join(dir, 'worktree.diff'), snapshot.worktreeDiff);
- 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);
+ const files = snapshot.others.filter(entry => entry.symlink === undefined);
+ const symlinks = snapshot.others.filter(entry => entry.symlink !== undefined).map(({ path, symlink }) => ({ path, target: symlink }));
+ for (const file of files) {
+ const destination = join(dir, 'files', file.path);
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 });
+ await copyFileGuarded(join(tree.path, file.path), destination);
+ if (await sha256File(destination) !== file.sha256) throw new Error(`archived copy of ${file.path} does not match`);
}
- if (await contentFingerprint(tree.path) !== fingerprint) throw new Error('checkout content changed while archiving');
+ if ((await snapshotContent(tree.path)).fingerprint !== snapshot.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 },
+ captured: { commitsPatch: Boolean(commits), indexDiff: Boolean(snapshot.indexDiff), worktreeDiff: Boolean(snapshot.worktreeDiff), files, symlinks },
restore: [
`git -C <repo> worktree add <checkout> ${tree.head}`,
- diff.trim() ? 'git -C <checkout> apply worktree.diff' : null,
+ snapshot.indexDiff ? 'git -C <checkout> apply --index index.diff' : null,
+ snapshot.worktreeDiff ? '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 };
+ return { dir, fingerprint: snapshot.fingerprint };
}
const isAncestor = (repoPath, sha, ref) => execGit(['merge-base', '--is-ancestor', sha, ref], repoPath, { ignoreExitCode: true })
@@ -204,7 +207,8 @@ async function retireHeldCheckout({ repoPath, release }, { cosDir = PATHS.cos, r
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 current = await snapshotContent(tree.path).catch(() => null);
+ return current?.fingerprint === archive.fingerprint ? null : 'checkout-content-changed';
};
const removal = await forceRemoveWorktreeDir(repoPath, tree.path, {
label: '🧹 held-checkout recovery: remove checkout', log: 'all', verifyRemoval,
diff --git a/server/services/heldCheckoutRecovery.test.js b/server/services/heldCheckoutRecovery.test.js
index c2ec041cb0..a1479e3875 100644
--- a/server/services/heldCheckoutRecovery.test.js
+++ b/server/services/heldCheckoutRecovery.test.js
@@ -80,8 +80,12 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
}
const archives = async () => (existsSync(heldCheckoutArchiveRoot(cosDir)) ? readdir(heldCheckoutArchiveRoot(cosDir)) : []);
- it('archives tracked, untracked, ignored and symlinked content, then retires a locked detached checkout', async () => {
+ it('archives staged, unstaged, untracked, ignored and symlinked content, then retires a locked detached checkout', async () => {
const { path, release } = await heldCheckout('detached-held');
+ // Only the index holds this file once its working copy is gone.
+ await writeFile(join(path, 'staged-only.txt'), 'staged work\n');
+ await execGit(['add', 'staged-only.txt'], path);
+ await rm(join(path, 'staged-only.txt'));
const result = await retire(release);
@@ -94,6 +98,7 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
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');
+ expect(await readFile(join(result.archiveDir, 'index.diff'), 'utf8')).toContain('+staged work');
});
it('retires a merged branch checkout and its branch, and drops it from the persisted inventory', async () => {
@@ -157,6 +162,20 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
expect(existsSync(join(result.archiveDir, 'manifest.json'))).toBe(true);
});
+ it('keeps the checkout when its content changes between the archive and removal', async () => {
+ const { path, release } = await heldCheckout('rewritten');
+ let reads = 0;
+ // Same length, so only a content hash can tell the archived copy is stale.
+ const readAgents = async () => {
+ if (++reads === 2) await writeFile(join(path, 'ignored.txt'), 'IGNORED WORK\n');
+ return [];
+ };
+
+ expect(await retire(release, { readAgents })).toMatchObject({ ok: false, reason: 'checkout-content-changed' });
+ expect(await readFile(join(path, 'ignored.txt'), 'utf8')).toBe('IGNORED WORK\n');
+ expect(await lockText(release.path)).toBe('synthetic external owner');
+ });
+
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.