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: publish recovery journal rows atomically

[._.]/ Adam Eivya997ab73af7d
diff --git a/docs/features/branch-reconciliation.md b/docs/features/branch-reconciliation.md
index 84bbb174a1..446a53de02 100644
--- a/docs/features/branch-reconciliation.md
+++ b/docs/features/branch-reconciliation.md
@@ -165,6 +165,10 @@ it records a durable pending intent before execution and then a response. A
pending-only record means inspect the transaction before any retry. The CLI
requires an existing self-install registry and trusted owner state, and refuses
an absent or uncertain reservation. It never initializes a different data tree.
+Journal rows are fully written and synced to private staging files before
+exclusive hardlink publication to their numbered names. Staging files remain
+as evidence, including partial writes; recovery reads only committed numbered
+rows. Existing malformed numbered rows are never silently ignored or replaced.
After an interrupted recovery, read status again and obtain a new review for
the new journal digest rather than replaying an old approval.
diff --git a/server/services/initializedCheckoutRecovery.js b/server/services/initializedCheckoutRecovery.js
index ba499b281d..b4be7e5366 100644
--- a/server/services/initializedCheckoutRecovery.js
+++ b/server/services/initializedCheckoutRecovery.js
@@ -5,7 +5,7 @@
*/
import { spawn } from '../lib/childProcess.js';
import { createHash, randomUUID } from 'node:crypto';
-import { lstat, mkdir, open, readFile, readdir } from 'node:fs/promises';
+import { link, lstat, mkdir, open, readFile, readdir } from 'node:fs/promises';
import { join } from 'node:path';
import { type as hostOsType } from 'node:os';
import { fileURLToPath } from 'node:url';
@@ -94,9 +94,15 @@ async function appendStep(directory, state, phase, patch = {}) {
await privateDirectory(directory);
const next = { ...state, ...patch, phase, sequence: (state.sequence ?? -1) + 1,
previous: state.sequence == null ? null : hash(state) };
- const file = await open(join(directory, `${String(next.sequence).padStart(6, '0')}.json`), 'wx', 0o600);
+ const name = `${String(next.sequence).padStart(6, '0')}.json`;
+ const staged = join(directory, `.${name}.${randomUUID()}.staging`);
+ const file = await open(staged, 'wx', 0o600);
try { await file.writeFile(`${JSON.stringify(next)}\n`); await file.sync(); }
finally { await file.close(); }
+ // A partial write must never occupy the next committed sequence. Hardlink
+ // publication is atomic and refuses an existing name on every supported
+ // test platform. Retain staging names, including interrupted rows, as evidence.
+ await link(staged, join(directory, name));
await syncDirectory(directory);
return next;
}
diff --git a/server/services/initializedCheckoutRecovery.test.js b/server/services/initializedCheckoutRecovery.test.js
index 8f9fbcbede..17cfe6c44f 100644
--- a/server/services/initializedCheckoutRecovery.test.js
+++ b/server/services/initializedCheckoutRecovery.test.js
@@ -20,7 +20,17 @@ vi.mock('./taskScheduleStore.js', () => ({
}));
vi.mock('node:fs/promises', async importOriginal => {
const actual = await importOriginal();
- return { ...actual, lstat: async path => {
+ return { ...actual, link: async (source, target) => {
+ if (fixture?.conflictNextJournal) {
+ fixture.conflictNextJournal = false;
+ await actual.writeFile(target, 'concurrent-evidence', { flag: 'wx', mode: 0o600 });
+ }
+ await actual.link(source, target);
+ if (fixture?.stopAfterJournalPublication) {
+ fixture.stopAfterJournalPublication = false;
+ throw new Error('journal-publication-interrupted');
+ }
+ }, lstat: async path => {
const info = await actual.lstat(path);
// Model POSIX permission bits even when this Darwin-capability fixture runs
// on Windows; the unsafe-mode branch below still exercises real refusal.
@@ -31,11 +41,17 @@ vi.mock('node:fs/promises', async importOriginal => {
return info;
}, open: async (path, ...args) => {
if (persisted.rejectDirectoryOpen && (await actual.lstat(path).catch(() => null))?.isDirectory()) throw new Error('directory-open-unsupported');
- if (fixture?.failNextJournal && /[\\/]\d{6}\.json$/.test(String(path))) {
+ const isJournalStage = /[\\/]\.\d{6}\.json\.[a-f0-9-]+\.staging$/.test(String(path));
+ if (fixture?.failNextJournal && isJournalStage) {
fixture.failNextJournal = false;
throw new Error('journal-write-interrupted');
}
const handle = await actual.open(path, ...args);
+ if (fixture?.partialNextJournal && isJournalStage) {
+ fixture.partialNextJournal = false;
+ const write = handle.writeFile.bind(handle);
+ handle.writeFile = async text => { await write(text.slice(0, 1)); throw new Error('partial-journal-write'); };
+ }
const originalSync = handle.sync.bind(handle);
handle.sync = async () => { persisted.fileSyncs++; return originalSync(); };
return handle;
@@ -261,6 +277,57 @@ describe('initialized checkout transaction', () => {
.toMatchObject({ ok: true, restored: true });
expect(fixture.cut).toBeNull();
});
+ it('preserves a partial staged journal without blocking fresh metadata recovery', async () => {
+ const input = await interruptedMetadata();
+ const prepared = await fixture.service.reviewMetadataRestore(input);
+ fixture.partialNextJournal = true;
+ expect(await fixture.service.restoreMetadata({ ...input, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'partial-journal-write' });
+ expect(fixture.cut).not.toBeNull();
+ const directory = join(root, input.transactionId);
+ const partial = (await readdir(directory)).filter(name => name.endsWith('.staging'));
+ const fragments = (await Promise.all(partial.map(async name => [name, await readFile(join(directory, name), 'utf8')])))
+ .filter(([, text]) => text === '{');
+ expect(fragments).toHaveLength(1);
+ const restarted = _createInitializedCheckoutRecovery(fixture.deps);
+ const status = await restarted.status(input);
+ expect(status.journalDigest).toBe(input.journalDigest);
+ const fresh = await restarted.reviewMetadataRestore(input);
+ expect(await restarted.restoreMetadata({ ...input, review: { digest: fresh.review.digest } }))
+ .toMatchObject({ ok: true, restored: true });
+ expect(await readFile(join(directory, fragments[0][0]), 'utf8')).toBe('{');
+ expect(fixture.cut).toBeNull();
+ });
+ it('never replaces a conflicting canonical journal during metadata recovery', async () => {
+ const input = await interruptedMetadata();
+ const prepared = await fixture.service.reviewMetadataRestore(input);
+ fixture.conflictNextJournal = true;
+ expect(await fixture.service.restoreMetadata({ ...input, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, recoveryRequired: true });
+ const directory = join(root, input.transactionId);
+ const names = (await readdir(directory)).filter(name => /^\d{6}\.json$/.test(name)).sort();
+ expect(await readFile(join(directory, names.at(-1)), 'utf8')).toBe('concurrent-evidence');
+ expect(fixture.placement.working).toBe('quarantined');
+ expect(fixture.cut).not.toBeNull();
+ });
+ it('resumes from a complete journal published just before interruption', async () => {
+ const input = await interruptedMetadata();
+ const prepared = await fixture.service.reviewMetadataRestore(input);
+ fixture.stopAfterJournalPublication = true;
+ expect(await fixture.service.restoreMetadata({ ...input, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'journal-publication-interrupted' });
+ const restarted = _createInitializedCheckoutRecovery(fixture.deps);
+ const status = await restarted.status(input);
+ expect(status.phase).toBe('metadata-restore-approved');
+ expect(fixture.cut).not.toBeNull();
+ expect(await restarted.restoreMetadata({ ...input, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'retirement-journal-changed' });
+ const freshInput = { ...input, journalDigest: status.journalDigest };
+ const fresh = await restarted.reviewMetadataRestore(freshInput);
+ expect(await restarted.restoreMetadata({ ...freshInput, review: { digest: fresh.review.digest } }))
+ .toMatchObject({ ok: true, restored: true });
+ expect(fixture.cut).toBeNull();
+ });
it('exposes only source-verified cancellation after durable preservation loses its proof journal', async () => {
fixture.failProofJournal = true;
const result = await fixture.service.retire(await reviewed());