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: preserve copy-added provenance during checkout retirement (#12631)

[._.]/ae5837f49b54
diff --git a/docs/STORAGE.md b/docs/STORAGE.md
index 4adf37eb77..30a7bbb640 100644
--- a/docs/STORAGE.md
+++ b/docs/STORAGE.md
@@ -1042,7 +1042,13 @@ checkout retirement. Version 1 immutable numbered JSON steps form a SHA-256
linked journal; each step and containing directory is fsynced. The directory is
0700 and journal/native manifests are 0600. `archive/` preserves original bytes
and metadata, `restore/` holds a proven standalone checkout and Git stores, and
-`quarantine/` retains whole original directories. `execution.lock` and
+`quarantine/` retains whole original directories. Native manifest version 2 records
+per-path hashes for OS-added `com.apple.provenance` on copies only; original
+attributes cannot change or disappear. Archive additions must keep their exact
+recorded hashes, and the final standalone manifest remains exact. The preservation
+proof journals the SHA-256 of the exact manifest bytes; later native reads verify
+that binding, including when an edited manifest claims an older version. Version 1
+archives retain their original strict comparison. `execution.lock` and
`backend.lock` serialize service executors and surviving native commands. These
are private archives, excluded from federation and never seeded, migrated into
PostgreSQL, expired or automatically purged. No existing-record migration is
diff --git a/docs/features/branch-reconciliation.md b/docs/features/branch-reconciliation.md
index da22787a69..b94b639080 100644
--- a/docs/features/branch-reconciliation.md
+++ b/docs/features/branch-reconciliation.md
@@ -99,6 +99,14 @@ The native backend preserves file bytes, permissions, ownership, timestamps,
ACLs, xattrs, supported flags, empty directories, hard links and symlink targets
without following symlink dependencies. It retains original identity evidence;
only the standalone copy's Git pointers are rewritten to its isolated stores.
+An OS-added `com.apple.provenance` attribute on a copy is retained and recorded
+with its exact hash; changed existing attributes, missing attributes and other
+additions still refuse preservation. No provenance or quarantine attribute is
+removed or rewritten. Original and quarantined metadata stay exact. Every later
+archive verification or move is bound to the exact manifest hash journaled after
+preservation. If that journal write is interrupted before any move, status
+exposes an unverified-archive hold and a digest for source-verified cancellation;
+it does not infer a preservation proof from the retained manifest.
Shared/external/nested module stores, alternates, promisor dependencies, active
Git operations, insufficient space and unsupported metadata hold the operation.
A full parent store copy and a second standalone restore require bounded free
diff --git a/scripts/lib/initialized_checkout_archive.py b/scripts/lib/initialized_checkout_archive.py
index 9eedccb735..a5038d673b 100644
--- a/scripts/lib/initialized_checkout_archive.py
+++ b/scripts/lib/initialized_checkout_archive.py
@@ -191,6 +191,28 @@ def same_copy(actual, expected):
return portable(actual) == portable(expected)
+def copy_augmentations(actual, expected):
+ """Record only OS-added provenance; never discard or normalize source attrs."""
+ if len(actual) != len(expected):
+ return None
+ additions = []
+ for copied, source in zip(actual, expected):
+ attrs = copied.get('xattrs', {})
+ original = source.get('xattrs', {})
+ extra = set(attrs) - set(original)
+ if extra - {'com.apple.provenance'}:
+ return None
+ if extra:
+ value = attrs['com.apple.provenance']
+ if not isinstance(value, str) or not re.fullmatch(r'[0-9a-f]{64}', value):
+ return None
+ additions.append({'path': copied['path'], 'xattrs': {'com.apple.provenance': value}})
+ without_added = {**copied, 'xattrs': {key: value for key, value in attrs.items() if key not in extra}}
+ if not same_copy([without_added], [source]):
+ return None
+ return additions
+
+
def fsync_dir(path):
fd = os.open(path, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
try:
@@ -200,12 +222,13 @@ def fsync_dir(path):
def private_json(path, data):
- with os.fdopen(os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600), 'w') as out:
- json.dump(data, out, sort_keys=True)
- out.write('\n')
+ encoded = (json.dumps(data, sort_keys=True) + '\n').encode('utf-8')
+ with os.fdopen(os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600), 'wb') as out:
+ out.write(encoded)
out.flush()
os.fsync(out.fileno())
fsync_dir(path.parent)
+ return hashlib.sha256(encoded).hexdigest()
def read_pointer(path, prefix='', directory=True):
@@ -466,8 +489,8 @@ def rewrite_copy(path, text):
# Only isolated proof pointers are rewritten; archive pointer bytes remain exact.
if not stat.S_ISREG(path.lstat().st_mode):
fail('restore-pointer-not-regular')
- with path.open('w') as out:
- out.write(text)
+ with path.open('wb') as out:
+ out.write(text.encode('utf-8') if isinstance(text, str) else text)
out.flush()
os.fsync(out.fileno())
@@ -543,19 +566,28 @@ def preserve(request):
# Persist the complete source evidence before copying. Failure leaves a
# recognizable incomplete archive; retry never overwrites any part.
private_json(root / 'source.json', before)
+ augmentations = {'archive': {'common': {}}, 'restore': {}}
for label, source in [('working', work), ('administration', admin)]:
copy_tree(source, root / 'archive' / label)
- if not same_copy(manifest(root / 'archive' / label), before['sources'][label]):
+ added = copy_augmentations(manifest(root / 'archive' / label), before['sources'][label])
+ if added is None:
fail('archive-metadata-mismatch:' + label)
+ augmentations['archive'][label] = added
(root / 'archive' / 'common').mkdir(mode=0o700)
for name, expected_rows in before['sources']['common'].items():
copy_tree(common / name, root / 'archive' / 'common' / name)
- if not same_copy(manifest(root / 'archive' / 'common' / name, True), expected_rows):
+ added = copy_augmentations(manifest(root / 'archive' / 'common' / name, True), expected_rows)
+ if added is None:
fail('shared-archive-metadata-mismatch:' + name)
+ augmentations['archive']['common'][name] = added
for label in ('working', 'administration', 'common'):
copy_tree(root / 'archive' / label, root / 'restore' / label)
- if not same_copy(manifest(root / 'archive' / label), manifest(root / 'restore' / label)):
+ added = copy_augmentations(manifest(root / 'restore' / label), manifest(root / 'archive' / label))
+ if added is None:
fail('restore-copy-metadata-mismatch')
+ # Historical pre-relocation evidence; saved.restored below is the exact
+ # post-relocation expectation used by every later restore verification.
+ augmentations['restore'][label] = added
restore = root / 'restore'
rewrite_copy(restore / 'working' / '.git', 'gitdir: ' + str(restore / 'administration') + '\n')
rewrite_copy(restore / 'administration' / 'commondir', str(restore / 'common') + '\n')
@@ -563,7 +595,15 @@ def preserve(request):
for m in before['modules']:
store, tree = restore / 'administration' / m['administrationPath'], restore / 'working' / m['path']
rewrite_copy(tree / '.git', 'gitdir: ' + str(store) + '\n')
- git(store, tree, 'config', '--file', str(store / 'config'), 'core.worktree', str(tree))
+ # Git config publishes through lock/rename, which can discard inherited
+ # xattrs. Generate only replacement bytes outside the proof tree, then
+ # rewrite the isolated config in place without changing its metadata.
+ scratch = root / 'relocated-module-config'
+ with os.fdopen(os.open(scratch, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600), 'wb') as out:
+ out.write((store / 'config').read_bytes())
+ git(store, tree, 'config', '--file', str(scratch), 'core.worktree', str(tree))
+ rewrite_copy(store / 'config', scratch.read_bytes())
+ scratch.unlink()
proof = proof_repositories(root, before)
# Check source metadata again after both full copies and offline proof.
after = inspect(request, full=True)
@@ -572,21 +612,32 @@ def preserve(request):
restored = {label: manifest(restore / label) for label in ('working', 'administration', 'common')}
durable_tree(root / 'archive')
durable_tree(restore)
- saved = {'version': 1, 'transactionIdentity': identity(root), 'facts': before,
- 'restored': restored, 'restoreProof': proof}
- private_json(root / 'manifest.json', saved)
- return {'manifestPath': str(root / 'manifest.json'), 'fingerprint': before['fingerprint'],
+ saved = {'version': 2, 'transactionIdentity': identity(root), 'facts': before,
+ 'copyAugmentations': augmentations, 'restored': restored, 'restoreProof': proof}
+ check_restore_augmentations(root, saved)
+ manifest_sha = private_json(root / 'manifest.json', saved)
+ return {'manifestSha256': manifest_sha, 'manifestPath': str(root / 'manifest.json'), 'fingerprint': before['fingerprint'],
'administrationFingerprint': before['administrationFingerprint'], 'restoreProof': proof}
def load_transaction(request):
root = transaction(request['transactionDir'])
path = root / 'manifest.json'
- if not stat.S_ISREG(path.lstat().st_mode) or path.stat().st_size > 256 * 1024 ** 2:
+ 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-archive-manifest')
+ encoded = source.read(limit + 1)
+ if len(encoded) > limit:
fail('invalid-archive-manifest')
- saved = json.loads(path.read_text())
- if saved['version'] != 1 or saved['transactionIdentity'] != identity(root):
+ saved = json.loads(encoded)
+ if saved['version'] not in (1, 2) or saved['transactionIdentity'] != identity(root):
fail('transaction-incarnation-changed')
+ # A bound v2 archive cannot evade its journal proof by declaring itself v1.
+ # Hash the exact bytes parsed, never a second path read after parsing.
+ if (saved['version'] == 2 or 'manifestSha256' in request) and request.get('manifestSha256') != hashlib.sha256(encoded).hexdigest():
+ fail('archive-manifest-proof-changed')
for label in ('archive', 'restore', 'quarantine'):
safe_path(str(root / label))
return root, saved
@@ -610,13 +661,36 @@ def placements(root, facts):
return result
+def check_restore_augmentations(root, saved):
+ if saved['version'] == 1:
+ return
+ records = saved['copyAugmentations']
+ if (set(records) != {'archive', 'restore'}
+ or set(records['archive']) != {'working', 'administration', 'common'}
+ or set(records['archive']['common']) != set(saved['facts']['sources']['common'])
+ or set(records['restore']) != {'working', 'administration', 'common'}):
+ fail('invalid-copy-augmentation-layout')
+ for label in ('working', 'administration', 'common'):
+ archived = manifest(root / 'archive' / label)
+ attrs = lambda rows: [{'path': row['path'], 'xattrs': row['xattrs']} for row in rows]
+ added = copy_augmentations(attrs(saved['restored'][label]), attrs(archived))
+ if added is None or added != records['restore'][label]:
+ fail('restore-copy-augmentation-changed:' + label)
+
+
def verify_saved_archive(root, saved):
+ check_restore_augmentations(root, saved)
facts = saved['facts']
+ recorded = saved['copyAugmentations']['archive'] if saved['version'] == 2 else None
for label in ('working', 'administration'):
- if not same_copy(manifest(root / 'archive' / label), facts['sources'][label]):
+ expected_added = recorded[label] if recorded is not None else []
+ added = copy_augmentations(manifest(root / 'archive' / label), facts['sources'][label])
+ if added is None or added != expected_added:
fail('archive-changed:' + label)
for name, expected in facts['sources']['common'].items():
- if not same_copy(manifest(root / 'archive' / 'common' / name, True), expected):
+ expected_added = recorded['common'][name] if recorded is not None else []
+ added = copy_augmentations(manifest(root / 'archive' / 'common' / name, True), expected)
+ if added is None or added != expected_added:
fail('common-archive-changed:' + name)
if sorted(p.name for p in (root / 'archive/common').iterdir()) != sorted(facts['sources']['common']):
fail('common-archive-layout-changed')
diff --git a/scripts/lib/initialized_checkout_archive_test.py b/scripts/lib/initialized_checkout_archive_test.py
index d0cf40bb2a..644d7da740 100644
--- a/scripts/lib/initialized_checkout_archive_test.py
+++ b/scripts/lib/initialized_checkout_archive_test.py
@@ -1,5 +1,6 @@
"""Disposable native integration fixtures; never use an installed checkout."""
import importlib.util
+import copy
import json
import os
from pathlib import Path
@@ -9,12 +10,37 @@ import subprocess
import sys
import tempfile
import unittest
+from unittest.mock import patch
SPEC = importlib.util.spec_from_file_location('archive', Path(__file__).with_name('initialized_checkout_archive.py'))
archive = importlib.util.module_from_spec(SPEC)
SPEC.loader.exec_module(archive)
+class CopyMetadata(unittest.TestCase):
+ def test_only_new_provenance_is_recorded_and_original_evidence_is_exact(self):
+ source = {'path': 'evidence', 'kind': 'file', 'sha256': 'a' * 64,
+ 'mode': 0o600, 'xattrs': {'fixture.original': 'b' * 64}}
+ copied = {**source, 'xattrs': {**source['xattrs'], 'com.apple.provenance': 'c' * 64}}
+ self.assertEqual(archive.copy_augmentations([copied], [source]),
+ [{'path': 'evidence', 'xattrs': {'com.apple.provenance': 'c' * 64}}])
+ self.assertEqual(archive.copy_augmentations([source], [source]), [])
+ for invalid in (
+ {**copied, 'sha256': 'd' * 64},
+ {**copied, 'mode': 0o644},
+ {**copied, 'path': 'other'},
+ {**copied, 'xattrs': {'com.apple.provenance': 'c' * 64}},
+ {**copied, 'xattrs': {**copied['xattrs'], 'fixture.original': 'd' * 64}},
+ {**copied, 'xattrs': {**copied['xattrs'], 'unknown.attribute': 'd' * 64}},
+ {**copied, 'xattrs': {**copied['xattrs'], 'com.apple.provenance': 'invalid'}},
+ ):
+ with self.subTest(invalid=invalid):
+ self.assertIsNone(archive.copy_augmentations([invalid], [source]))
+ for invalid in (source, {**copied, 'xattrs': {**copied['xattrs'], 'com.apple.provenance': 'd' * 64}}):
+ self.assertIsNone(archive.copy_augmentations([invalid], [copied]))
+ self.assertIsNone(archive.copy_augmentations([], [source]))
+
+
@unittest.skipUnless(sys.platform == 'darwin', 'Darwin metadata/rename ABI required')
class NativeArchive(unittest.TestCase):
def setUp(self):
@@ -69,7 +95,9 @@ class NativeArchive(unittest.TestCase):
def preserve(self):
self.request['expected'] = archive.inspect(self.request)
- return archive.preserve(self.request)
+ proof = archive.preserve(self.request)
+ self.request['manifestSha256'] = proof['manifestSha256']
+ return proof
def test_admission_bookkeeping_does_not_change_source_review(self):
before = archive.inspect(self.request)
@@ -137,6 +165,131 @@ class NativeArchive(unittest.TestCase):
finally:
path.unlink()
+ def test_recorded_copy_provenance_is_strict_on_archive_and_restore_rechecks(self):
+ raw = archive.raw_xattrs
+ change = {'mode': None}
+ def observed(path):
+ attrs = raw(path)
+ if path.is_relative_to(self.txn / 'archive') or path.is_relative_to(self.txn / 'restore'):
+ # Simulate the OS copy augmentation at the metadata observation
+ # boundary; never set/remove provenance on the real filesystem.
+ if path != self.txn / 'archive/working/ignored':
+ attrs = {**attrs, 'com.apple.provenance': b'copy provenance'}
+ if path == self.txn / 'archive/working/base.txt':
+ if change['mode'] == 'missing':
+ attrs = {key: value for key, value in attrs.items() if key != 'com.apple.provenance'}
+ if change['mode'] == 'changed':
+ attrs = {**attrs, 'com.apple.provenance': b'changed'}
+ if change['mode'] == 'unknown':
+ attrs = {**attrs, 'fixture.unrecorded': b'unrecorded'}
+ if path == self.txn / 'archive/working/ignored' and change['mode'] == 'new':
+ attrs = {**attrs, 'com.apple.provenance': b'late addition'}
+ if path == self.txn / 'restore/working/ignored' and change['mode'] == 'restore':
+ attrs = {**attrs, 'com.apple.provenance': b'changed restore'}
+ return attrs
+ original = archive.inspect(self.request)
+ module_config = Path(original['privateGitDir']) / original['modules'][0]['administrationPath'] / 'config'
+ subprocess.run(['/usr/bin/xattr', '-w', 'fixture.module.config', 'inherited', str(module_config)], check=True)
+ original = archive.inspect(self.request)
+ with patch.object(archive, 'raw_xattrs', observed):
+ self.preserve()
+ saved = json.loads((self.txn / 'manifest.json').read_text())
+ self.assertEqual(saved['version'], 2)
+ self.assertTrue(saved['copyAugmentations']['archive']['working'])
+ config_path = original['modules'][0]['administrationPath'] + '/config'
+ copied_config = next(row for row in saved['restored']['administration'] if row['path'] == config_path)
+ self.assertEqual(copied_config['xattrs']['fixture.module.config'], archive.hashlib.sha256(b'inherited').hexdigest())
+ self.assertEqual(copied_config['xattrs']['com.apple.provenance'], archive.hashlib.sha256(b'copy provenance').hexdigest())
+ self.assertEqual(saved['copyAugmentations']['restore']['working'][0]['path'], 'ignored')
+ self.assertEqual(archive.inspect(self.request), original)
+ self.assertTrue(archive.verify(self.request)['verified'])
+ self.assertTrue(archive.verify({**self.request, 'mode': 'standalone'})['standalone'])
+ for mode in ('removed-record', 'changed-hash', 'new-record'):
+ altered = copy.deepcopy(saved)
+ rows = altered['copyAugmentations']['archive']['working']
+ if mode == 'removed-record':
+ rows.pop()
+ elif mode == 'changed-hash':
+ rows[0]['xattrs']['com.apple.provenance'] = '0' * 64
+ else:
+ rows.append({'path': 'unrecorded', 'xattrs': {'com.apple.provenance': '0' * 64}})
+ with self.subTest(mode=mode), self.assertRaisesRegex(RuntimeError, 'archive-changed'):
+ archive.verify_saved_archive(self.txn, altered)
+ for mode in ('missing', 'changed', 'unknown', 'new', 'restore'):
+ change['mode'] = mode
+ with self.subTest(mode=mode), self.assertRaisesRegex(RuntimeError, 'archive-changed|restore-proof-changed|restore-copy-augmentation-changed'):
+ archive.verify({**self.request, 'mode': 'standalone'})
+ change['mode'] = None
+ with self.assertRaisesRegex(RuntimeError, 'archive-manifest-proof-changed'):
+ archive.verify({key: value for key, value in self.request.items() if key != 'manifestSha256'})
+ manifest_path = self.txn / 'manifest.json'
+ original_manifest = manifest_path.read_bytes()
+ altered = copy.deepcopy(saved)
+ for row in altered['copyAugmentations']['archive']['working']:
+ if row['path'] == 'base.txt':
+ row['xattrs']['com.apple.provenance'] = archive.hashlib.sha256(b'changed').hexdigest()
+ manifest_path.write_text(json.dumps(altered))
+ change['mode'] = 'changed'
+ try:
+ with self.assertRaisesRegex(RuntimeError, 'archive-manifest-proof-changed'):
+ archive.verify({**self.request, 'mode': 'standalone'})
+ finally:
+ manifest_path.write_bytes(original_manifest)
+ change['mode'] = None
+ for part in ('working', 'administration'):
+ archive.move({**self.request, 'part': part, 'direction': 'quarantine'})
+ self.assertEqual(archive.manifest(self.txn / 'quarantine/working'), saved['facts']['sources']['working'])
+ for part in ('administration', 'working'):
+ archive.move({**self.request, 'part': part, 'direction': 'restore'})
+ self.assertEqual(archive.inspect(self.request), original)
+
+ def test_manifest_proof_binds_exact_written_and_parsed_bytes(self):
+ # Simulate replacement after the producer fsync: the returned proof must
+ # still describe the saved bytes, and consuming the replacement holds.
+ original_sync = archive.fsync_dir
+ changed = {'done': False, 'written': None}
+ path = self.txn / 'manifest.json'
+ def replace_after_write(directory):
+ original_sync(directory)
+ if directory == self.txn and path.exists() and not changed['done']:
+ changed['done'] = True
+ changed['written'] = path.read_bytes()
+ path.write_bytes(changed['written'] + b' ')
+ with patch.object(archive, 'fsync_dir', replace_after_write):
+ proof = self.preserve()
+ self.assertEqual(proof['manifestSha256'], archive.hashlib.sha256(changed['written']).hexdigest())
+ with self.assertRaisesRegex(RuntimeError, 'archive-manifest-proof-changed'):
+ archive.load_transaction(self.request)
+ path.write_bytes(changed['written'])
+ original_loads = json.loads
+ replacement = changed['written'] + b' '
+ def replace_after_read(encoded):
+ path.write_bytes(replacement)
+ return original_loads(encoded)
+ # A digest from a later path read must not bless earlier parsed bytes.
+ with patch.object(archive.json, 'loads', replace_after_read), self.assertRaisesRegex(RuntimeError, 'archive-manifest-proof-changed'):
+ archive.load_transaction({**self.request, 'manifestSha256': archive.hashlib.sha256(replacement).hexdigest()})
+
+ def test_version_one_archive_does_not_accept_unrecorded_copy_provenance(self):
+ self.preserve()
+ saved = json.loads((self.txn / 'manifest.json').read_text())
+ self.assertFalse(any(saved['copyAugmentations']['archive'][part]
+ for part in ('working', 'administration')))
+ self.assertFalse(any(saved['copyAugmentations']['archive']['common'].values()))
+ saved['version'] = 1
+ del saved['copyAugmentations']
+ (self.txn / 'manifest.json').write_text(json.dumps(saved))
+ with self.assertRaisesRegex(RuntimeError, 'archive-manifest-proof-changed'):
+ archive.verify(self.request)
+ del self.request['manifestSha256'] # Genuine legacy callers have no bound v2 proof.
+ self.assertTrue(archive.verify(self.request)['verified'])
+ raw = archive.raw_xattrs
+ def augmented(path):
+ attrs = raw(path)
+ return {**attrs, 'com.apple.provenance': b'unrecorded'} if path == self.txn / 'archive/working/base.txt' else attrs
+ with patch.object(archive, 'raw_xattrs', augmented), self.assertRaisesRegex(RuntimeError, 'archive-changed'):
+ archive.verify({**self.request, 'mode': 'standalone'})
+
def test_restore_is_offline_and_preserves_staged_private_and_metadata(self):
subprocess.run(['/usr/bin/xattr', '-w', 'fixture.attribute', 'preserved', str(self.work / 'ignored')], check=True)
subprocess.run(['/usr/bin/xattr', '-w', 'com.apple.decmpfs', 'fixture-residual',
diff --git a/server/services/initializedCheckoutRecovery.js b/server/services/initializedCheckoutRecovery.js
index 8db7f989a7..9a4830cd79 100644
--- a/server/services/initializedCheckoutRecovery.js
+++ b/server/services/initializedCheckoutRecovery.js
@@ -200,14 +200,14 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
expected: prepared.review.snapshot, transactionDir: directory });
state = await appendStep(directory, state, 'preserved', { proof: preserved });
await verifyFacts(ctx, state, true);
- await native({ command: 'verify', transactionDir: directory });
+ await native({ command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory });
for (const part of ['working', 'administration']) {
executor.assertHeld();
state = await appendStep(directory, state, `quarantine-${part}-intent`);
- await native({ command: 'move', transactionDir: directory, part, direction: 'quarantine' });
+ await native({ command: 'move', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, part, direction: 'quarantine' });
state = await appendStep(directory, state, `quarantined-${part}`);
}
- await native({ command: 'verify', transactionDir: directory });
+ await native({ command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory });
await verifyFacts(ctx, state, false);
executor.assertHeld();
// Keep the original ref available for exact in-place rollback. A later
@@ -237,7 +237,7 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
const branchReview = async ({ directory, state, ctx }) => {
if (state.phase !== 'quarantined' || state.branchDeleted) fail('retirement-branch-phase-not-ready');
const policy = await ensureOwner(ctx, state.release, false);
- const proof = await native({ command: 'verify', transactionDir: directory, mode: 'restore' });
+ const proof = await native({ command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, mode: 'restore' });
if (['working', 'administration'].some(part => proof.placements?.[part]?.state !== 'quarantine')) fail('retirement-originals-not-quarantined');
const list = deps.listWorktrees || (await import('./worktreeManager.js')).listWorktrees;
if ((await list(ctx.repoPath)).some(tree => String(tree.branch || '').replace(/^refs\/heads\//, '') === state.release.branch)) fail('branch-has-new-holder');
@@ -267,8 +267,8 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
const verify = async () => {
executor.assertHeld();
await ensureOwner(ctx, state.release, false);
- await native({ command: 'verify', transactionDir: directory, mode: 'standalone' });
- const placement = await native({ command: 'status', transactionDir: directory });
+ await native({ command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, mode: 'standalone' });
+ const placement = await native({ command: 'status', manifestSha256: state.proof?.manifestSha256, transactionDir: directory });
if (['working', 'administration'].some(part => placement.placements?.[part]?.state !== 'quarantine')) fail('retirement-originals-not-quarantined');
const list = deps.listWorktrees || (await import('./worktreeManager.js')).listWorktrees;
if ((await list(ctx.repoPath)).some(tree => String(tree.branch || '').replace(/^refs\/heads\//, '') === state.release.branch)) fail('branch-has-new-holder');
@@ -336,7 +336,14 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
if (error.code === 'ENOENT') return false;
throw error;
});
- const placement = hasManifest ? await native({ command: 'status', transactionDir: directory }) : { preserved: false };
+ // A manifest can be durable before its proof reaches the journal. Only a
+ // proven pre-move phase may expose cancellation metadata without trusting
+ // that archive; restore still requires a fresh, unchanged-source inspect.
+ const unboundPreservation = hasManifest && !state.proof?.manifestSha256
+ && ['intent', 'reserved', 'preserved'].includes(state.phase);
+ const cancelledUnboundPreservation = state.phase === 'restored' && state.cancelledUnboundPreservation === true;
+ const placement = unboundPreservation || (hasManifest && cancelledUnboundPreservation) ? { preserved: false, unverifiedArchive: true }
+ : hasManifest ? await native({ command: 'status', manifestSha256: state.proof?.manifestSha256, transactionDir: directory }) : { preserved: false };
let branchRef;
if (state.phase === 'branch-retirement-intent') {
const result = await (deps.execGit || execGit)(['show-ref', '--verify', '--quiet', `refs/heads/${state.release.branch}`], ctx.repoPath, { ignoreExitCode: true }).catch(() => null);
@@ -344,6 +351,7 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
}
return { ok: true, transactionId, phase: state.phase, release: state.release, placement,
branchDeleted: state.branchDeleted ?? null, journalDigest: hash(state),
+ ...(unboundPreservation ? { recoveryRequired: true, recoveryAction: 'restore', reason: 'preservation-proof-unbound' } : {}),
...(state.phase === 'branch-retirement-intent' ? { branchDeletion: 'uncertain', branchRef, recoveryRequired: true } : {}),
...(state.phase === 'branch-retired' ? { receiptPending: true, recoveryRequired: true } : {}),
...(['branch-retired', 'retired'].includes(state.phase) ? { recoveryAction: 'retire-branch' } : {}) };
@@ -355,7 +363,7 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
if (hash(state) !== input.journalDigest) fail('retirement-journal-changed');
const ctx = await context(input.appId);
if (state.appId !== input.appId || state.repoPath !== ctx.repoPath) fail('retirement-transaction-app-mismatch');
- const proof = await native({ command: 'verify', transactionDir: directory, mode: 'standalone' });
+ const proof = await native({ command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, mode: 'standalone' });
return { ok: true, transactionId: state.id, standaloneCheckoutPath: proof.restorePath,
verified: true, branchDeleted: state.branchDeleted ?? false, proof };
};
@@ -381,17 +389,19 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
// Preservation can fail before a native manifest exists. No move is
// ever attempted before its fsynced intent; only those early phases
// may cancel the cut after a fresh unchanged-source inspection.
- if (['intent', 'reserved', 'preserved'].includes(state.phase)) {
+ if (['intent', 'reserved', 'preserved'].includes(state.phase)
+ || (state.phase === 'restored' && state.cancelledUnboundPreservation === true)) {
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');
- state = await appendStep(directory, state, 'restored', { reservation });
+ state = await appendStep(directory, state, 'restored', { reservation,
+ cancelledUnboundPreservation: !state.proof?.manifestSha256 });
await gate.releaseCheckoutReservation(reservation);
return { ok: true, transactionId: state.id, restored: true, archivesRetained: true };
}
const { listWorktrees } = await import('./worktreeManager.js');
const trees = await (deps.listWorktrees || listWorktrees)(ctx.repoPath);
if (trees.some(tree => String(tree.branch || '').replace(/^refs\/heads\//, '') === state.release.branch && tree.path !== state.release.path)) fail('branch-has-new-holder');
- await native({ command: 'verify', transactionDir: directory, mode: 'restore' });
+ await native({ command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, mode: 'restore' });
const ref = `refs/heads/${state.release.branch}`;
const runGit = deps.execGit || execGit;
const existing = await runGit(['rev-parse', '--verify', ref], ctx.repoPath, { ignoreExitCode: true });
@@ -399,10 +409,10 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
for (const part of ['administration', 'working']) {
executor.assertHeld();
state = await appendStep(directory, state, `restore-${part}-intent`, { reservation });
- await native({ command: 'move', transactionDir: directory, part, direction: 'restore' });
+ await native({ command: 'move', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, part, direction: 'restore' });
state = await appendStep(directory, state, `restored-${part}`);
}
- await native({ command: 'verify', transactionDir: directory, mode: 'restore' });
+ await native({ command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, mode: 'restore' });
state = await appendStep(directory, state, 'restored');
await gate.releaseCheckoutReservation(reservation);
return { ok: true, transactionId: state.id, restored: true, archivesRetained: true };
diff --git a/server/services/initializedCheckoutRecovery.test.js b/server/services/initializedCheckoutRecovery.test.js
index 45a9a1f465..d89828a659 100644
--- a/server/services/initializedCheckoutRecovery.test.js
+++ b/server/services/initializedCheckoutRecovery.test.js
@@ -72,8 +72,10 @@ beforeEach(async () => {
if (input.command === 'preserve') {
if (fixture.failPreserve) throw new Error('archive-no-space');
await writeFile(join(input.transactionDir, 'manifest.json'), '{}', { mode: 0o600 });
- return { ok: true, restoreProof: { verified: true } };
+ if (fixture.failProofJournal) fixture.failNextJournal = true;
+ return { ok: true, manifestSha256: 'e'.repeat(64), restoreProof: { verified: true } };
}
+ if (['verify', 'move', 'status'].includes(input.command) && input.manifestSha256 !== 'e'.repeat(64)) throw new Error('archive-manifest-proof-changed');
if (input.command === 'move') {
if (fixture.failPart === input.part && input.direction === 'quarantine') throw new Error('move-refused');
fixture.placement[input.part] = input.direction === 'quarantine' ? 'quarantined' : 'original';
@@ -163,6 +165,42 @@ 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('exposes only source-verified cancellation after durable preservation loses its proof journal', async () => {
+ fixture.failProofJournal = true;
+ const result = await fixture.service.retire(await reviewed());
+ expect(result).toMatchObject({ ok: false, reason: 'journal-write-interrupted', recoveryRequired: true });
+ const directory = join(root, result.transactionId);
+ expect(await readFile(join(directory, 'manifest.json'), 'utf8')).toBe('{}');
+ expect(fixture.cut).not.toBeNull();
+ const restarted = _createInitializedCheckoutRecovery(fixture.deps);
+ const status = await restarted.status({ appId: 'app', transactionId: result.transactionId });
+ expect(status).toMatchObject({ phase: 'reserved', placement: { preserved: false, unverifiedArchive: true },
+ recoveryRequired: true, recoveryAction: 'restore', reason: 'preservation-proof-unbound' });
+ expect(status.journalDigest).toMatch(/^[a-f0-9]{64}$/);
+ const input = { appId: 'app', transactionId: result.transactionId, journalDigest: status.journalDigest };
+ 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(fixture.cut).not.toBeNull();
+ fixture.snapshot = oldSnapshot;
+ fixture.deps.admission.releaseCheckoutReservation.mockRejectedValueOnce(new Error('release-interrupted'));
+ expect(await restarted.restore(input)).toMatchObject({ ok: false, reason: 'release-interrupted' });
+ expect(fixture.cut).not.toBeNull();
+ const afterReleaseFailure = _createInitializedCheckoutRecovery(fixture.deps);
+ const cancelled = await afterReleaseFailure.status(input);
+ expect(cancelled).toMatchObject({ phase: 'restored', placement: { preserved: false, unverifiedArchive: true } });
+ expect(await afterReleaseFailure.restore({ ...input, journalDigest: cancelled.journalDigest }))
+ .toMatchObject({ ok: true, restored: true, archivesRetained: true });
+ expect(fixture.cut).toBeNull();
+ expect(fixture.placement).toEqual({ working: 'original', administration: 'original' });
+ expect(fixture.deps.native.mock.calls.some(([call]) => call.command === 'move' || call.command === 'status')).toBe(false);
+ expect(await readFile(join(directory, 'manifest.json'), 'utf8')).toBe('{}');
+ const completed = await restarted.status({ appId: 'app', transactionId: result.transactionId });
+ expect(completed).toMatchObject({ phase: 'restored', placement: { preserved: false, unverifiedArchive: true } });
+ expect(completed.recoveryRequired).toBeUndefined();
+ expect(fixture.deps.native.mock.calls.some(([call]) => call.command === 'status')).toBe(false);
+ });
it('requires a fresh accepted review and an explicit supersession decision', async () => {
const input = await reviewed();
fixture.facts.defaultHead = 'e'.repeat(40);
@@ -197,7 +235,7 @@ describe('initialized checkout transaction', () => {
fixture.deps.execGit.mockResolvedValue({ exitCode: 1, stdout: '' });
const input = { appId: 'app', transactionId: result.transactionId, journalDigest: status.journalDigest };
expect(await fixture.service.verifyArchive(input)).toMatchObject({ ok: true, verified: true });
- expect(fixture.deps.native).toHaveBeenLastCalledWith({ command: 'verify', transactionDir: join(root, result.transactionId), mode: 'standalone' });
+ expect(fixture.deps.native).toHaveBeenLastCalledWith({ command: 'verify', manifestSha256: 'e'.repeat(64), transactionDir: join(root, result.transactionId), mode: 'standalone' });
expect(fixture.deps.execGit).not.toHaveBeenCalled();
});
const quarantinedReview = async () => {