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
fix: finalize restored checkouts with reviewed metadata evidence
[._.]/ Adam Eivy9c20f6a2e193
diff --git a/docs/features/branch-reconciliation.md b/docs/features/branch-reconciliation.mdindex 446a53de02..2d7196ef07 100644--- a/docs/features/branch-reconciliation.md+++ b/docs/features/branch-reconciliation.md@@ -172,6 +172,48 @@ rows. Existing malformed numbered rows are never silently ignored or replaced.After an interrupted recovery, read status again and obtain a new review forthe new journal digest rather than replaying an old approval.+### Finalizing originals that have already been restored++Metadata can change after the post-move proof succeeds. In an observed case,+directory modification times changed and some residual compression attributes+returned with exactly their archived original bytes. The writer was not+established. The restore's final verification correctly retained its reservation.++When both original directories are already back at their exact original inode+identities, a separate completion path can record this narrow delta without+moving or repairing anything:++1. `POST /review-restored-finalization` accepts the transaction identifiers and+ fresh journal digest. It binds the previous accepted restore review and its+ immutable post-move observations, verifies the archive, and captures a new+ immutable full source snapshot under the existing reservation and executor.+2. Independently review the new digest and complete evidence. Only directory+ modification-time changes and reappearance of original residual+ `com.apple.decmpfs` bytes are eligible. Reappeared attributes must match both+ their prior raw preimages and the verified archive; the file must remain+ uncompressed. Administration, file contents and modification times, paths,+ identities, permissions, ownership, ACLs, flags, and all other attributes+ remain exact. Unknown drift stays held.+3. `POST /finalize-restored` accepts that separately reviewed digest. It repeats+ the review, verifies the exact snapshot again, and rechecks the branch,+ ownership, policy and reservation before recording completion and releasing+ the exact reservation. It performs no directory moves, metadata writes,+ branch changes or cleanup. Original manifests, raw values, observations,+ archives and journal evidence remain retained.++The bootstrap CLI exposes the same separate operations:++```sh+node scripts/recover-initialized-checkout.js review-finalization /absolute/request.json \+ --install-root /absolute/PortOS --output /absolute/new-finalization-review.jsonl+node scripts/recover-initialized-checkout.js finalize /absolute/approved-request.json \+ --install-root /absolute/PortOS --output /absolute/new-finalization.jsonl+```++These operations do not relax normal retirement or restore-move checks, and+finalization does not authorize branch deletion. Any subsequent retirement+requires a fresh review and preservation proof for the current checkout.+Managed checkout creation/adoption/removal, claim binding, the full workspacepreparation through agent registration/spawn, and supported Git API writersshare admission under the canonical common Git directory. Synthetic read-onlydiff --git a/scripts/lib/initialized_checkout_archive.py b/scripts/lib/initialized_checkout_archive.pyindex 9c399e4cd7..742814cb1b 100644--- a/scripts/lib/initialized_checkout_archive.py+++ b/scripts/lib/initialized_checkout_archive.py@@ -923,7 +923,164 @@ def review_metadata_recovery(request):'changedPaths': len({(row['part'], row['path']) for row in changes})}+def load_bound_evidence(root, reference, prefix):+ if (not isinstance(reference, dict) or set(reference) != {'file', 'sha256', 'digest'}+ or not isinstance(reference['digest'], str)+ or not re.fullmatch(r'[0-9a-f]{64}', reference['digest'])+ or reference['file'] != prefix + reference['digest'] + '.json'):+ fail('restored-finalization-evidence-invalid')+ path = root / reference['file']+ 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_nlink != 1+ or stat.S_IMODE(info.st_mode) != 0o600 or info.st_uid != os.getuid()+ or info.st_size > 256 * 1024 ** 2):+ fail('restored-finalization-evidence-unsafe')+ encoded = source.read(256 * 1024 ** 2 + 1)+ evidence = json.loads(encoded)+ # All supported publishers use this canonical encoding. Exact equality also+ # rejects duplicate JSON keys rather than interpreting an ambiguous ledger.+ if (hashlib.sha256(encoded).hexdigest() != reference['sha256']+ or digest(evidence) != reference['digest']+ or encoded != (json.dumps(evidence, sort_keys=True) + '\n').encode('utf-8')):+ fail('restored-finalization-evidence-changed')+ return evidence+++def restored_finalization_context(root, saved, request):+ prior = load_metadata_recovery(root, saved, request)+ accepted = request['metadataRecovery']+ canonical_prior = load_bound_evidence(root, {+ 'file': accepted['evidenceFile'], 'sha256': accepted['evidenceSha256'],+ 'digest': accepted['digest']}, 'metadata-recovery-')+ if canonical_prior != prior:+ fail('restored-finalization-prior-review-changed')+ located, sources = original_sources(root, saved['facts'])+ if any(row['state'] != 'original' for row in located.values()):+ fail('restored-finalization-original-placement-required')+ if metadata_recovery_changes(root, saved, located, prior['sources']) != prior['changes']:+ fail('restored-finalization-prior-review-changed')+ references = request.get('postMoveObservations')+ if not isinstance(references, list) or len(references) != 2:+ fail('restored-finalization-postmove-proof-required')+ for part, reference in zip(('administration', 'working'), references):+ # An already-original administration restore is an authenticated no-op,+ # so the old move command legitimately produced no postmove artifact.+ if (reference is None and part == 'administration'+ and prior['initialPlacements'][part] == 'original'+ and sources[part] == saved['facts']['sources'][part]):+ continue+ observation = load_bound_evidence(root, reference, 'metadata-recovery-postmove-')+ positions = {+ label: {'original': 'matching' if state == 'original' else 'absent',+ 'quarantine': 'absent' if state == 'original' else 'matching', 'state': state}+ for label, state in {'administration': 'original',+ 'working': 'original' if part == 'working' else 'quarantine'}.items()}+ if observation != {'version': 1, 'manifestSha256': request['manifestSha256'],+ 'acceptedMetadataRecovery': accepted, 'part': part,+ 'placements': positions, 'sources': prior['sources']}:+ fail('restored-finalization-postmove-proof-changed')+ return prior, located, sources+++def restored_finalization_changes(root, saved, prior, sources):+ # This is a record-only acceptance after both moves, never a move policy.+ # Directory mtimes are evidence of an observed change, not a causal claim.+ baseline = saved['facts']['sources']+ if sources['administration'] != baseline['administration']:+ fail('restored-finalization-administration-changed')+ expected, actual = prior['sources']['working'], sources['working']+ if len(expected) != len(actual):+ fail('restored-finalization-source-layout-changed')+ preimages = {(row['part'], row['path'], row['attribute']): row for row in prior['changes']}+ changes, total = [], 0+ for original, before, after in zip(baseline['working'], expected, actual):+ excluded = {'xattrs', 'mtimeNs'} if before['kind'] == 'directory' else {'xattrs'}+ if {k: v for k, v in before.items() if k not in excluded} != {+ k: v for k, v in after.items() if k not in excluded}:+ fail('restored-finalization-source-content-or-identity-changed')+ if before['mtimeNs'] != after['mtimeNs']:+ changes.append({'part': 'working', 'path': before['path'], 'field': 'mtimeNs',+ 'before': before['mtimeNs'], 'after': after['mtimeNs']})+ for name in sorted(set(before['xattrs']) | set(after['xattrs'])):+ old, new = before['xattrs'].get(name), after['xattrs'].get(name)+ if old == new:+ continue+ preimage = preimages.get(('working', before['path'], name), {})+ if (name != 'com.apple.decmpfs' or old is not None or new is None+ or before['kind'] != 'file' or before['flags'] & 0x20+ or original['xattrs'].get(name) != new+ or preimage.get('beforeSha256') != new or preimage.get('afterSha256') is not None+ or 'beforeBase64' not in preimage):+ fail('restored-finalization-unsupported-attribute-change:' + name)+ archived = raw_xattrs(root / 'archive/working' / before['path']).get(name)+ current = raw_xattrs(Path(saved['facts']['release']['path']) / before['path']).get(name)+ if (archived is None or current != archived+ or hashlib.sha256(archived).hexdigest() != new+ or base64.b64encode(archived).decode('ascii') != preimage['beforeBase64']):+ fail('restored-finalization-preimage-missing-or-changed')+ total += len(archived) + len(current)+ if total > 16 * 1024 ** 2:+ fail('metadata-recovery-evidence-budget-exceeded')+ changes.append({'part': 'working', 'path': before['path'], 'attribute': name,+ 'beforeSha256': None, 'afterSha256': new,+ 'originalSha256': original['xattrs'][name],+ 'originalBase64': preimage['beforeBase64'],+ 'afterBase64': base64.b64encode(current).decode('ascii')})+ return changes+++def restored_finalization_snapshot(request):+ if not re.fullmatch(r'[0-9a-f]{64}', request.get('manifestSha256', '')):+ fail('restored-finalization-manifest-proof-required')+ root, saved = load_transaction(request)+ verify_saved_archive(root, saved)+ prior, located, sources = restored_finalization_context(root, saved, request)+ changes = restored_finalization_changes(root, saved, prior, sources)+ verify_live_common(root, saved, restoring=True)+ if original_sources(root, saved['facts']) != (located, sources):+ fail('restored-finalization-observation-changed')+ evidence = {'version': 1, 'manifestSha256': request['manifestSha256'],+ 'transactionIdentity': saved['transactionIdentity'],+ 'originalFingerprint': saved['facts']['fingerprint'],+ 'acceptedMetadataRecovery': request['metadataRecovery'],+ 'postMoveObservations': request['postMoveObservations'],+ 'placements': located, 'sources': sources, 'changes': changes}+ return root, evidence+++def review_restored_finalization(request):+ root, evidence = restored_finalization_snapshot(request)+ stored = immutable_recovery_evidence(root, 'restored-finalization-', evidence)+ return {'restoredFinalization': {'version': 1, 'evidenceFile': stored['file'],+ 'evidenceSha256': stored['sha256'], 'digest': stored['digest']},+ 'placements': {label: row['state'] for label, row in evidence['placements'].items()},+ 'changeCounts': {+ 'directoryMtimeChanged': sum(row.get('field') == 'mtimeNs' for row in evidence['changes']),+ 'residualCompressionReappeared': sum(row.get('attribute') == 'com.apple.decmpfs'+ for row in evidence['changes'])},+ 'changedPaths': len({(row['part'], row['path']) for row in evidence['changes']})}+++def verify_restored_finalization(request):+ accepted = request.get('restoredFinalization')+ if (not isinstance(accepted, dict)+ or set(accepted) != {'version', 'evidenceFile', 'evidenceSha256', 'digest'}+ or accepted['version'] != 1):+ fail('restored-finalization-proof-invalid')+ root, evidence = restored_finalization_snapshot(request)+ recorded = load_bound_evidence(root, {'file': accepted['evidenceFile'],+ 'sha256': accepted['evidenceSha256'],+ 'digest': accepted['digest']}, 'restored-finalization-')+ if recorded != evidence:+ fail('restored-finalization-review-changed')+ return {'verified': True, 'alreadyRestored': True, 'placements': evidence['placements'],+ 'fingerprint': evidence['originalFingerprint'], 'restoredFinalizationAccepted': True}++def verify(request):+ if 'restoredFinalization' in request:+ fail('restored-finalization-separate-command-required')root, saved = load_transaction(request)facts = saved['facts']recovering = 'metadataRecovery' in request@@ -1044,11 +1201,14 @@ def main():elif action == 'status':root, saved = load_transaction(request)result = {'placements': placements(root, saved['facts']), 'fingerprint': saved['facts']['fingerprint']}- elif action in ('preserve', 'verify', 'move', 'review-metadata-recovery'):+ elif action in ('preserve', 'verify', 'move', 'review-metadata-recovery',+ 'review-restored-finalization', 'verify-restored-finalization'):fd = lock_file(transaction(request['transactionDir']), 'backend.lock')try:result = {'preserve': preserve, 'verify': verify, 'move': move,- 'review-metadata-recovery': review_metadata_recovery}[action](request)+ 'review-metadata-recovery': review_metadata_recovery,+ 'review-restored-finalization': review_restored_finalization,+ 'verify-restored-finalization': verify_restored_finalization}[action](request)finally:os.close(fd)else:diff --git a/scripts/lib/initialized_checkout_archive_test.py b/scripts/lib/initialized_checkout_archive_test.pyindex 60bb3e870e..3bdc853a30 100644--- a/scripts/lib/initialized_checkout_archive_test.py+++ b/scripts/lib/initialized_checkout_archive_test.py@@ -615,6 +615,127 @@ class NativeArchive(unittest.TestCase):self.assertTrue(archive.verify({**accepted, 'mode': 'restore'})['metadataRecoveryAccepted'])self.assertEqual((self.txn / 'manifest.json').read_bytes(), before)+ def restored_finalization_fixture(self, move_administration=False):+ subprocess.run(['/usr/bin/xattr', '-w', 'com.apple.decmpfs', 'fixture-residual',+ str(self.work / 'base.txt')], check=True)+ self.preserve()+ for part in (('administration', 'working') if move_administration else ('working',)):+ archive.move({**self.request, 'part': part, 'direction': 'quarantine'})+ moved = self.txn / 'quarantine/working/base.txt'+ if 'com.apple.decmpfs' in archive.raw_xattrs(moved):+ subprocess.run(['/usr/bin/xattr', '-d', 'com.apple.decmpfs', str(moved)], check=True)+ review = archive.review_metadata_recovery(self.request)+ request = {**self.request, 'metadataRecovery': review['metadataRecovery']}+ observations = [archive.move({**request, 'part': part, 'direction': 'restore'}).get('postMoveObservation')+ for part in ('administration', 'working')]+ self.assertTrue(archive.verify({**request, 'mode': 'restore'})['verified'])+ # Actual disposable-file operations reproduce a delayed reappearance and+ # directory timestamp change after both original-inode moves succeeded.+ subprocess.run(['/usr/bin/xattr', '-w', 'com.apple.decmpfs', 'fixture-residual',+ str(self.work / 'base.txt')], check=True)+ directory = self.work / 'empty'+ info = directory.stat()+ os.utime(directory, ns=(info.st_atime_ns, info.st_mtime_ns + 1_000_000_000))+ return {**request, 'postMoveObservations': observations}++ def test_restored_finalization_records_delayed_metadata_without_moving_or_rewriting_originals(self):+ request = self.restored_finalization_fixture()+ baseline = (self.txn / 'manifest.json').read_bytes()+ before = archive.original_sources(self.txn, archive.load_transaction(request)[1]['facts'])+ with self.assertRaisesRegex(RuntimeError, 'metadata-recovery-review-changed'):+ archive.verify({**request, 'mode': 'restore'})+ result = subprocess.run([sys.executable, str(Path(archive.__file__))],+ input=json.dumps({**request, 'command': 'review-restored-finalization'}) + '\n',+ env=self.env, capture_output=True, text=True, check=True)+ reviewed = json.loads(result.stdout)+ self.assertEqual(reviewed['changeCounts'], {'directoryMtimeChanged': 1, 'residualCompressionReappeared': 1})+ accepted = {**request, 'restoredFinalization': reviewed['restoredFinalization']}+ evidence = json.loads((self.txn / reviewed['restoredFinalization']['evidenceFile']).read_text())+ returned = next(row for row in evidence['changes'] if row.get('attribute') == 'com.apple.decmpfs')+ self.assertEqual(archive.base64.b64decode(returned['originalBase64']), b'fixture-residual')+ self.assertEqual(returned['afterBase64'], returned['originalBase64'])+ with patch.object(archive, 'exclusive_rename', side_effect=AssertionError('no move allowed')):+ self.assertTrue(archive.verify_restored_finalization(accepted)['restoredFinalizationAccepted'])+ self.assertTrue(archive.verify_restored_finalization(accepted)['alreadyRestored'])+ for command in ({'command': 'verify', 'mode': 'restore'},+ {'command': 'move', 'direction': 'restore', 'part': 'working'}):+ result = subprocess.run([sys.executable, str(Path(archive.__file__))],+ input=json.dumps({**accepted, **command}) + '\n',+ env=self.env, capture_output=True, text=True)+ self.assertEqual(result.returncode, 1)+ self.assertEqual(json.loads(result.stdout)['reason'], 'restored-finalization-separate-command-required')+ self.assertEqual(archive.original_sources(self.txn, archive.load_transaction(request)[1]['facts']), before)+ self.assertEqual((self.txn / 'manifest.json').read_bytes(), baseline)+ self.assertTrue(archive.verify({**self.request, 'mode': 'standalone'})['standalone'])++ def test_restored_finalization_refuses_stale_snapshot_and_noneligible_changes(self):+ request = self.restored_finalization_fixture()+ review = archive.review_restored_finalization(request)+ accepted = {**request, 'restoredFinalization': review['restoredFinalization']}+ original_manifest = archive.manifest+ mutations = {+ 'content': lambda row: row.update(sha256='0' * 64),+ 'file mtime': lambda row: row.update(mtimeNs=row['mtimeNs'] + 1),+ 'flags': lambda row: row.update(flags=row['flags'] | 0x20),+ 'ownership': lambda row: row.update(uid=row['uid'] + 1),+ 'acl': lambda row: row.update(acl='changed'),+ 'identity': lambda row: row['filesystemIdentity'].update(ino=0),+ 'security attribute': lambda row: row['xattrs'].update({'com.apple.quarantine': '0' * 64}),+ 'wrong compression': lambda row: row['xattrs'].update({'com.apple.decmpfs': '0' * 64}),+ }+ for name, mutation in mutations.items():+ def observe(path, reject_links=False):+ rows = original_manifest(path, reject_links)+ if path == self.work:+ rows = copy.deepcopy(rows)+ mutation(next(row for row in rows if row['path'] == 'base.txt'))+ return rows+ with self.subTest(change=name), patch.object(archive, 'manifest', observe):+ with self.assertRaisesRegex(RuntimeError, 'restored-finalization-source-content-or-identity-changed|restored-finalization-unsupported-attribute-change'):+ archive.review_restored_finalization(request)+ directory = self.work / 'empty'+ info = directory.stat()+ os.utime(directory, ns=(info.st_atime_ns, info.st_mtime_ns + 1))+ with self.assertRaisesRegex(RuntimeError, 'restored-finalization-review-changed'):+ archive.verify_restored_finalization(accepted)+ refreshed = archive.review_restored_finalization(request)+ self.assertNotEqual(refreshed['restoredFinalization']['digest'], review['restoredFinalization']['digest'])+ self.assertTrue(archive.verify_restored_finalization(+ {**request, 'restoredFinalization': refreshed['restoredFinalization']})['verified'])++ def test_restored_finalization_requires_exact_prior_observations_and_raw_preimages(self):+ request = self.restored_finalization_fixture(move_administration=True)+ self.assertTrue(archive.review_restored_finalization(request)['restoredFinalization'])+ for references in ([], request['postMoveObservations'][::-1],+ [request['postMoveObservations'][0]] * 2,+ [None, request['postMoveObservations'][1]],+ [request['postMoveObservations'][0], None]):+ with self.subTest(references=references), self.assertRaisesRegex(RuntimeError, 'restored-finalization-postmove-proof|restored-finalization-evidence-invalid'):+ archive.review_restored_finalization({**request, 'postMoveObservations': references})+ reference = request['postMoveObservations'][0]+ path = self.txn / reference['file']+ encoded = path.read_bytes()+ path.write_bytes(encoded + b' ')+ with self.assertRaisesRegex(RuntimeError, 'restored-finalization-evidence-changed'):+ archive.review_restored_finalization(request)+ path.write_bytes(encoded)+ attributes = archive.raw_xattrs+ def invalid_raw(path):+ values = attributes(path)+ return {**values, 'com.apple.decmpfs': b'wrong'} if path == self.work / 'base.txt' else values+ # Keep the observed manifest hashes stable to isolate the separate raw+ # preimage check against a racing attribute read.+ manifest = archive.manifest(self.work)+ real_manifest = archive.manifest+ def stable_manifest(path, reject_links=False):+ return manifest if path == self.work else real_manifest(path, reject_links)+ with patch.object(archive, 'raw_xattrs', invalid_raw), patch.object(archive, 'manifest', stable_manifest):+ with self.assertRaisesRegex(RuntimeError, 'restored-finalization-preimage-missing-or-changed'):+ archive.review_restored_finalization(request)+ archive.exclusive_rename(self.work, self.txn / 'quarantine/working')+ with self.assertRaisesRegex(RuntimeError, 'restored-finalization-original-placement-required'):+ archive.review_restored_finalization(request)+def test_fresh_process_refuses_foreign_rollback_target(self):self.preserve()archive.move({**self.request, 'part': 'working', 'direction': 'quarantine'})diff --git a/scripts/recover-initialized-checkout.js b/scripts/recover-initialized-checkout.jsindex 0375040d96..5c6813f75e 100644--- a/scripts/recover-initialized-checkout.js+++ b/scripts/recover-initialized-checkout.js@@ -4,7 +4,7 @@* Run reviewed code from an independent checkout when its install's durable* retirement cut prevents the normal update. Never edits the install's code.*- * node scripts/recover-initialized-checkout.js review|restore request.json \+ * node scripts/recover-initialized-checkout.js review|restore|review-finalization|finalize request.json \* --install-root /absolute/install --output /absolute/new-private-record.jsonl** Output is an exclusive 0600 JSONL journal: a durable pending intent precedes@@ -23,13 +23,19 @@ const MAX_REQUEST_BYTES = 16 * 1024;const MAX_RESPONSE_BYTES = 1024 * 1024;const HASH = /^[a-f0-9]{64}$/;const ID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;+const ACTIONS = {+ review: { method: 'reviewMetadataRestore', acceptedReview: false },+ restore: { method: 'restoreMetadata', acceptedReview: true },+ 'review-finalization': { method: 'reviewRestoredFinalization', acceptedReview: false },+ finalize: { method: 'finalizeRestored', acceptedReview: true },+};const fail = code => { throw Object.assign(new Error(code), { recoveryCode: code }); };const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);const exactKeys = (value, keys) => object(value) && Object.keys(value).sort().join(',') === [...keys].sort().join(',');export function parseRecoveryArgs(argv) {const [action, requestPath, ...options] = argv;- if (!['review', 'restore'].includes(action) || !requestPath || requestPath.startsWith('--')) fail('recovery-usage');+ if (!Object.hasOwn(ACTIONS, action) || !requestPath || requestPath.startsWith('--')) fail('recovery-usage');const parsed = { action, requestPath };for (let i = 0; i < options.length; i += 2) {const key = { '--install-root': 'installRoot', '--output': 'outputPath' }[options[i]];@@ -58,11 +64,12 @@ async function readJson(path, limit) {}function validateRequest(action, request) {- const keys = ['appId', 'transactionId', 'journalDigest', ...(action === 'restore' ? ['review'] : [])];+ const acceptedReview = ACTIONS[action].acceptedReview;+ const keys = ['appId', 'transactionId', 'journalDigest', ...(acceptedReview ? ['review'] : [])];if (!exactKeys(request, keys) || typeof request.appId !== 'string' || !/^[a-zA-Z0-9_-]{1,128}$/.test(request.appId)|| typeof request.transactionId !== 'string' || !ID.test(request.transactionId)|| typeof request.journalDigest !== 'string' || !HASH.test(request.journalDigest)- || (action === 'restore' && (!exactKeys(request.review, ['digest'])+ || (acceptedReview && (!exactKeys(request.review, ['digest'])|| typeof request.review.digest !== 'string' || !HASH.test(request.review.digest)))) fail('recovery-request-invalid');return request;}@@ -121,7 +128,7 @@ export async function runRecovery(argv, { load = loadRecovery, stdout = value =>}process.env.PORTOS_DATA_ROOT = options.installRoot;const service = await load(deps, options.installRoot);- const response = await service[options.action === 'review' ? 'reviewMetadataRestore' : 'restoreMetadata'](request);+ const response = await service[ACTIONS[options.action].method](request);const completion = { completedAt: new Date().toISOString(), outcome: 'response-recorded', response };const serialized = JSON.stringify(completion);if (Buffer.byteLength(serialized) > MAX_RESPONSE_BYTES) fail('recovery-response-exceeds-budget');diff --git a/scripts/recover-initialized-checkout.test.js b/scripts/recover-initialized-checkout.test.jsindex 7d69597378..f2e71d6403 100644--- a/scripts/recover-initialized-checkout.test.js+++ b/scripts/recover-initialized-checkout.test.js@@ -18,7 +18,7 @@ async function fixture(action = 'review') {const apps = { apps: { 'portos-default': { repoPath: root } } };await writeFile(join(root, 'data/apps.json'), JSON.stringify(apps));await writeFile(join(root, 'data/cos/state.json'), JSON.stringify({ agents: {} }));- const body = { ...request, ...(action === 'restore' ? { review: { digest: 'b'.repeat(64) } } : {}) };+ const body = { ...request, ...(['restore', 'finalize'].includes(action) ? { review: { digest: 'b'.repeat(64) } } : {}) };const input = join(root, 'request.json');const output = join(root, 'result.jsonl');await writeFile(input, JSON.stringify(body));@@ -26,11 +26,12 @@ async function fixture(action = 'review') {}describe('initialized checkout recovery CLI', () => {- it.each(['review', 'restore'])('pins the existing install, journals intent first, and invokes only guarded %s', async action => {+ it.each(['review', 'restore', 'review-finalization', 'finalize'])('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 = action === 'review' ? 'reviewMetadataRestore' : 'restoreMetadata';+ const method = { review: 'reviewMetadataRestore', restore: 'restoreMetadata',+ 'review-finalization': 'reviewRestoredFinalization', finalize: 'finalizeRestored' }[action];const load = vi.fn(async (deps, root) => {expect(root).toBe(f.root);expect(process.env.PORTOS_DATA_ROOT).toBe(f.root);@@ -54,6 +55,15 @@ describe('initialized checkout recovery CLI', () => {expect(JSON.parse(stdout.mock.calls[0][0]).reviewDigest).toBe('c'.repeat(64));});+ it('requires a separate exact review for finalization and never falls back to restore', async () => {+ const f = await fixture('finalize');+ await writeFile(f.input, JSON.stringify(request));+ const load = vi.fn();+ expect(await runRecovery(f.args, { load, stdout: () => {} })).toBe(1);+ expect(load).not.toHaveBeenCalled();+ await expect(stat(f.output)).rejects.toMatchObject({ code: 'ENOENT' });+ });+it.each(['missing-install', 'missing-agents', 'invalid-state', 'wrong-app-root', 'conflicting-app-id', 'inherited-app-id', 'invalid-json', 'extra-request-key', 'missing-review', 'unknown-option', 'existing-output'])('refuses %s before invoking recovery', async change => {const f = await fixture('restore');diff --git a/server/lib/hostControlRoutes.js b/server/lib/hostControlRoutes.jsindex 6edcbb2cdc..641114cc72 100644--- a/server/lib/hostControlRoutes.js+++ b/server/lib/hostControlRoutes.js@@ -422,6 +422,8 @@ export const HOST_CONTROL_ROUTES = Object.freeze(['POST /api/cos/schedule/branch-reconcile/initialized-checkouts/restore','POST /api/cos/schedule/branch-reconcile/initialized-checkouts/review-metadata-restore','POST /api/cos/schedule/branch-reconcile/initialized-checkouts/restore-metadata',+ 'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/review-restored-finalization',+ 'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/finalize-restored','POST /api/cos/schedule/branch-reconcile/initialized-checkouts/verify-archive','POST /api/cos/schedule/branch-reconcile/initialized-checkouts/review-branch','POST /api/cos/schedule/branch-reconcile/initialized-checkouts/retire-branch',diff --git a/server/lib/validation.js b/server/lib/validation.jsindex 8c05f98cde..68d4614666 100644--- a/server/lib/validation.js+++ b/server/lib/validation.js@@ -2885,6 +2885,7 @@ export const initializedCheckoutBranchRetireSchema = initializedCheckoutRestoreSexport const initializedCheckoutMetadataRestoreSchema = initializedCheckoutRestoreSchema.extend({review: z.object({ digest: z.string().regex(/^[a-f0-9]{64}$/) }).strict(),}).strict();+export const initializedCheckoutFinalizationSchema = initializedCheckoutMetadataRestoreSchema;// 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 2e3991ac62..c170107d3d 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, heldCheckoutRetireBodySchema, heldCheckoutReviewBodySchema, initializedCheckoutRetireBodySchema, initializedCheckoutTransactionSchema, initializedCheckoutRestoreSchema, initializedCheckoutBranchRetireSchema, initializedCheckoutMetadataRestoreSchema } from '../lib/validation.js';+import { sanitizeTaskMetadata, taskDataInputsSchema, validateRequest, parsePagination, cosScheduleTargetBodySchema, heldCheckoutRetireBodySchema, heldCheckoutReviewBodySchema, initializedCheckoutRetireBodySchema, initializedCheckoutTransactionSchema, initializedCheckoutRestoreSchema, initializedCheckoutBranchRetireSchema, initializedCheckoutMetadataRestoreSchema, initializedCheckoutFinalizationSchema } 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';@@ -356,6 +356,20 @@ router.post('/schedule/branch-reconcile/initialized-checkouts/restore-metadata',res.status(result.ok ? 200 : 409).json(result);}));+router.post('/schedule/branch-reconcile/initialized-checkouts/review-restored-finalization', asyncHandler(async (req, res) => {+ const input = validateRequest(initializedCheckoutRestoreSchema, req.body);+ const { reviewInitializedCheckoutRestoredFinalization } = await import('../services/initializedCheckoutRecovery.js');+ const result = await reviewInitializedCheckoutRestoredFinalization(input);+ res.status(result.ok ? 200 : 409).json(result);+}));++router.post('/schedule/branch-reconcile/initialized-checkouts/finalize-restored', asyncHandler(async (req, res) => {+ const input = validateRequest(initializedCheckoutFinalizationSchema, req.body);+ const { finalizeInitializedCheckoutRestored } = await import('../services/initializedCheckoutRecovery.js');+ const result = await finalizeInitializedCheckoutRestored(input);+ res.status(result.ok ? 200 : 409).json(result);+}));+router.post('/schedule/branch-reconcile/initialized-checkouts/verify-archive', asyncHandler(async (req, res) => {const input = validateRequest(initializedCheckoutRestoreSchema, req.body);const { verifyInitializedCheckoutArchive } = await import('../services/initializedCheckoutRecovery.js');diff --git a/server/routes/cosScheduleRoutes.test.js b/server/routes/cosScheduleRoutes.test.jsindex b4a02120b1..df9102ab99 100644--- a/server/routes/cosScheduleRoutes.test.js+++ b/server/routes/cosScheduleRoutes.test.js@@ -10,7 +10,7 @@ vi.mock('../services/maintenanceRun.js', () => maintenance);const recovery = vi.hoisted(() => ({ prepareInventoriedCheckoutRetirement: vi.fn(), retireInventoriedCheckout: vi.fn() }));vi.mock('../services/heldCheckoutRecovery.js', () => recovery);-const initialized = vi.hoisted(() => ({ reviewInitializedCheckout: vi.fn(), retireInitializedCheckout: vi.fn(), initializedCheckoutStatus: vi.fn(), restoreInitializedCheckout: vi.fn(), verifyInitializedCheckoutArchive: vi.fn(), reviewInitializedCheckoutBranch: vi.fn(), retireInitializedCheckoutBranch: vi.fn(), reviewInitializedCheckoutMetadataRestore: vi.fn(), restoreInitializedCheckoutMetadata: vi.fn() }));+const initialized = vi.hoisted(() => ({ reviewInitializedCheckout: vi.fn(), retireInitializedCheckout: vi.fn(), initializedCheckoutStatus: vi.fn(), restoreInitializedCheckout: vi.fn(), verifyInitializedCheckoutArchive: vi.fn(), reviewInitializedCheckoutBranch: vi.fn(), retireInitializedCheckoutBranch: vi.fn(), reviewInitializedCheckoutMetadataRestore: vi.fn(), restoreInitializedCheckoutMetadata: vi.fn(), reviewInitializedCheckoutRestoredFinalization: vi.fn(), finalizeInitializedCheckoutRestored: vi.fn() }));vi.mock('../services/initializedCheckoutRecovery.js', () => initialized);vi.mock('../services/taskSchedule.js', () => ({@@ -109,6 +109,22 @@ describe('CoS Schedule Routes', () => {expect(initialized.restoreInitializedCheckoutMetadata).toHaveBeenCalledWith(approved);});+ it('requires a distinct finalization digest and never accepts caller-supplied metadata allowances', async () => {+ const base = '/api/cos/schedule/branch-reconcile/initialized-checkouts';+ const input = { appId: 'app', transactionId: '2f800be9-682c-4726-813d-8d9ea0b2c1dc', journalDigest: 'a'.repeat(64) };+ initialized.reviewInitializedCheckoutRestoredFinalization.mockResolvedValue({ ok: true, review: { digest: 'b'.repeat(64) } });+ expect((await request(app).post(`${base}/review-restored-finalization`).send(input)).status).toBe(200);+ expect(initialized.reviewInitializedCheckoutRestoredFinalization).toHaveBeenCalledWith(input);+ expect((await request(app).post(`${base}/finalize-restored`).send(input)).status).toBe(400);+ const approved = { ...input, review: { digest: 'b'.repeat(64) } };+ expect((await request(app).post(`${base}/finalize-restored`).send({ ...approved, ignoreMtime: true })).status).toBe(400);+ expect((await request(app).post(`${base}/finalize-restored`).send({ ...approved, review: { ...approved.review, acceptChanges: true } })).status).toBe(400);+ expect(initialized.finalizeInitializedCheckoutRestored).not.toHaveBeenCalled();+ initialized.finalizeInitializedCheckoutRestored.mockResolvedValue({ ok: false, reason: 'restored-finalization-review-changed' });+ expect((await request(app).post(`${base}/finalize-restored`).send(approved)).status).toBe(409);+ expect(initialized.finalizeInitializedCheckoutRestored).toHaveBeenCalledWith(approved);+ });+describe('GET /api/cos/schedule', () => {it('surfaces unavailable schedule inputs as errors and recovers on the next read', async () => {taskSchedule.getScheduleStatusdiff --git a/server/services/initializedCheckoutRecovery.js b/server/services/initializedCheckoutRecovery.jsindex b4be7e5366..313b95ac0f 100644--- a/server/services/initializedCheckoutRecovery.js+++ b/server/services/initializedCheckoutRecovery.js@@ -363,6 +363,10 @@ export function _createInitializedCheckoutRecovery(deps = {}) {...(state.metadataRestoreReview ? { metadataRecovery: state.metadataRestoreReview.metadataRecovery,metadataChangeCounts: state.metadataRestoreReview.changeCounts,metadataRestored: state.phase === 'restored-with-metadata-transitions' } : {}),+ ...(state.restoredFinalizationReview ? {+ restoredFinalization: state.restoredFinalizationReview.restoredFinalization,+ restoredFinalizationComplete: state.phase === 'restored-with-reviewed-finalization',+ } : {}),...(['branch-retired', 'retired'].includes(state.phase) ? { recoveryAction: 'retire-branch' } : {}) };};@@ -480,7 +484,7 @@ export function _createInitializedCheckoutRecovery(deps = {}) {if (current.digest !== input.review?.digest) fail('metadata-recovery-review-changed');const { directory } = bound;let state = await appendStep(directory, bound.state, 'metadata-restore-approved',- { metadataRestoreReview: current, reservation });+ { metadataRestoreReview: current, metadataRestoreObservations: [], reservation });const proof = { transactionDir: directory, manifestSha256: state.proof.manifestSha256,metadataRecovery: current.metadataRecovery };for (const part of ['administration', 'working']) {@@ -502,7 +506,88 @@ export function _createInitializedCheckoutRecovery(deps = {}) {return { ok: true, transactionId: state.id, phase: state.phase, restored: true, archivesRetained: true,metadataTransitionsPreserved: true, metadataRecovery: current.metadataRecovery, archiveDir: directory };});- return { review, retire, status, restore, verifyArchive, reviewBranch, retireBranch, reviewMetadataRestore, restoreMetadata };+ const restoredFinalizationInputs = ({ directory, state, ctx }) => {+ const prior = state.metadataRestoreReview;+ const observations = state.metadataRestoreObservations;+ const unsigned = { ...prior };+ delete unsigned.digest;+ if (!state.proof?.manifestSha256 || state.branchDeleted || !prior+ || prior.mode !== 'restore-metadata-only' || prior.digest !== hash(unsigned)+ || prior.transactionId !== state.id || prior.repoPath !== ctx.repoPath || !sameRelease(prior.release, state.release)+ || !Array.isArray(observations) || observations.length !== 2+ || observations.some((row, index) => row?.part !== ['administration', 'working'][index]+ || (row.proof == null ? index !== 0 || prior.initialPlacements?.administration !== 'original'+ : !/^[a-f0-9]{64}$/.test(row.proof.sha256 || '')+ || !/^[a-f0-9]{64}$/.test(row.proof.digest || '')))) fail('restored-finalization-evidence-missing');+ return { transactionDir: directory, manifestSha256: state.proof.manifestSha256,+ metadataRecovery: prior.metadataRecovery, postMoveObservations: observations.map(row => row.proof ?? null) };+ };+ // A separate endpoint can acknowledge a narrowly reviewed post-restoration+ // transition. It never passes that permission to a move or ordinary verifier.+ const finalizationReview = async (bound, reservation) => {+ const { state, ctx } = bound;+ if (!['metadata-restored-working', 'restored-finalization-approved'].includes(state.phase)) fail('restored-finalization-phase-not-ready');+ const input = restoredFinalizationInputs(bound);+ const policy = await metadataRestoreSafety(bound);+ const proof = await native({ command: 'review-restored-finalization', ...input });+ if (proof.placements?.working !== 'original' || proof.placements?.administration !== 'original') fail('restored-finalization-originals-not-restored');+ const evidence = { version: 1, mode: 'finalize-already-restored', transactionId: state.id,+ repoPath: ctx.repoPath, release: state.release, journalDigest: hash(state), phase: state.phase, policy,+ reservation, priorMetadataRestoreReview: state.metadataRestoreReview,+ postMoveObservations: state.metadataRestoreObservations, restoredFinalization: proof.restoredFinalization,+ placements: proof.placements, changeCounts: proof.changeCounts, changedPaths: proof.changedPaths };+ return { digest: hash(evidence), ...evidence };+ };+ const withRestoredFinalization = (input, work, allowReleased = false) => fenced(async () => {+ const directory = location(input.transactionId);+ const executor = await native({ command: 'lock', transactionDir: directory }, { keepOpen: true });+ try {+ const bound = await loadBoundTransaction(input);+ const gate = await admission();+ const reservation = await gate.readCheckoutReservation(bound.ctx.repoPath, bound.state.id).catch(error => {+ if (error.code === 'ENOENT' && allowReleased && bound.state.phase === 'restored-with-reviewed-finalization') return null;+ throw error;+ });+ if (reservation && JSON.stringify(reservation) !== JSON.stringify(bound.state.reservation)) fail('restored-finalization-reservation-changed');+ const run = async () => {+ executor.assertHeld();+ if (hash(await readJournal(directory)) !== hash(bound.state)) fail('retirement-journal-changed');+ return work(bound, { executor, gate, reservation });+ };+ return reservation ? await gate.withCheckoutReservation(reservation, run)+ : await gate.withCheckoutPublication(bound.ctx.repoPath, run);+ } finally { await executor.release(); }+ }).catch(error => ({ ok: false, reason: error.message, transactionId: input.transactionId, recoveryRequired: true }));+ const reviewRestoredFinalization = input => withRestoredFinalization(input,+ async (bound, { reservation }) => ({ ok: true, review: await finalizationReview(bound, reservation) }));+ const finalizeRestored = input => withRestoredFinalization(input, async (bound, { executor, gate, reservation }) => {+ const { directory } = bound;+ let state = bound.state;+ const replay = state.phase === 'restored-with-reviewed-finalization';+ const current = replay ? state.restoredFinalizationReview : await finalizationReview(bound, reservation);+ const unsigned = { ...current };+ delete unsigned.digest;+ if (!current || current.mode !== 'finalize-already-restored' || current.digest !== hash(unsigned)+ || current.digest !== input.review?.digest) fail('restored-finalization-review-changed');+ if (!replay) state = await appendStep(directory, state, 'restored-finalization-approved', { restoredFinalizationReview: current });+ const policy = await metadataRestoreSafety({ ...bound, state });+ if (JSON.stringify(policy) !== JSON.stringify(current.policy)) fail('retirement-evidence-changed');+ executor.assertHeld();+ const proof = await native({ command: 'verify-restored-finalization', ...restoredFinalizationInputs({ ...bound, state }),+ restoredFinalization: current.restoredFinalization });+ if (proof.verified !== true || proof.alreadyRestored !== true || proof.restoredFinalizationAccepted !== true+ || ['working', 'administration'].some(part => proof.placements?.[part]?.state !== 'original')) fail('restored-finalization-proof-refused');+ const finalPolicy = await metadataRestoreSafety({ ...bound, state });+ if (JSON.stringify(finalPolicy) !== JSON.stringify(current.policy)) fail('retirement-evidence-changed');+ executor.assertHeld();+ if (!replay) state = await appendStep(directory, state, 'restored-with-reviewed-finalization');+ if (reservation) await gate.releaseCheckoutReservation(reservation);+ return { ok: true, transactionId: state.id, phase: state.phase, restored: true, alreadyRestored: true,+ archivesRetained: true, metadataTransitionsPreserved: true, restoredFinalization: current.restoredFinalization,+ archiveDir: directory };+ }, true);+ return { review, retire, status, restore, verifyArchive, reviewBranch, retireBranch, reviewMetadataRestore, restoreMetadata,+ reviewRestoredFinalization, finalizeRestored };}const recovery = _createInitializedCheckoutRecovery();@@ -517,3 +602,5 @@ export const reviewInitializedCheckoutBranch = recovery.reviewBranch;export const retireInitializedCheckoutBranch = recovery.retireBranch;export const reviewInitializedCheckoutMetadataRestore = recovery.reviewMetadataRestore;export const restoreInitializedCheckoutMetadata = recovery.restoreMetadata;+export const reviewInitializedCheckoutRestoredFinalization = recovery.reviewRestoredFinalization;+export const finalizeInitializedCheckoutRestored = recovery.finalizeRestored;diff --git a/server/services/initializedCheckoutRecovery.test.js b/server/services/initializedCheckoutRecovery.test.jsindex 17cfe6c44f..bcb2464940 100644--- a/server/services/initializedCheckoutRecovery.test.js+++ b/server/services/initializedCheckoutRecovery.test.js@@ -69,7 +69,7 @@ beforeEach(async () => {const facts = { prUrl, prHead: release.head, defaultHead: 'b'.repeat(40) };const snapshot = { fingerprint: 'c'.repeat(64), administrationFingerprint: 'd'.repeat(64), identity: { working: 1, administration: 2, common: 3 } };fixture = { cut: null, facts, snapshot, headExists: true, placement: { working: 'original', administration: 'original' }, failPart: null,- metadataToken: 'f'.repeat(64) };+ metadataToken: 'f'.repeat(64), finalizationToken: '7'.repeat(64) };const admission = {withCheckoutPublication: async (_repo, work) => { if (fixture.cut) throw new Error('checkout-retirement-reserved'); return work(); },reserveCheckoutRetirement: vi.fn(async (_repo, id) => {@@ -96,9 +96,23 @@ beforeEach(async () => {metadataRecovery: { version: 1, digest: fixture.metadataToken, evidenceFile: 'private-proof.json', evidenceSha256: fixture.metadataToken },initialPlacements: { ...fixture.placement }, changeCounts: { residualCompressionRemoved: 3, rootProvenanceAdded: 1 }, changedPaths: 4,};+ if (input.command === 'review-restored-finalization') {+ if (fixture.failArchive) throw new Error('archive-changed');+ return { restoredFinalization: { version: 1, evidenceFile: 'finalization.json',+ evidenceSha256: fixture.finalizationToken, digest: fixture.finalizationToken },+ placements: { ...fixture.placement }, changeCounts: { directoryMtimeChanged: 2, residualCompressionReappeared: 1 }, changedPaths: 3 };+ }+ if (input.command === 'verify-restored-finalization') {+ if (fixture.failFinalization || input.restoredFinalization?.digest !== fixture.finalizationToken) throw new Error('finalization-evidence-changed');+ return { verified: true, alreadyRestored: true, restoredFinalizationAccepted: true,+ placements: Object.fromEntries(Object.entries(fixture.placement).map(([part, state]) => [part, { state }])) };+ }if (['verify', 'move', 'status'].includes(input.command) && input.manifestSha256 !== 'e'.repeat(64)) throw new Error('archive-manifest-proof-changed');+ if (fixture.delayedRestoreDrift && input.command === 'verify' && input.mode === 'restore'+ && Object.values(fixture.placement).every(value => value === 'original')) throw new Error('source-content-or-identity-changed:working');if (fixture.metadataDrift && ['verify', 'move'].includes(input.command) && input.mode !== 'standalone'&& input.metadataRecovery?.digest !== fixture.metadataToken) throw new Error('source-content-or-identity-changed:working');+ const alreadyRestored = input.command === 'move' && input.direction === 'restore' && fixture.placement[input.part] === 'original';if (input.command === 'move') {if (fixture.failPart === input.part && input.direction === 'quarantine') throw new Error('move-refused');if (fixture.failRestorePart === input.part && input.direction === 'restore') throw new Error('restore-interrupted');@@ -106,7 +120,9 @@ beforeEach(async () => {}if (fixture.failArchive && input.command === 'verify') throw new Error('archive-changed');return { ok: true, placement: fixture.placement, fingerprint: fixture.snapshot.fingerprint,- ...(input.metadataRecovery ? { postMoveObservation: { file: 'post-move.json', sha256: fixture.metadataToken } } : {}),+ ...(input.metadataRecovery && !alreadyRestored ? {+ postMoveObservation: { file: `${input.part}-post-move.json`, sha256: fixture.metadataToken, digest: fixture.metadataToken },+ } : {}),placements: Object.fromEntries(Object.entries(fixture.placement).map(([part, state]) => [part, { state: state === 'quarantined' ? 'quarantine' : state }])) };});const deps = { root: () => root, fenced: work => work(), admission, native,@@ -328,6 +344,145 @@ describe('initialized checkout transaction', () => {.toMatchObject({ ok: true, restored: true });expect(fixture.cut).toBeNull();});+ const restoredWithDelayedDrift = async () => {+ const input = await interruptedMetadata();+ const prepared = await fixture.service.reviewMetadataRestore(input);+ fixture.delayedRestoreDrift = true;+ expect(await fixture.service.restoreMetadata({ ...input, review: { digest: prepared.review.digest } }))+ .toMatchObject({ ok: false, reason: 'source-content-or-identity-changed:working' });+ const status = await fixture.service.status(input);+ expect(status.phase).toBe('metadata-restored-working');+ expect(fixture.placement).toEqual({ working: 'original', administration: 'original' });+ return { ...input, journalDigest: status.journalDigest };+ };+ it('finalizes a retried restore using only its current observations while retaining earlier immutable evidence', async () => {+ const original = fixture.deps.native.getMockImplementation();+ fixture.deps.native.mockImplementation(async input => {+ const result = await original(input);+ if (input.command === 'move' && input.direction === 'quarantine' && input.part === 'administration') {+ fixture.metadataDrift = true;+ }+ return result;+ });+ const retired = await fixture.service.retire(await reviewed());+ expect(retired).toMatchObject({ ok: false, reason: 'source-content-or-identity-changed:working' });+ expect(fixture.placement).toEqual({ working: 'quarantined', administration: 'quarantined' });+ const status = await fixture.service.status({ appId: 'app', transactionId: retired.transactionId });+ const input = { appId: 'app', transactionId: retired.transactionId, journalDigest: status.journalDigest };+ const firstReview = await fixture.service.reviewMetadataRestore(input);+ fixture.failRestorePart = 'working';+ expect(await fixture.service.restoreMetadata({ ...input, review: { digest: firstReview.review.digest } }))+ .toMatchObject({ ok: false, reason: 'restore-interrupted' });+ expect(fixture.placement).toEqual({ working: 'quarantined', administration: 'original' });+ const directory = join(root, input.transactionId);+ const names = (await readdir(directory)).filter(name => /^\d{6}\.json$/.test(name)).sort();+ const previousFile = join(directory, names.at(-1));+ const previousBytes = await readFile(previousFile, 'utf8');+ expect(JSON.parse(previousBytes).metadataRestoreObservations)+ .toEqual([{ part: 'administration', proof: expect.objectContaining({ file: 'administration-post-move.json' }) }]);+ const retryStatus = await fixture.service.status(input);+ const retry = { ...input, journalDigest: retryStatus.journalDigest };+ const nextReview = await fixture.service.reviewMetadataRestore(retry);+ fixture.failRestorePart = null;+ fixture.delayedRestoreDrift = true;+ expect(await fixture.service.restoreMetadata({ ...retry, review: { digest: nextReview.review.digest } }))+ .toMatchObject({ ok: false, reason: 'source-content-or-identity-changed:working' });+ const finalStatus = await fixture.service.status(input);+ const finalInput = { ...input, journalDigest: finalStatus.journalDigest };+ const finalReview = await fixture.service.reviewRestoredFinalization(finalInput);+ expect(finalReview).toMatchObject({ ok: true, review: { postMoveObservations: [+ { part: 'administration' }, { part: 'working', proof: { file: 'working-post-move.json' } },+ ] } });+ expect(finalReview.review.postMoveObservations).toHaveLength(2);+ expect(await fixture.service.finalizeRestored({ ...finalInput, review: { digest: finalReview.review.digest } }))+ .toMatchObject({ ok: true, restored: true });+ expect(await readFile(previousFile, 'utf8')).toBe(previousBytes);+ expect(fixture.cut).toBeNull();+ expect(fixture.deps.deleteRef).not.toHaveBeenCalled();+ });+ it('finalizes already-restored originals only with a new review bound to the actual no-op and move evidence', async () => {+ const input = await restoredWithDelayedDrift();+ const before = fixture.deps.native.mock.calls.filter(([row]) => row.command === 'move').length;+ const prepared = await fixture.service.reviewRestoredFinalization(input);+ expect(prepared).toMatchObject({ ok: true, review: { mode: 'finalize-already-restored',+ postMoveObservations: [{ part: 'administration' }, { part: 'working', proof: { digest: fixture.metadataToken } }] } });+ const result = await fixture.service.finalizeRestored({ ...input, review: { digest: prepared.review.digest } });+ expect(result).toMatchObject({ ok: true, alreadyRestored: true, phase: 'restored-with-reviewed-finalization', archivesRetained: true });+ expect(fixture.cut).toBeNull();+ expect(fixture.headExists).toBe(true);+ expect(fixture.deps.deleteRef).not.toHaveBeenCalled();+ expect(fixture.deps.native.mock.calls.filter(([row]) => row.command === 'move')).toHaveLength(before);+ expect(fixture.deps.native).toHaveBeenCalledWith(expect.objectContaining({+ command: 'verify-restored-finalization', postMoveObservations: [null, expect.objectContaining({ file: 'working-post-move.json' })],+ }));+ expect(await readFile(join(root, input.transactionId, 'manifest.json'), 'utf8')).toBe('{}');+ expect(await fixture.service.status(input)).toMatchObject({ restoredFinalizationComplete: true });+ });+ it.each(['delta', 'owner', 'ref', 'holder', 'cut', 'archive'])('retains the cut when finalization %s evidence changes', async change => {+ const input = await restoredWithDelayedDrift();+ const prepared = await fixture.service.reviewRestoredFinalization(input);+ if (change === 'delta') fixture.finalizationToken = '8'.repeat(64);+ if (change === 'owner') fixture.deps.ownership.mockResolvedValue({ ok: false, reason: 'active-owner' });+ if (change === 'ref') fixture.headExists = false;+ if (change === 'holder') fixture.newHolder = true;+ if (change === 'cut') fixture.cut.owner.id = 'different-owner';+ if (change === 'archive') fixture.failArchive = true;+ const releases = fixture.deps.admission.releaseCheckoutReservation.mock.calls.length;+ expect(await fixture.service.finalizeRestored({ ...input, review: { digest: prepared.review.digest } })).toMatchObject({ ok: false, recoveryRequired: true });+ expect(fixture.cut).not.toBeNull();+ expect(fixture.deps.admission.releaseCheckoutReservation).toHaveBeenCalledTimes(releases);+ expect(fixture.deps.deleteRef).not.toHaveBeenCalled();+ });+ it('requires a new finalization approval after a durable approved phase is interrupted', async () => {+ const input = await restoredWithDelayedDrift();+ const prepared = await fixture.service.reviewRestoredFinalization(input);+ fixture.failFinalization = true;+ expect(await fixture.service.finalizeRestored({ ...input, review: { digest: prepared.review.digest } }))+ .toMatchObject({ ok: false, reason: 'finalization-evidence-changed' });+ const restarted = _createInitializedCheckoutRecovery(fixture.deps);+ const status = await restarted.status(input);+ expect(status.phase).toBe('restored-finalization-approved');+ expect(await restarted.finalizeRestored({ ...input, review: { digest: prepared.review.digest } }))+ .toMatchObject({ ok: false, reason: 'retirement-journal-changed' });+ const fresh = { ...input, journalDigest: status.journalDigest };+ expect(await restarted.finalizeRestored({ ...fresh, review: { digest: prepared.review.digest } }))+ .toMatchObject({ ok: false, reason: 'restored-finalization-review-changed' });+ fixture.failFinalization = false;+ const next = await restarted.reviewRestoredFinalization(fresh);+ expect(await restarted.finalizeRestored({ ...fresh, review: { digest: next.review.digest } })).toMatchObject({ ok: true });+ });+ it.each([false, true])('replays only final proof and release after uncertain release, cutAlreadyReleased=%s', async released => {+ const input = await restoredWithDelayedDrift();+ const prepared = await fixture.service.reviewRestoredFinalization(input);+ fixture.deps.admission.releaseCheckoutReservation.mockImplementationOnce(async () => {+ if (released) fixture.cut = null;+ throw new Error('release-acknowledgement-lost');+ });+ expect(await fixture.service.finalizeRestored({ ...input, review: { digest: prepared.review.digest } }))+ .toMatchObject({ ok: false, reason: 'release-acknowledgement-lost' });+ const restarted = _createInitializedCheckoutRecovery(fixture.deps);+ const status = await restarted.status(input);+ expect(status.phase).toBe('restored-with-reviewed-finalization');+ const commands = fixture.deps.native.mock.calls.length;+ expect(await restarted.finalizeRestored({ ...input, journalDigest: status.journalDigest, review: { digest: prepared.review.digest } }))+ .toMatchObject({ ok: true, alreadyRestored: true });+ expect(fixture.deps.native.mock.calls.slice(commands).map(([row]) => row.command)).toEqual(['lock', 'verify-restored-finalization']);+ expect(fixture.cut).toBeNull();+ expect(fixture.deps.deleteRef).not.toHaveBeenCalled();+ });+ it('rechecks ownership after final native verification and retains the reservation on a new owner', async () => {+ const input = await restoredWithDelayedDrift();+ const prepared = await fixture.service.reviewRestoredFinalization(input);+ const original = fixture.deps.native.getMockImplementation();+ fixture.deps.native.mockImplementation(async value => {+ const result = await original(value);+ if (value.command === 'verify-restored-finalization') fixture.deps.ownership.mockResolvedValue({ ok: false, reason: 'active-owner' });+ return result;+ });+ expect(await fixture.service.finalizeRestored({ ...input, review: { digest: prepared.review.digest } }))+ .toMatchObject({ ok: false, reason: 'active-owner' });+ expect(fixture.cut).not.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());