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: cancel unmoved checkout preservation safely (#12717)

[._.]/5ac793ee4f45
diff --git a/scripts/lib/initialized_checkout_archive.py b/scripts/lib/initialized_checkout_archive.py
index 4a89e442b6..6354e367bc 100644
--- a/scripts/lib/initialized_checkout_archive.py
+++ b/scripts/lib/initialized_checkout_archive.py
@@ -681,6 +681,54 @@ def preserve(request):
'administrationFingerprint': before['administrationFingerprint'], 'restoreProof': proof}
+def verify_unmoved_preservation(request):
+ """Cancel an unbound copy while shared Git evolves; never move any data."""
+ root = transaction(request['transactionDir'])
+ if os.path.lexists(root / 'manifest.json'):
+ fail('preservation-already-bound')
+ quarantine = root / 'quarantine'
+ if os.path.lexists(quarantine) and (not safe_path(str(quarantine)).is_dir()
+ or any(quarantine.iterdir())):
+ fail('preservation-originals-may-have-moved')
+ path = root / 'source.json'
+ limit = 256 * 1024 ** 2
+ with os.fdopen(os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK), 'rb') as source:
+ info = os.fstat(source.fileno())
+ if not stat.S_ISREG(info.st_mode) or info.st_size > limit:
+ fail('invalid-preservation-source')
+ encoded = source.read(limit + 1)
+ if len(encoded) > limit:
+ fail('invalid-preservation-source')
+ before = json.loads(encoded)
+ compact = {k: v for k, v in before.items() if k != 'sources'}
+ expected = {k: v for k, v in request['expected'].items() if k != 'ok'}
+ if compact != expected:
+ fail('preservation-source-not-reviewed')
+ unsigned = {k: v for k, v in compact.items() if k != 'fingerprint'}
+ if digest({'facts': unsigned, 'sources': before['sources']}) != before['fingerprint']:
+ fail('preservation-source-proof-changed')
+ after = inspect(request, full=True)
+ def stable_facts(value):
+ facts = {k: v for k, v in value.items() if k not in ('sources', 'fingerprint')}
+ # Other checkouts publish shared refs. Their history is not being
+ # retired here. inspect still resolves this exact released branch/head;
+ # private refs are also covered byte-for-byte by administration below.
+ facts['parent'] = {k: v for k, v in facts['parent'].items() if k != 'refs'}
+ return facts
+ if stable_facts(before) != stable_facts(after):
+ fail('preservation-original-identity-or-git-changed')
+ for part in ('working', 'administration'):
+ if before['sources'][part] != after['sources'][part]:
+ fail('preservation-original-content-changed')
+ # No shared data is restored, removed, or certified as archived. Preserve
+ # both observation hashes so cancellation cannot masquerade as retirement.
+ return {'verified': True, 'originalsUnmoved': True, 'archiveVerified': False,
+ 'sharedBeforeSha256': digest(before['sources']['common']),
+ 'sharedAfterSha256': digest(after['sources']['common']),
+ 'sourceSha256': hashlib.sha256(encoded).hexdigest(),
+ 'reviewedFingerprint': before['fingerprint'], 'observedFingerprint': after['fingerprint']}
+
+
def load_transaction(request):
root = transaction(request['transactionDir'])
path = root / 'manifest.json'
@@ -1481,7 +1529,8 @@ def main():
elif action in ('preserve', 'verify', 'move', 'review-metadata-recovery',
'review-restored-finalization', 'verify-restored-finalization',
'review-quarantine-resumption', 'verify-quarantine-resumption', 'resume-quarantine',
- 'verify-completed-quarantine', 'verify-retired-quarantine', 'verify-deleted-branch'):
+ 'verify-completed-quarantine', 'verify-retired-quarantine', 'verify-deleted-branch',
+ 'verify-unmoved-preservation'):
fd = lock_file(transaction(request['transactionDir']), 'backend.lock')
try:
result = {'preserve': preserve, 'verify': verify, 'move': move,
@@ -1493,7 +1542,8 @@ def main():
'resume-quarantine': resume_quarantine,
'verify-completed-quarantine': verify_completed_quarantine,
'verify-retired-quarantine': verify_retired_quarantine,
- 'verify-deleted-branch': verify_deleted_branch}[action](request)
+ 'verify-deleted-branch': verify_deleted_branch,
+ 'verify-unmoved-preservation': verify_unmoved_preservation}[action](request)
finally:
os.close(fd)
else:
diff --git a/scripts/lib/initialized_checkout_archive_test.py b/scripts/lib/initialized_checkout_archive_test.py
index 413647c069..e77e424154 100644
--- a/scripts/lib/initialized_checkout_archive_test.py
+++ b/scripts/lib/initialized_checkout_archive_test.py
@@ -128,6 +128,50 @@ class NativeArchive(unittest.TestCase):
(admission / 'writer.lock').write_text('owned service bookkeeping')
self.assertEqual(archive.inspect(self.request), before)
+ def test_unbound_cancellation_accepts_shared_updates_without_touching_originals_or_evidence(self):
+ before = archive.inspect(self.request, full=True)
+ self.request['expected'] = {k: v for k, v in before.items() if k != 'sources'}
+ archive.private_json(self.txn / 'source.json', before)
+ (self.txn / 'quarantine').mkdir(mode=0o700)
+ (self.txn / 'partial-copy').write_bytes(b'incomplete evidence')
+ objects = Path(before['commonGitDir']) / 'objects'
+ info = objects.stat()
+ os.utime(objects, ns=(info.st_atime_ns, info.st_mtime_ns + 1000000000))
+ self.git(self.repo, 'update-ref', 'refs/heads/independent-work', 'HEAD')
+ observed = archive.inspect(self.request, full=True)
+ proof = archive.verify_unmoved_preservation(self.request)
+ self.assertTrue(proof['verified'])
+ self.assertTrue(proof['originalsUnmoved'])
+ self.assertFalse(proof['archiveVerified'])
+ self.assertNotEqual(proof['sharedBeforeSha256'], proof['sharedAfterSha256'])
+ self.assertEqual(archive.inspect(self.request, full=True), observed)
+ self.assertEqual((self.txn / 'partial-copy').read_bytes(), b'incomplete evidence')
+ self.assertFalse((self.txn / 'manifest.json').exists())
+ # Changes to original bytes or placement never borrow this exception.
+ for target, content, refusal in (
+ (self.work / 'new-data', b'new work', 'preservation-original-content-changed'),
+ (self.txn / 'quarantine' / 'working', b'move evidence', 'preservation-originals-may-have-moved'),
+ (self.txn / 'manifest.json', b'bound proof', 'preservation-already-bound'),
+ ):
+ with self.subTest(refusal=refusal):
+ parent_time = target.parent.stat()
+ target.write_bytes(content)
+ with self.assertRaisesRegex(RuntimeError, refusal):
+ archive.verify_unmoved_preservation(self.request)
+ target.unlink()
+ os.utime(target.parent, ns=(parent_time.st_atime_ns, parent_time.st_mtime_ns))
+ saved = (self.txn / 'source.json').read_bytes()
+ tampered = copy.deepcopy(before)
+ tampered['sources']['working'][0]['mode'] ^= 1
+ (self.txn / 'source.json').write_text(json.dumps(tampered))
+ with self.assertRaisesRegex(RuntimeError, 'preservation-source-proof-changed'):
+ archive.verify_unmoved_preservation(self.request)
+ (self.txn / 'source.json').write_bytes(saved)
+ self.assertTrue(archive.verify_unmoved_preservation(self.request)['verified'])
+ self.git(self.repo, 'update-ref', 'refs/heads/feature/fixture', 'HEAD^')
+ with self.assertRaisesRegex(RuntimeError, 'release-head-or-branch-changed'):
+ archive.verify_unmoved_preservation(self.request)
+
def test_common_runtime_sockets_are_outside_capture_but_private_and_captured_sockets_hold(self):
facts = archive.inspect(self.request)
common = Path(facts['commonGitDir'])
diff --git a/scripts/recover-initialized-checkout.js b/scripts/recover-initialized-checkout.js
index 50278bbbee..b8c9f022a6 100644
--- a/scripts/recover-initialized-checkout.js
+++ b/scripts/recover-initialized-checkout.js
@@ -7,7 +7,7 @@
* node scripts/recover-initialized-checkout.js <action> request.json \
* --install-root /absolute/install --output /absolute/new-private-record.jsonl
* Actions: review, restore, review-finalization, finalize,
- * review-quarantine, resume-quarantine.
+ * review-quarantine, resume-quarantine, cancel-preservation.
*
* Output is an exclusive 0600 JSONL journal: a durable pending intent precedes
* the service call; a completed response is appended. A lone pending line means
@@ -35,6 +35,7 @@ const ACTIONS = {
finalize: { method: 'finalizeRestored', acceptedReview: true },
'review-quarantine': { method: 'reviewQuarantineResumption', acceptedReview: false },
'resume-quarantine': { method: 'resumeQuarantine', acceptedReview: true, supersession: true },
+ 'cancel-preservation': { method: 'cancelPreservation', acceptedReview: false },
};
const fail = code => { throw Object.assign(new Error(code), { recoveryCode: code }); };
const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
diff --git a/scripts/recover-initialized-checkout.test.js b/scripts/recover-initialized-checkout.test.js
index de9ed9d6ca..a5c2fe6e73 100644
--- a/scripts/recover-initialized-checkout.test.js
+++ b/scripts/recover-initialized-checkout.test.js
@@ -27,13 +27,14 @@ async function fixture(action = 'review') {
}
describe('initialized checkout recovery CLI', () => {
- it.each(['review', 'restore', 'review-finalization', 'finalize', 'review-quarantine', 'resume-quarantine'])('pins the existing install, journals intent first, and invokes only guarded %s', async action => {
+ it.each(['review', 'restore', 'review-finalization', 'finalize', 'review-quarantine', 'resume-quarantine', 'cancel-preservation'])('pins the existing install, journals intent first, and invokes only guarded %s', async action => {
const f = await fixture(action);
const before = process.env.PORTOS_DATA_ROOT;
const stdout = vi.fn();
const method = { review: 'reviewMetadataRestore', restore: 'restoreMetadata',
'review-finalization': 'reviewRestoredFinalization', finalize: 'finalizeRestored',
- 'review-quarantine': 'reviewQuarantineResumption', 'resume-quarantine': 'resumeQuarantine' }[action];
+ 'review-quarantine': 'reviewQuarantineResumption', 'resume-quarantine': 'resumeQuarantine',
+ 'cancel-preservation': 'cancelPreservation' }[action];
const load = vi.fn(async (deps, root) => {
expect(root).toBe(f.root);
expect(process.env.PORTOS_DATA_ROOT).toBe(f.root);
diff --git a/server/services/initializedCheckoutRecovery.js b/server/services/initializedCheckoutRecovery.js
index 019169bc2c..29aeeded8a 100644
--- a/server/services/initializedCheckoutRecovery.js
+++ b/server/services/initializedCheckoutRecovery.js
@@ -496,19 +496,24 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
// Explicit recovery restores the exact original inodes. It does not erase
// archives or auto-finish an interrupted ref deletion on stale forge evidence.
- const restore = input => fenced(async () => {
+ const restore = (input, { cancelOnly = false } = {}) => fenced(async () => {
const directory = location(input.transactionId);
const executor = await native({ command: 'lock', transactionDir: directory }, { keepOpen: true });
const gate = await admission();
try {
let state = await readJournal(directory);
if (hash(state) !== input.journalDigest) fail('retirement-journal-changed');
+ if (cancelOnly && (state.proof?.manifestSha256 || !(['intent', 'reserved'].includes(state.phase)
+ || (state.phase === 'restored' && state.cancelledUnboundPreservation === true)))) fail('retirement-cancellation-phase-invalid');
const ctx = await context(input.appId);
if (state.appId !== input.appId || state.repoPath !== ctx.repoPath) fail('retirement-transaction-app-mismatch');
await ensureOwner(ctx, state.release, false);
// A completed quarantine released its cut. An interrupted one retains it.
+ let newReservation = false;
const reservation = await gate.readCheckoutReservation(ctx.repoPath, state.id).catch(async error => {
if (error.code !== 'ENOENT') throw error;
+ if (['intent', 'reserved', 'preserved'].includes(state.phase) && state.reservation) fail('retirement-reservation-missing');
+ newReservation = true;
return gate.reserveCheckoutRetirement(ctx.repoPath, state.id);
});
return await gate.withCheckoutReservation(reservation, async () => {
@@ -517,10 +522,26 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
// may cancel the cut after a fresh unchanged-source inspection.
if (['intent', 'reserved', 'preserved'].includes(state.phase)
|| (state.phase === 'restored' && state.cancelledUnboundPreservation === true)) {
+ if (state.phase !== 'restored' && !newReservation && state.reservation
+ && JSON.stringify(reservation) !== JSON.stringify(state.reservation)) fail('retirement-reservation-changed');
const snapshot = await native({ command: 'inspect', repoPath: ctx.repoPath, release: state.release });
- if (JSON.stringify(snapshot) !== JSON.stringify(state.review.snapshot)) fail('retirement-source-changed');
+ let cancellationProof;
+ if (JSON.stringify(snapshot) !== JSON.stringify(state.review.snapshot)) {
+ // A failed, unbound copy has never authorized a move. A concurrent
+ // fetch or another checkout can change shared Git data. Verify the
+ // untouched original checkout/private Git, retaining every copy; this
+ // cancels only the reservation and never approves an archive.
+ if (state.proof?.manifestSha256 || state.phase === 'preserved') fail('retirement-source-changed');
+ cancellationProof = await native({ command: 'verify-unmoved-preservation',
+ repoPath: ctx.repoPath, release: state.release, transactionDir: directory,
+ expected: state.review.snapshot });
+ if (cancellationProof.verified !== true || cancellationProof.originalsUnmoved !== true) fail('retirement-source-changed');
+ }
+ await ensureOwner(ctx, state.release, true);
+ executor.assertHeld();
state = await appendStep(directory, state, 'restored', { reservation,
- cancelledUnboundPreservation: !state.proof?.manifestSha256 });
+ cancelledUnboundPreservation: !state.proof?.manifestSha256,
+ ...(cancellationProof ? { cancellationProof } : {}) });
await gate.releaseCheckoutReservation(reservation);
return { ok: true, transactionId: state.id, restored: true, archivesRetained: true };
}
@@ -916,7 +937,8 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
};
const automatic = async (input, options) => recoverAutomatically(input, options)
.catch(error => ({ ok: false, reason: error.message, transactionId: input.transactionId, recoveryRequired: true }));
- return { discover, recoverAutomatically: automatic, review, retire, status, restore, verifyArchive, reviewBranch, retireBranch, reviewMetadataRestore, restoreMetadata,
+ return { discover, recoverAutomatically: automatic, review, retire, status, restore,
+ cancelPreservation: input => restore(input, { cancelOnly: true }), verifyArchive, reviewBranch, retireBranch, reviewMetadataRestore, restoreMetadata,
reviewRestoredFinalization, finalizeRestored, reviewQuarantineResumption, resumeQuarantine };
}
diff --git a/server/services/initializedCheckoutRecovery.test.js b/server/services/initializedCheckoutRecovery.test.js
index 4b65d90dd1..d17e244573 100644
--- a/server/services/initializedCheckoutRecovery.test.js
+++ b/server/services/initializedCheckoutRecovery.test.js
@@ -87,6 +87,12 @@ beforeEach(async () => {
const native = vi.fn(async input => {
if (input.command === 'lock') return { assertHeld: () => {}, release: async () => {} };
if (input.command === 'inspect') return { ...fixture.snapshot };
+ if (input.command === 'verify-unmoved-preservation') {
+ if (fixture.cancelRefusal) throw new Error(fixture.cancelRefusal);
+ if ((await readdir(input.transactionDir)).includes('manifest.json')) throw new Error('preservation-already-bound');
+ return { verified: true, originalsUnmoved: true, archiveVerified: false,
+ reviewedFingerprint: input.expected.fingerprint, observedFingerprint: fixture.snapshot.fingerprint };
+ }
if (input.command === 'preserve') {
if (fixture.failPreserve) throw new Error('archive-no-space');
await writeFile(join(input.transactionDir, 'manifest.json'), '{}', { mode: 0o600 });
@@ -238,6 +244,73 @@ describe('initialized checkout transaction', () => {
expect(await fixture.service.restore({ appId: 'app', transactionId: result.transactionId, journalDigest: status.journalDigest })).toMatchObject({ ok: true });
expect((await readdir(join(root, result.transactionId))).length).toBeGreaterThan(0);
});
+ it('releases an unmoved failed copy after shared Git drift and replays cancellation after restart', async () => {
+ fixture.failPreserve = true;
+ const result = await fixture.service.retire(await reviewed());
+ fixture.snapshot.fingerprint = '9'.repeat(64);
+ const input = { appId: 'app', transactionId: result.transactionId };
+ const status = await fixture.service.status(input);
+ fixture.deps.admission.releaseCheckoutReservation.mockRejectedValueOnce(new Error('release-interrupted'));
+ expect(await fixture.service.cancelPreservation({ ...input, journalDigest: status.journalDigest }))
+ .toMatchObject({ ok: false, reason: 'release-interrupted' });
+ expect(fixture.cut).not.toBeNull();
+ const rows = (await readdir(join(root, result.transactionId))).filter(name => /^\d{6}\.json$/.test(name)).sort();
+ const saved = JSON.parse(await readFile(join(root, result.transactionId, rows.at(-1)), 'utf8'));
+ expect(saved).toMatchObject({ phase: 'restored', cancelledUnboundPreservation: true,
+ cancellationProof: { verified: true, originalsUnmoved: true, archiveVerified: false } });
+ const restarted = _createInitializedCheckoutRecovery(fixture.deps);
+ const fresh = await restarted.status(input);
+ expect(await restarted.cancelPreservation({ ...input, journalDigest: fresh.journalDigest })).toMatchObject({ ok: true });
+ expect(fixture.cut).toBeNull();
+ });
+ it.each(['preservation-original-content-changed', 'preservation-originals-may-have-moved'])(
+ 'retains failed-copy reservation when native cancellation refuses %s', async reason => {
+ fixture.failPreserve = true;
+ const result = await fixture.service.retire(await reviewed());
+ fixture.snapshot.fingerprint = '9'.repeat(64);
+ fixture.cancelRefusal = reason;
+ const input = { appId: 'app', transactionId: result.transactionId };
+ const status = await fixture.service.status(input);
+ expect(await fixture.service.restore({ ...input, journalDigest: status.journalDigest }))
+ .toMatchObject({ ok: false, reason });
+ expect(fixture.cut).not.toBeNull();
+ expect((await fixture.service.status(input)).phase).toBe('reserved');
+ });
+ it('never releases a replaced reservation while cancelling a failed copy', async () => {
+ fixture.failPreserve = true;
+ const result = await fixture.service.retire(await reviewed());
+ fixture.cut = { ...fixture.cut, owner: { ...fixture.cut.owner, generation: 'other' } };
+ const input = { appId: 'app', transactionId: result.transactionId };
+ const status = await fixture.service.status(input);
+ expect(await fixture.service.restore({ ...input, journalDigest: status.journalDigest }))
+ .toMatchObject({ ok: false, reason: 'retirement-reservation-changed' });
+ expect(fixture.cut.owner.generation).toBe('other');
+ });
+ it('does not create an unbound replacement when an unfinished cancellation loses its recorded cut', async () => {
+ fixture.failPreserve = true;
+ const result = await fixture.service.retire(await reviewed());
+ fixture.cut = null;
+ const input = { appId: 'app', transactionId: result.transactionId };
+ const status = await fixture.service.status(input);
+ fixture.deps.admission.reserveCheckoutRetirement.mockClear();
+ expect(await fixture.service.restore({ ...input, journalDigest: status.journalDigest }))
+ .toMatchObject({ ok: false, reason: 'retirement-reservation-missing' });
+ expect(fixture.deps.admission.reserveCheckoutRetirement).not.toHaveBeenCalled();
+ expect(fixture.cut).toBeNull();
+ expect((await fixture.service.status(input)).journalDigest).toBe(status.journalDigest);
+ });
+ it('the recovery CLI cancellation cannot restore or release an already quarantined transaction', async () => {
+ const result = await fixture.service.retire(await reviewed());
+ const input = { appId: 'app', transactionId: result.transactionId };
+ const status = await fixture.service.status(input);
+ fixture.deps.native.mockClear();
+ fixture.deps.admission.reserveCheckoutRetirement.mockClear();
+ expect(await fixture.service.cancelPreservation({ ...input, journalDigest: status.journalDigest }))
+ .toMatchObject({ ok: false, reason: 'retirement-cancellation-phase-invalid' });
+ expect(fixture.deps.admission.reserveCheckoutRetirement).not.toHaveBeenCalled();
+ expect(fixture.deps.native.mock.calls.map(([call]) => call.command)).toEqual(['lock']);
+ expect(fixture.placement).toEqual({ working: 'quarantined', administration: 'quarantined' });
+ });
const interruptedMetadata = async () => {
fixture.failPart = 'administration';
const retired = await fixture.service.retire(await reviewed());
@@ -801,7 +874,7 @@ describe('initialized checkout transaction', () => {
await expect(restarted.verifyArchive(input)).rejects.toThrow('archive-manifest-proof-changed');
const oldSnapshot = fixture.snapshot;
fixture.snapshot = { ...oldSnapshot, fingerprint: 'f'.repeat(64) };
- expect(await restarted.restore(input)).toMatchObject({ ok: false, reason: 'retirement-source-changed' });
+ expect(await restarted.restore(input)).toMatchObject({ ok: false, reason: 'preservation-already-bound' });
expect(fixture.cut).not.toBeNull();
fixture.snapshot = oldSnapshot;
fixture.deps.admission.releaseCheckoutReservation.mockRejectedValueOnce(new Error('release-interrupted'));