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: resume verified initialized checkout quarantines

[._.]/ Adam Eivy8387545bef89
diff --git a/docs/features/branch-reconciliation.md b/docs/features/branch-reconciliation.md
index 2d7196ef07..2778166dd6 100644
--- a/docs/features/branch-reconciliation.md
+++ b/docs/features/branch-reconciliation.md
@@ -213,6 +213,60 @@ node scripts/recover-initialized-checkout.js finalize /absolute/approved-request
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.
+A move-based restore retry refuses when both originals are already restored and
+its working-move proof is present, preserving that evidence for this separate
+finalization path instead of replacing it with no-op observations.
+
+### Completing an interrupted quarantine
+
+When the working directory has already moved into quarantine, restoring it
+solely to retry retirement can trigger further metadata changes. A separate
+reviewed operation can instead finish quarantining its administration while
+preserving the working directory at its existing quarantine location.
+
+1. `POST /review-quarantine-resumption` accepts `appId`, `transactionId` and
+ the current `journalDigest`. Under the native executor and exact existing
+ reservation, it verifies the archive, full current sources, original inode
+ placements, current ownership and branch, and fresh forge/integration
+ evidence for the PR recorded in the original transaction.
+2. Independently inspect the returned `resume-initialized-quarantine` review.
+ Its distinct native proof preserves full current manifests and raw metadata
+ deltas. Only removal of residual compression attributes from uncompressed
+ regular files and addition of provenance on an original root directory are
+ eligible. Every other source field, including directory timestamps, stays
+ exact. Restore and already-restored finalization approvals cannot authorize
+ this operation.
+3. `POST /resume-quarantine` takes the same identifiers and
+ `review: {digest, acceptSuperseded?}`. Explicit supersession acceptance is
+ required when the fresh comparison calls for it. The service recomputes the
+ review and moves only administration, if it is still original, using an
+ exclusive rename. A separately recorded post-move observation and full
+ verification must prove both original inodes are quarantined before the
+ exact reservation is released. Unexpected drift retains all evidence and
+ requires a new review. If the rename completed but publication of its
+ post-move observation was interrupted, a fresh review may prove both
+ original inodes already quarantined; it neither repeats the rename nor
+ fabricates a missing historical observation.
+4. Quarantine completion retains the branch. The existing branch-review and
+ branch-retirement operations require a second fresh approval, now also
+ bound to the recorded quarantine metadata proof. They verify the complete
+ quarantined originals, archive and object closure, current branch tip,
+ ownership, holders and forge state before exact-head branch retirement.
+ Receipt recovery after a durably confirmed deletion verifies the preserved
+ sources again and requires the ref to remain absent.
+
+The bootstrap CLI provides `review-quarantine` and `resume-quarantine` with
+the same request fields, explicit `--install-root`, and a new private `--output`
+record for each invocation. It cannot accept a caller-supplied native proof or
+reuse a restore/finalization approval as quarantine authorization.
+
+Neither resumption nor receipt recovery deletes original directories or
+rewrites their metadata. A lost branch-deletion result remains an uncertainty
+hold; an absent ref alone does not establish that the intended deletion
+completed. An occupied or malformed loose-ref path, unsafe ref parent, or
+unreadable packed refs cannot establish absence for receipt recovery. Archive
+copies, original quarantines, raw preimages, post-move observations, journal
+staging and released reservation evidence remain retained.
Managed checkout creation/adoption/removal, claim binding, the full workspace
preparation through agent registration/spawn, and supported Git API writers
diff --git a/scripts/lib/initialized_checkout_archive.py b/scripts/lib/initialized_checkout_archive.py
index 742814cb1b..1f37623a15 100644
--- a/scripts/lib/initialized_checkout_archive.py
+++ b/scripts/lib/initialized_checkout_archive.py
@@ -32,15 +32,15 @@ def fail(reason):
raise RuntimeError(reason)
-def command(args, env=None, input_data=None):
+def command(args, env=None, input_data=None, expected_returncode=0):
result = subprocess.run(args, capture_output=True, text=True, env=env,
timeout=1200, **({'stdin': subprocess.DEVNULL} if input_data is None else {'input': input_data}))
- if result.returncode:
+ if result.returncode != expected_returncode:
fail('command-failed:' + str(args[0]) + ':' + result.stderr[-1200:])
return result.stdout
-def git(admin, work, *args, objects=None, input_data=None):
+def git(admin, work, *args, objects=None, input_data=None, expected_returncode=0):
env = {k: v for k, v in os.environ.items() if not k.startswith('GIT_')}
env.update(GIT_OPTIONAL_LOCKS='0', GIT_TERMINAL_PROMPT='0',
GIT_CONFIG_NOSYSTEM='1', GIT_CONFIG_GLOBAL=os.devnull,
@@ -54,7 +54,8 @@ def git(admin, work, *args, objects=None, input_data=None):
env['GIT_OBJECT_DIRECTORY'] = str(objects)
return command(['git', '--no-optional-locks', '--git-dir', str(admin),
'--work-tree', str(work), '-c', 'core.fsmonitor=false',
- '-c', 'core.hooksPath=' + os.devnull, *args], env, input_data).strip()
+ '-c', 'core.hooksPath=' + os.devnull, *args], env, input_data,
+ expected_returncode=expected_returncode).strip()
def digest(value):
@@ -923,19 +924,19 @@ def review_metadata_recovery(request):
'changedPaths': len({(row['part'], row['path']) for row in changes})}
-def load_bound_evidence(root, reference, prefix):
+def load_bound_evidence(root, reference, prefix, reason='restored-finalization'):
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')
+ fail(reason + '-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')
+ fail(reason + '-evidence-unsafe')
encoded = source.read(256 * 1024 ** 2 + 1)
evidence = json.loads(encoded)
# All supported publishers use this canonical encoding. Exact equality also
@@ -943,7 +944,7 @@ def load_bound_evidence(root, reference, prefix):
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')
+ fail(reason + '-evidence-changed')
return evidence
@@ -1081,6 +1082,8 @@ def verify_restored_finalization(request):
def verify(request):
if 'restoredFinalization' in request:
fail('restored-finalization-separate-command-required')
+ if 'quarantineResumption' in request:
+ fail('quarantine-resumption-separate-command-required')
root, saved = load_transaction(request)
facts = saved['facts']
recovering = 'metadataRecovery' in request
@@ -1103,31 +1106,279 @@ def verify(request):
**({'metadataRecoveryAccepted': True} if recovering else {})}
-def verify_live_common(root, saved, restoring):
+def verify_common_metadata(saved, mutable_shared):
facts = saved['facts']
common = safe_path(facts['commonGitDir'])
check_admin(common, common=True)
if identity(common) != facts['identity']['common']:
fail('common-store-incarnation-changed')
- mutable_shared = {'objects', 'refs', 'logs', 'packed-refs'} if restoring else set()
for name, expected in facts['sources']['common'].items():
if name not in mutable_shared and manifest(common / name, True) != expected:
fail('common-store-changed:' + name)
if sorted(p.name for p in common.iterdir() if p.name in COMMON_PARTS and p.name not in mutable_shared) != sorted(
name for name in facts['sources']['common'] if name not in mutable_shared):
fail('common-store-layout-changed')
+ return common
+
+
+def verify_live_parent(saved):
+ facts = saved['facts']
+ head = git(Path(facts['commonGitDir']), Path(facts['repoPath']), 'rev-parse', '--verify',
+ 'refs/heads/' + facts['release']['branch'] + '^{commit}')
+ if head != facts['parent']['head']:
+ fail('restore-live-parent-facts-changed')
+
+
+def verify_live_object_closure(root, common):
+ git(root / 'restore/administration', root / 'restore/working',
+ 'fsck', '--full', '--strict', objects=common / 'objects')
+ prove_index_blobs(root / 'restore/administration', root / 'restore/working',
+ objects=common / 'objects')
+
+
+def verify_live_common(root, saved, restoring):
+ common = verify_common_metadata(saved, {'objects', 'refs', 'logs', 'packed-refs'} if restoring else set())
if restoring:
# Other branches may legitimately advance after quarantine. Rollback
# never rewrites shared refs or objects: prove the original private index
# and HEAD still resolve completely against today's shared store.
- head = git(common, Path(facts['repoPath']), 'rev-parse', '--verify',
- 'refs/heads/' + facts['release']['branch'] + '^{commit}')
- if head != facts['parent']['head']:
- fail('restore-live-parent-facts-changed')
- git(root / 'restore/administration', root / 'restore/working',
- 'fsck', '--full', '--strict', objects=common / 'objects')
- prove_index_blobs(root / 'restore/administration', root / 'restore/working',
- objects=common / 'objects')
+ verify_live_parent(saved)
+ verify_live_object_closure(root, common)
+
+
+def require_no_packed_ref(common, ref, oid_length):
+ path = common / 'packed-refs'
+ if not os.path.lexists(path):
+ return
+ try:
+ fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+ except OSError:
+ fail('deleted-branch-packed-refs-unreadable')
+ with os.fdopen(fd, 'rb') as source:
+ before = os.fstat(source.fileno())
+ if not stat.S_ISREG(before.st_mode):
+ fail('deleted-branch-packed-refs-unsafe')
+ budget = 16 * 1024 ** 2
+ if before.st_size > budget:
+ fail('deleted-branch-packed-refs-budget-exceeded')
+ seen, peeled_allowed, total, count = set(), False, 0, 0
+ oid_pattern = rb'[0-9a-fA-F]{' + str(oid_length).encode('ascii') + rb'}'
+ target = os.fsencode(ref)
+ while True:
+ line = source.readline(65537)
+ if not line:
+ break
+ total += len(line)
+ count += 1
+ if len(line) > 65536 or total > budget or count > MAX_FILES:
+ fail('deleted-branch-packed-refs-budget-exceeded')
+ line = line[:-1] if line.endswith(b'\n') else line
+ if line.startswith(b'#'):
+ continue
+ if line.startswith(b'^'):
+ if not peeled_allowed or not re.fullmatch(oid_pattern, line[1:]):
+ fail('deleted-branch-packed-refs-malformed')
+ peeled_allowed = False
+ continue
+ oid, separator, name = line.partition(b' ')
+ components = name.split(b'/')
+ if (not separator or not re.fullmatch(oid_pattern, oid) or not any(value != 48 for value in oid)
+ or not name.startswith(b'refs/') or name.endswith((b'/', b'.'))
+ or b'..' in name or b'@{' in name
+ or any(value < 33 or value == 127 or value in b'~^:?*[\\' for value in name)
+ or any(not part or part.startswith(b'.') or part.endswith(b'.lock') for part in components)
+ or name in seen):
+ fail('deleted-branch-packed-refs-malformed')
+ seen.add(name)
+ peeled_allowed = True
+ if name == target:
+ fail('quarantine-resumption-retired-branch-not-absent')
+ lease = lambda value: (value.st_dev, value.st_ino, value.st_mode, value.st_size,
+ value.st_uid, value.st_gid, value.st_mtime_ns, value.st_ctime_ns)
+ try:
+ unchanged = lease(before) == lease(os.fstat(source.fileno())) == lease(path.lstat())
+ except OSError:
+ unchanged = False
+ if not unchanged:
+ fail('deleted-branch-packed-refs-changed')
+
+
+def verify_deleted_parent(saved, request):
+ facts = saved['facts']
+ receipt = request.get('confirmedDeletion')
+ # The service derives this binding only from its validated durable receipt,
+ # never from ref absence or a deletion intent. This command writes no refs.
+ if (not isinstance(receipt, dict) or set(receipt) != {'journalDigest', 'branch', 'head', 'phase'}
+ or not isinstance(receipt['journalDigest'], str)
+ or not re.fullmatch(r'[0-9a-f]{64}', receipt['journalDigest'])
+ or receipt['branch'] != facts['release']['branch']
+ or receipt['head'] != facts['parent']['head']
+ or receipt['phase'] not in ('branch-retired', 'retired')):
+ fail('quarantine-resumption-confirmed-deletion-required')
+ ref = 'refs/heads/' + facts['release']['branch']
+ def require_no_loose_ref():
+ current = safe_path(facts['commonGitDir'])
+ if identity(current) != facts['identity']['common']:
+ fail('common-store-incarnation-changed')
+ parts = ref.split('/')
+ if any(part in ('', '.', '..') for part in parts):
+ fail('quarantine-resumption-retired-branch-not-absent')
+ for index, part in enumerate(parts):
+ current = current / part
+ try:
+ info = current.lstat()
+ except FileNotFoundError:
+ break
+ # Git can report a malformed loose ref as missing. Preserve and
+ # refuse every occupied leaf and every unsafe parent component.
+ if index == len(parts) - 1 or not stat.S_ISDIR(info.st_mode):
+ fail('quarantine-resumption-retired-branch-not-absent')
+ require_no_loose_ref()
+ require_no_packed_ref(safe_path(facts['commonGitDir']), ref, len(facts['parent']['head']))
+ try:
+ # Also check packed refs. Any status other than Git's exact missing
+ # status holds; filesystem checks separately cover skipped loose refs.
+ git(Path(facts['commonGitDir']), Path(facts['repoPath']),
+ 'show-ref', '--verify', '--quiet', ref, expected_returncode=1)
+ except RuntimeError:
+ fail('quarantine-resumption-retired-branch-not-absent')
+ require_no_packed_ref(safe_path(facts['commonGitDir']), ref, len(facts['parent']['head']))
+ require_no_loose_ref()
+
+
+def verify_deleted_branch(request):
+ if not re.fullmatch(r'[0-9a-f]{64}', request.get('manifestSha256', '')):
+ fail('deleted-branch-manifest-proof-required')
+ _, saved = load_transaction(request)
+ verify_deleted_parent(saved, request)
+ return {'verified': True, 'branchAbsent': True, 'confirmedDeletion': request['confirmedDeletion']}
+
+
+def quarantine_observation(request, retired=False):
+ if 'metadataRecovery' in request or 'restoredFinalization' in request:
+ fail('quarantine-resumption-purpose-mismatch')
+ if not re.fullmatch(r'[0-9a-f]{64}', request.get('manifestSha256', '')):
+ fail('quarantine-resumption-manifest-proof-required')
+ root, saved = load_transaction(request)
+ located, sources = original_sources(root, saved['facts'])
+ if located['working']['state'] != 'quarantine':
+ fail('quarantine-resumption-working-placement-required')
+ if retired and located['administration']['state'] != 'quarantine':
+ fail('quarantine-resumption-completed-placement-required')
+ verify_saved_archive(root, saved)
+ changes = metadata_recovery_changes(root, saved, located, sources)
+ if retired:
+ verify_deleted_parent(saved, request)
+ # Receipt replay restores nothing. The strict standalone archive proof
+ # above retains closure even after legitimate live-store garbage collection.
+ verify_common_metadata(saved, {'objects', 'refs', 'logs', 'packed-refs'})
+ else:
+ verify_live_common(root, saved, restoring=True)
+ if original_sources(root, saved['facts']) != (located, sources):
+ fail('quarantine-resumption-observation-changed')
+ # The full source/archive scans may be long. Pin the ref condition again
+ # before returning the observation to the service's fresh ownership gate.
+ if retired:
+ verify_deleted_parent(saved, request)
+ else:
+ verify_live_parent(saved)
+ return root, saved, located, sources, changes
+
+
+def review_quarantine_resumption(request):
+ root, saved, located, sources, changes = quarantine_observation(request)
+ evidence = {'version': 1, 'purpose': 'resume-initialized-quarantine',
+ 'manifestSha256': request['manifestSha256'],
+ 'transactionIdentity': saved['transactionIdentity'],
+ 'originalFingerprint': saved['facts']['fingerprint'],
+ 'initialPlacements': {label: row['state'] for label, row in located.items()},
+ 'sources': sources, 'changes': changes}
+ stored = immutable_recovery_evidence(root, 'quarantine-resumption-', evidence)
+ return {'quarantineResumption': {'version': 1, 'evidenceFile': stored['file'],
+ 'evidenceSha256': stored['sha256'], 'digest': stored['digest']},
+ 'initialPlacements': evidence['initialPlacements'],
+ 'changeCounts': {
+ 'residualCompressionRemoved': sum(row['attribute'] == 'com.apple.decmpfs' for row in changes),
+ 'rootProvenanceAdded': sum(row['attribute'] == 'com.apple.provenance' for row in changes)},
+ 'changedPaths': len({(row['part'], row['path']) for row in changes})}
+
+
+def verified_quarantine_resumption(request, completed=False, retired=False):
+ accepted = request.get('quarantineResumption')
+ if (not isinstance(accepted, dict)
+ or set(accepted) != {'version', 'evidenceFile', 'evidenceSha256', 'digest'}
+ or accepted['version'] != 1):
+ fail('quarantine-resumption-proof-invalid')
+ root, saved, located, sources, changes = quarantine_observation(request, retired=retired)
+ evidence = load_bound_evidence(root, {'file': accepted['evidenceFile'],
+ 'sha256': accepted['evidenceSha256'],
+ 'digest': accepted['digest']},
+ 'quarantine-resumption-', reason='quarantine-resumption')
+ if (not isinstance(evidence, dict)
+ or set(evidence) != {'version', 'purpose', 'manifestSha256', 'transactionIdentity',
+ 'originalFingerprint', 'initialPlacements', 'sources', 'changes'}
+ or evidence['version'] != 1 or evidence['purpose'] != 'resume-initialized-quarantine'
+ or evidence['manifestSha256'] != request['manifestSha256']
+ or evidence['transactionIdentity'] != saved['transactionIdentity']
+ or evidence['originalFingerprint'] != saved['facts']['fingerprint']
+ or not isinstance(evidence['initialPlacements'], dict)
+ or set(evidence['initialPlacements']) != {'working', 'administration'}
+ or evidence['initialPlacements']['working'] != 'quarantine'
+ or evidence['initialPlacements']['administration'] not in ('original', 'quarantine')):
+ fail('quarantine-resumption-proof-invalid')
+ if sources != evidence['sources'] or changes != evidence['changes']:
+ fail('quarantine-resumption-review-changed')
+ if (evidence['initialPlacements']['administration'] == 'quarantine'
+ and located['administration']['state'] != 'quarantine'):
+ fail('quarantine-resumption-placement-regressed')
+ if completed and located['administration']['state'] != 'quarantine':
+ fail('quarantine-resumption-completed-placement-required')
+ return {'verified': True, 'placements': located, 'fingerprint': saved['facts']['fingerprint'],
+ 'quarantineResumptionAccepted': True,
+ **({'confirmedDeletion': request['confirmedDeletion']} if retired else {})}
+
+
+def verify_quarantine_resumption(request):
+ return verified_quarantine_resumption(request)
+
+
+def verify_completed_quarantine(request):
+ return verified_quarantine_resumption(request, completed=True)
+
+
+def verify_retired_quarantine(request):
+ return verified_quarantine_resumption(request, completed=True, retired=True)
+
+
+def resume_quarantine(request):
+ verified = verify_quarantine_resumption(request)
+ if verified['placements']['administration']['state'] == 'quarantine':
+ return {'moved': False, 'alreadyQuarantined': True, 'part': 'administration',
+ 'direction': 'quarantine', 'placements': verified['placements']}
+ root, saved = load_transaction(request)
+ facts = saved['facts']
+ source, destination = Path(facts['privateGitDir']), root / 'quarantine/administration'
+ safe_path(str(source))
+ safe_path(str(destination.parent))
+ if identity(source) != facts['identity']['administration'] or os.path.lexists(destination):
+ fail('move-lease-or-destination-changed')
+ exclusive_rename(source, destination)
+ fsync_dir(source.parent)
+ fsync_dir(destination.parent)
+ if identity(destination) != facts['identity']['administration']:
+ fail('post-move-identity-uncertain')
+ located, sources = original_sources(root, facts)
+ observation = immutable_recovery_evidence(root, 'quarantine-resumption-postmove-', {
+ 'version': 1, 'purpose': 'resume-initialized-quarantine',
+ 'manifestSha256': request['manifestSha256'],
+ 'acceptedQuarantineResumption': request['quarantineResumption'],
+ 'part': 'administration', 'placements': located, 'sources': sources})
+ try:
+ verify_completed_quarantine(request)
+ except Exception as error:
+ fail('quarantine-resumption-postmove-changed:' + observation['file'] + ':' + str(error))
+ return {'moved': True, 'part': 'administration', 'direction': 'quarantine',
+ 'placements': located, 'postMoveObservation': observation}
def exclusive_rename(source, destination):
@@ -1202,13 +1453,21 @@ def main():
root, saved = load_transaction(request)
result = {'placements': placements(root, saved['facts']), 'fingerprint': saved['facts']['fingerprint']}
elif action in ('preserve', 'verify', 'move', 'review-metadata-recovery',
- 'review-restored-finalization', 'verify-restored-finalization'):
+ 'review-restored-finalization', 'verify-restored-finalization',
+ 'review-quarantine-resumption', 'verify-quarantine-resumption', 'resume-quarantine',
+ 'verify-completed-quarantine', 'verify-retired-quarantine', 'verify-deleted-branch'):
fd = lock_file(transaction(request['transactionDir']), 'backend.lock')
try:
result = {'preserve': preserve, 'verify': verify, 'move': move,
'review-metadata-recovery': review_metadata_recovery,
'review-restored-finalization': review_restored_finalization,
- 'verify-restored-finalization': verify_restored_finalization}[action](request)
+ 'verify-restored-finalization': verify_restored_finalization,
+ 'review-quarantine-resumption': review_quarantine_resumption,
+ 'verify-quarantine-resumption': verify_quarantine_resumption,
+ 'resume-quarantine': resume_quarantine,
+ 'verify-completed-quarantine': verify_completed_quarantine,
+ 'verify-retired-quarantine': verify_retired_quarantine,
+ 'verify-deleted-branch': verify_deleted_branch}[action](request)
finally:
os.close(fd)
else:
diff --git a/scripts/lib/initialized_checkout_archive_test.py b/scripts/lib/initialized_checkout_archive_test.py
index 3bdc853a30..5454a36fec 100644
--- a/scripts/lib/initialized_checkout_archive_test.py
+++ b/scripts/lib/initialized_checkout_archive_test.py
@@ -736,6 +736,245 @@ class NativeArchive(unittest.TestCase):
with self.assertRaisesRegex(RuntimeError, 'restored-finalization-original-placement-required'):
archive.review_restored_finalization(request)
+ def quarantine_resumption_fixture(self):
+ self.metadata_recovery_fixture()
+ reviewed = archive.review_quarantine_resumption(self.request)
+ return {**self.request, 'quarantineResumption': reviewed['quarantineResumption']}
+
+ def test_quarantine_resumption_moves_only_original_administration_and_keeps_purposes_separate(self):
+ self.metadata_recovery_fixture()
+ baseline = (self.txn / 'manifest.json').read_bytes()
+ def process(request):
+ result = subprocess.run([sys.executable, str(Path(archive.__file__))],
+ input=json.dumps(request) + '\n', env=self.env,
+ capture_output=True, text=True, check=True)
+ return json.loads(result.stdout)
+ reviewed = process({**self.request, 'command': 'review-quarantine-resumption'})
+ self.assertEqual(reviewed['initialPlacements'], {'working': 'quarantine', 'administration': 'original'})
+ self.assertEqual(reviewed['changeCounts'], {'residualCompressionRemoved': 1, 'rootProvenanceAdded': 0})
+ request = {**self.request, 'quarantineResumption': reviewed['quarantineResumption']}
+ evidence = json.loads((self.txn / reviewed['quarantineResumption']['evidenceFile']).read_text())
+ self.assertEqual(evidence['purpose'], 'resume-initialized-quarantine')
+ self.assertEqual(archive.base64.b64decode(evidence['changes'][0]['beforeBase64']), b'fixture-residual')
+ self.assertTrue(process({**request, 'command': 'verify-quarantine-resumption'})['verified'])
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-completed-placement-required'):
+ archive.verify_completed_quarantine(request)
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-separate-command-required'):
+ archive.move({**request, 'part': 'administration', 'direction': 'quarantine'})
+ restore = archive.review_metadata_recovery(self.request)['metadataRecovery']
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-evidence-invalid'):
+ archive.resume_quarantine({**request, 'quarantineResumption': restore})
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-purpose-mismatch'):
+ archive.resume_quarantine({**request, 'restoredFinalization': restore})
+ before = archive.original_sources(self.txn, archive.load_transaction(request)[1]['facts'])[1]
+ moved = process({**request, 'command': 'resume-quarantine'})
+ self.assertTrue(moved['moved'])
+ self.assertEqual(moved['part'], 'administration')
+ observation = moved['postMoveObservation']
+ self.assertEqual(archive.sha(self.txn / observation['file']), observation['sha256'])
+ self.assertTrue(process({**request, 'command': 'verify-completed-quarantine'})['verified'])
+ with patch.object(archive, 'exclusive_rename', side_effect=AssertionError('must not move twice')):
+ self.assertTrue(archive.resume_quarantine(request)['alreadyQuarantined'])
+ after = archive.original_sources(self.txn, archive.load_transaction(request)[1]['facts'])[1]
+ self.assertEqual(after, before)
+ self.assertFalse(self.work.exists())
+ self.assertEqual((self.txn / 'manifest.json').read_bytes(), baseline)
+
+ def test_quarantine_resumption_recovers_postmove_evidence_interruption_without_replaying_rename(self):
+ request = self.quarantine_resumption_fixture()
+ write = archive.private_json
+ stages = []
+ def interrupted(path, evidence):
+ if path.name.startswith('.quarantine-resumption-postmove-'):
+ with os.fdopen(os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), 'wb') as out:
+ out.write(b'{"interrupted":')
+ out.flush()
+ os.fsync(out.fileno())
+ stages.append(path)
+ raise RuntimeError('fixture evidence publication interrupted')
+ return write(path, evidence)
+ with patch.object(archive, 'private_json', interrupted):
+ with self.assertRaisesRegex(RuntimeError, 'fixture evidence publication interrupted'):
+ archive.resume_quarantine(request)
+ self.assertTrue((self.txn / 'quarantine/administration').exists())
+ self.assertFalse(self.work.exists())
+ self.assertEqual(list(self.txn.glob('quarantine-resumption-postmove-*.json')), [])
+ reviewed = archive.review_quarantine_resumption(self.request)
+ self.assertEqual(reviewed['initialPlacements'], {'working': 'quarantine', 'administration': 'quarantine'})
+ accepted = {**self.request, 'quarantineResumption': reviewed['quarantineResumption']}
+ self.assertNotEqual(accepted['quarantineResumption']['digest'], request['quarantineResumption']['digest'])
+ with patch.object(archive, 'exclusive_rename', side_effect=AssertionError('no repeat rename')):
+ self.assertTrue(archive.resume_quarantine(accepted)['alreadyQuarantined'])
+ self.assertTrue(archive.verify_completed_quarantine(accepted)['verified'])
+ self.assertEqual(stages[0].read_bytes(), b'{"interrupted":')
+
+ def test_quarantine_resumption_preserves_new_postmove_delta_and_requires_new_approval(self):
+ request = self.quarantine_resumption_fixture()
+ attrs = archive.raw_xattrs
+ def moved_provenance(path):
+ values = attrs(path)
+ # Model an OS-generated attribute on the moved disposable directory.
+ return {**values, 'com.apple.provenance': b'postmove provenance'} if path == self.txn / 'quarantine/administration' else values
+ with patch.object(archive, 'raw_xattrs', moved_provenance):
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-postmove-changed:'):
+ archive.resume_quarantine(request)
+ observations = list(self.txn.glob('quarantine-resumption-postmove-*.json'))
+ self.assertEqual(len(observations), 1)
+ observed = json.loads(observations[0].read_text())
+ self.assertEqual(observed['acceptedQuarantineResumption'], request['quarantineResumption'])
+ self.assertEqual(observed['placements']['administration']['state'], 'quarantine')
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-review-changed'):
+ archive.verify_completed_quarantine(request)
+ reviewed = archive.review_quarantine_resumption(self.request)
+ self.assertEqual(reviewed['changeCounts']['rootProvenanceAdded'], 1)
+ accepted = {**self.request, 'quarantineResumption': reviewed['quarantineResumption']}
+ with patch.object(archive, 'exclusive_rename', side_effect=AssertionError('no repeat rename')):
+ self.assertTrue(archive.resume_quarantine(accepted)['alreadyQuarantined'])
+ self.assertTrue(archive.verify_completed_quarantine(accepted)['verified'])
+ self.assertFalse(self.work.exists())
+
+ def test_quarantine_resumption_refuses_nonwhitelisted_drift_and_stale_source_approval(self):
+ request = self.quarantine_resumption_fixture()
+ original_manifest = archive.manifest
+ mutations = {
+ 'directory mtime': ('', lambda row: row.update(mtimeNs=row['mtimeNs'] + 1)),
+ 'file bytes': ('base.txt', lambda row: row.update(sha256='0' * 64)),
+ 'file mtime': ('base.txt', lambda row: row.update(mtimeNs=row['mtimeNs'] + 1)),
+ 'compression flag': ('base.txt', lambda row: row.update(flags=row['flags'] | 0x20)),
+ 'security attribute': ('base.txt', lambda row: row['xattrs'].update({'com.apple.quarantine': '0' * 64})),
+ 'unknown attribute': ('base.txt', lambda row: row['xattrs'].update({'fixture.unknown': '0' * 64})),
+ }
+ for name, (relative, mutation) in mutations.items():
+ def observe(path, reject_links=False):
+ rows = original_manifest(path, reject_links)
+ if path == self.txn / 'quarantine/working':
+ rows = copy.deepcopy(rows)
+ mutation(next(row for row in rows if row['path'] == relative))
+ return rows
+ with self.subTest(change=name), patch.object(archive, 'manifest', observe):
+ with self.assertRaisesRegex(RuntimeError, 'metadata-recovery-source-content-or-identity-changed|metadata-recovery-unsupported-attribute-change'):
+ archive.review_quarantine_resumption(self.request)
+ # Exact original bytes reappearing cannot silently reuse an approval of
+ # their absence, even though a fresh baseline-exact review could pass.
+ target = self.txn / 'quarantine/working/base.txt'
+ subprocess.run(['/usr/bin/xattr', '-w', 'com.apple.decmpfs', 'fixture-residual', str(target)], check=True)
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-review-changed'):
+ archive.resume_quarantine(request)
+ subprocess.run(['/usr/bin/xattr', '-d', 'com.apple.decmpfs', str(target)], check=True)
+ evidence_path = self.txn / request['quarantineResumption']['evidenceFile']
+ evidence_path.write_bytes(evidence_path.read_bytes() + b' ')
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-evidence-changed'):
+ archive.resume_quarantine(request)
+ self.assertFalse((self.txn / 'quarantine/administration').exists())
+
+ def test_retired_quarantine_proves_full_sources_and_receipt_phase_after_branch_deletion(self):
+ request = self.quarantine_resumption_fixture()
+ archive.resume_quarantine(request)
+ receipt = {'journalDigest': 'a' * 64, 'branch': self.request['release']['branch'],
+ 'head': self.request['release']['head'], 'phase': 'branch-retired'}
+ retired = {**request, 'confirmedDeletion': receipt}
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-retired-branch-not-absent'):
+ archive.verify_retired_quarantine(retired)
+ common = Path(archive.load_transaction(request)[1]['facts']['commonGitDir'])
+ config_before = archive.manifest(common / 'config')
+ # Match production's exact-old-OID local receiver. `git branch -d`
+ # rewrites config even without a matching stanza and correctly trips
+ # the immutable common-store guard; receiver deletion does not.
+ ref = 'refs/heads/' + self.request['release']['branch']
+ self.git(self.repo, 'push', '--force-with-lease=' + ref + ':' + self.request['release']['head'],
+ self.repo.as_uri(), ':' + ref)
+ self.assertEqual(archive.manifest(common / 'config'), config_before)
+ with self.assertRaises(RuntimeError):
+ archive.verify_completed_quarantine(request)
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-confirmed-deletion-required'):
+ archive.verify_retired_quarantine({**retired, 'confirmedDeletion': {**receipt, 'phase': 'retire-branch-intent'}})
+ result = subprocess.run([sys.executable, str(Path(archive.__file__))],
+ input=json.dumps({**retired, 'command': 'verify-retired-quarantine'}) + '\n',
+ env=self.env, capture_output=True, text=True)
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ verified = json.loads(result.stdout)
+ self.assertTrue(verified['verified'])
+ self.assertEqual(verified['confirmedDeletion'], receipt)
+ self.assertTrue(archive.verify_retired_quarantine(
+ {**retired, 'confirmedDeletion': {**receipt, 'phase': 'retired'}})['verified'])
+ self.assertTrue(archive.verify({**self.request, 'mode': 'standalone'})['standalone'])
+ # Only this disposable repository is pruned. Private index/ref objects
+ # no longer have live roots after quarantine but remain in the archive.
+ self.git(self.repo, 'prune', '--expire=now')
+ with self.assertRaises(RuntimeError):
+ archive.verify_live_object_closure(self.txn, common)
+ self.assertTrue(archive.verify_retired_quarantine(retired)['verified'])
+ # A damaged ref in this fixture must not be mistaken for absence by an
+ # enumeration command that skips broken entries. Keep the bytes intact.
+ broken_ref = common / 'refs/heads' / self.request['release']['branch']
+ broken_ref.parent.mkdir(parents=True, exist_ok=True)
+ broken_ref.write_text('invalid fixture ref\n')
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-retired-branch-not-absent'):
+ archive.verify_retired_quarantine(retired)
+ self.assertEqual(broken_ref.read_text(), 'invalid fixture ref\n')
+ broken_ref.unlink()
+ os.symlink(self.scratch / 'absent-ref-target', broken_ref)
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-retired-branch-not-absent'):
+ archive.verify_deleted_branch(retired)
+ self.assertTrue(broken_ref.is_symlink())
+ broken_ref.unlink()
+ broken_ref.mkdir()
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-retired-branch-not-absent'):
+ archive.verify_deleted_branch(retired)
+ broken_ref.rmdir()
+ saved_parent = self.scratch / 'saved-fixture-ref-parent'
+ broken_ref.parent.rename(saved_parent)
+ os.symlink(saved_parent, broken_ref.parent)
+ with self.assertRaisesRegex(RuntimeError, 'quarantine-resumption-retired-branch-not-absent'):
+ archive.verify_deleted_branch(retired)
+ broken_ref.parent.unlink()
+ saved_parent.rename(broken_ref.parent)
+
+ packed = common / 'packed-refs'
+ prior_packed = packed.read_bytes() if packed.exists() else None
+ head = receipt['head'].encode('ascii')
+ target = ('refs/heads/' + receipt['branch']).encode('ascii')
+ for content in (head + b' ' + target + b' extra\n',
+ b'invalid ' + target + b'\n',
+ b'0' * len(head) + b' ' + target + b'\n',
+ head + b' ' + target + b'\n'):
+ packed.write_bytes(content)
+ with self.subTest(packed=content), self.assertRaisesRegex(RuntimeError, 'deleted-branch-packed-refs-malformed|quarantine-resumption-retired-branch-not-absent'):
+ archive.verify_deleted_branch(retired)
+ self.assertEqual(packed.read_bytes(), content)
+ packed.write_bytes(b'# pack-refs with: peeled \n' + head + b' refs/custom/fixture\n'
+ + head + ' refs/notes/caf\u00e9\n'.encode('utf-8')
+ + head + b' refs/tags/fixture\n^' + head + b'\n')
+ result = subprocess.run([sys.executable, str(Path(archive.__file__))],
+ input=json.dumps({**retired, 'command': 'verify-deleted-branch'}) + '\n',
+ env=self.env, capture_output=True, text=True)
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertTrue(json.loads(result.stdout)['branchAbsent'])
+ if prior_packed is None:
+ packed.unlink()
+ else:
+ packed.write_bytes(prior_packed)
+ real_identity = archive.identity
+ def changed_common(path):
+ value = real_identity(path)
+ return {**value, 'ino': value['ino'] + 1} if path == common else value
+ with patch.object(archive, 'identity', changed_common):
+ with self.assertRaisesRegex(RuntimeError, 'common-store-incarnation-changed'):
+ archive.verify_deleted_branch(retired)
+ real_git, replaced = archive.git, [False]
+ def replace_after_read(*args, **kwargs):
+ result = real_git(*args, **kwargs)
+ replaced[0] = True
+ return result
+ def raced_identity(path):
+ return changed_common(path) if replaced[0] else real_identity(path)
+ with patch.object(archive, 'git', replace_after_read), patch.object(archive, 'identity', raced_identity):
+ with self.assertRaisesRegex(RuntimeError, 'common-store-incarnation-changed'):
+ archive.verify_deleted_branch(retired)
+ (self.txn / 'quarantine/working/base.txt').write_text('changed after deletion\n')
+ with self.assertRaisesRegex(RuntimeError, 'metadata-recovery-source-content-or-identity-changed'):
+ archive.verify_retired_quarantine(retired)
+
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.js
index 5c6813f75e..6907ec2268 100644
--- a/scripts/recover-initialized-checkout.js
+++ b/scripts/recover-initialized-checkout.js
@@ -1,11 +1,13 @@
#!/usr/bin/env node
/**
- * Restore-only bootstrap for an interrupted initialized checkout transaction.
+ * Guarded bootstrap for an interrupted initialized checkout transaction.
* 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|review-finalization|finalize request.json \
+ * node scripts/recover-initialized-checkout.js <action> request.json \
* --install-root /absolute/install --output /absolute/new-private-record.jsonl
+ * Actions: review, restore, review-finalization, finalize,
+ * review-quarantine, resume-quarantine.
*
* Output is an exclusive 0600 JSONL journal: a durable pending intent precedes
* the service call; a completed response is appended. A lone pending line means
@@ -28,6 +30,8 @@ const ACTIONS = {
restore: { method: 'restoreMetadata', acceptedReview: true },
'review-finalization': { method: 'reviewRestoredFinalization', acceptedReview: false },
finalize: { method: 'finalizeRestored', acceptedReview: true },
+ 'review-quarantine': { method: 'reviewQuarantineResumption', acceptedReview: false },
+ 'resume-quarantine': { method: 'resumeQuarantine', acceptedReview: true, supersession: true },
};
const fail = code => { throw Object.assign(new Error(code), { recoveryCode: code }); };
const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -66,11 +70,15 @@ async function readJson(path, limit) {
function validateRequest(action, request) {
const acceptedReview = ACTIONS[action].acceptedReview;
const keys = ['appId', 'transactionId', 'journalDigest', ...(acceptedReview ? ['review'] : [])];
+ const hasSupersession = ACTIONS[action].supersession && object(request?.review)
+ && Object.hasOwn(request.review, 'acceptSuperseded');
+ const reviewKeys = ['digest', ...(hasSupersession ? ['acceptSuperseded'] : [])];
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)
- || (acceptedReview && (!exactKeys(request.review, ['digest'])
- || typeof request.review.digest !== 'string' || !HASH.test(request.review.digest)))) fail('recovery-request-invalid');
+ || (acceptedReview && (!exactKeys(request.review, reviewKeys)
+ || typeof request.review.digest !== 'string' || !HASH.test(request.review.digest)
+ || (hasSupersession && typeof request.review.acceptSuperseded !== 'boolean')))) fail('recovery-request-invalid');
return request;
}
diff --git a/scripts/recover-initialized-checkout.test.js b/scripts/recover-initialized-checkout.test.js
index f2e71d6403..06192032e9 100644
--- a/scripts/recover-initialized-checkout.test.js
+++ b/scripts/recover-initialized-checkout.test.js
@@ -18,7 +18,8 @@ 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, ...(['restore', 'finalize'].includes(action) ? { review: { digest: 'b'.repeat(64) } } : {}) };
+ const body = { ...request, ...(['restore', 'finalize', 'resume-quarantine'].includes(action)
+ ? { review: { digest: 'b'.repeat(64), ...(action === 'resume-quarantine' ? { acceptSuperseded: true } : {}) } } : {}) };
const input = join(root, 'request.json');
const output = join(root, 'result.jsonl');
await writeFile(input, JSON.stringify(body));
@@ -26,12 +27,13 @@ async function fixture(action = 'review') {
}
describe('initialized checkout recovery CLI', () => {
- it.each(['review', 'restore', 'review-finalization', 'finalize'])('pins the existing install, journals intent first, and invokes only guarded %s', async action => {
+ it.each(['review', 'restore', 'review-finalization', 'finalize', 'review-quarantine', 'resume-quarantine'])('pins the existing install, journals intent first, and invokes only guarded %s', async action => {
const f = await fixture(action);
const before = process.env.PORTOS_DATA_ROOT;
const stdout = vi.fn();
const method = { review: 'reviewMetadataRestore', restore: 'restoreMetadata',
- 'review-finalization': 'reviewRestoredFinalization', finalize: 'finalizeRestored' }[action];
+ 'review-finalization': 'reviewRestoredFinalization', finalize: 'finalizeRestored',
+ 'review-quarantine': 'reviewQuarantineResumption', 'resume-quarantine': 'resumeQuarantine' }[action];
const load = vi.fn(async (deps, root) => {
expect(root).toBe(f.root);
expect(process.env.PORTOS_DATA_ROOT).toBe(f.root);
@@ -64,6 +66,19 @@ describe('initialized checkout recovery CLI', () => {
await expect(stat(f.output)).rejects.toMatchObject({ code: 'ENOENT' });
});
+ it.each(['missing-review', 'nonboolean-supersession', 'caller-proof'])('refuses quarantine %s before loading the service', async change => {
+ const f = await fixture('resume-quarantine');
+ const body = { ...f.body };
+ if (change === 'missing-review') delete body.review;
+ if (change === 'nonboolean-supersession') body.review.acceptSuperseded = 'true';
+ if (change === 'caller-proof') body.review.quarantineResumption = { digest: 'c'.repeat(64) };
+ await writeFile(f.input, JSON.stringify(body));
+ 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.js
index 641114cc72..d5546fb99d 100644
--- a/server/lib/hostControlRoutes.js
+++ b/server/lib/hostControlRoutes.js
@@ -424,6 +424,8 @@ export const HOST_CONTROL_ROUTES = Object.freeze([
'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/review-quarantine-resumption',
+ 'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/resume-quarantine',
'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.js
index 68d4614666..9cb7a33912 100644
--- a/server/lib/validation.js
+++ b/server/lib/validation.js
@@ -2886,6 +2886,9 @@ export const initializedCheckoutMetadataRestoreSchema = initializedCheckoutResto
review: z.object({ digest: z.string().regex(/^[a-f0-9]{64}$/) }).strict(),
}).strict();
export const initializedCheckoutFinalizationSchema = initializedCheckoutMetadataRestoreSchema;
+export const initializedCheckoutQuarantineResumptionSchema = initializedCheckoutRestoreSchema.extend({
+ review: z.object({ digest: z.string().regex(/^[a-f0-9]{64}$/), acceptSuperseded: z.boolean().optional() }).strict(),
+}).strict();
// 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.js
index c170107d3d..87a2efae9d 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, initializedCheckoutFinalizationSchema } from '../lib/validation.js';
+import { sanitizeTaskMetadata, taskDataInputsSchema, validateRequest, parsePagination, cosScheduleTargetBodySchema, heldCheckoutRetireBodySchema, heldCheckoutReviewBodySchema, initializedCheckoutRetireBodySchema, initializedCheckoutTransactionSchema, initializedCheckoutRestoreSchema, initializedCheckoutBranchRetireSchema, initializedCheckoutMetadataRestoreSchema, initializedCheckoutFinalizationSchema, initializedCheckoutQuarantineResumptionSchema } 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';
@@ -370,6 +370,20 @@ router.post('/schedule/branch-reconcile/initialized-checkouts/finalize-restored'
res.status(result.ok ? 200 : 409).json(result);
}));
+router.post('/schedule/branch-reconcile/initialized-checkouts/review-quarantine-resumption', asyncHandler(async (req, res) => {
+ const input = validateRequest(initializedCheckoutRestoreSchema, req.body);
+ const { reviewInitializedCheckoutQuarantineResumption } = await import('../services/initializedCheckoutRecovery.js');
+ const result = await reviewInitializedCheckoutQuarantineResumption(input);
+ res.status(result.ok ? 200 : 409).json(result);
+}));
+
+router.post('/schedule/branch-reconcile/initialized-checkouts/resume-quarantine', asyncHandler(async (req, res) => {
+ const input = validateRequest(initializedCheckoutQuarantineResumptionSchema, req.body);
+ const { resumeInitializedCheckoutQuarantine } = await import('../services/initializedCheckoutRecovery.js');
+ const result = await resumeInitializedCheckoutQuarantine(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.js
index df9102ab99..fd925bad02 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(), reviewInitializedCheckoutRestoredFinalization: vi.fn(), finalizeInitializedCheckoutRestored: 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(), reviewInitializedCheckoutQuarantineResumption: vi.fn(), resumeInitializedCheckoutQuarantine: vi.fn() }));
vi.mock('../services/initializedCheckoutRecovery.js', () => initialized);
vi.mock('../services/taskSchedule.js', () => ({
@@ -600,6 +600,23 @@ describe('CoS Schedule Routes', () => {
});
});
+ it('validates purpose-specific quarantine review and resumption without caller-supplied native proof', async () => {
+ const base = '/api/cos/schedule/branch-reconcile/initialized-checkouts';
+ const input = { appId: 'app', transactionId: 'c96ce286-b5f3-49c3-8e51-f8c8e1b8bd3f', journalDigest: 'a'.repeat(64) };
+ initialized.reviewInitializedCheckoutQuarantineResumption.mockResolvedValue({ ok: true, review: { digest: 'b'.repeat(64) } });
+ expect((await request(app).post(`${base}/review-quarantine-resumption`).send(input)).status).toBe(200);
+ expect(initialized.reviewInitializedCheckoutQuarantineResumption).toHaveBeenCalledWith(input);
+ expect((await request(app).post(`${base}/resume-quarantine`).send(input)).status).toBe(400);
+ const approved = { ...input, review: { digest: 'b'.repeat(64), acceptSuperseded: true } };
+ for (const extra of [{ quarantineResumption: {} }, { direction: 'restore' }, { prUrl: 'https://example.com/pr' }]) {
+ expect((await request(app).post(`${base}/resume-quarantine`).send({ ...approved, ...extra })).status).toBe(400);
+ }
+ expect((await request(app).post(`${base}/resume-quarantine`).send({ ...approved, review: { ...approved.review, ignoreMtime: true } })).status).toBe(400);
+ initialized.resumeInitializedCheckoutQuarantine.mockResolvedValue({ ok: false, reason: 'retirement-review-changed' });
+ expect((await request(app).post(`${base}/resume-quarantine`).send(approved)).status).toBe(409);
+ expect(initialized.resumeInitializedCheckoutQuarantine).toHaveBeenCalledWith(approved);
+ });
+
describe('POST /api/cos/schedule/templates', () => {
it('should add a template task', async () => {
taskSchedule.addTemplateTask.mockResolvedValue({ id: 'tmpl-1', name: 'Review' });
diff --git a/server/services/initializedCheckoutRecovery.js b/server/services/initializedCheckoutRecovery.js
index 313b95ac0f..0c44ef81c3 100644
--- a/server/services/initializedCheckoutRecovery.js
+++ b/server/services/initializedCheckoutRecovery.js
@@ -240,11 +240,26 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
if (state.appId !== input.appId || state.repoPath !== ctx.repoPath) fail('retirement-transaction-app-mismatch');
return { directory, state, ctx };
};
+ const quarantineProofInput = ({ directory, state, ctx }) => {
+ const accepted = state.quarantineResumptionReview;
+ const unsigned = { ...accepted };
+ delete unsigned.digest;
+ if (!accepted || accepted.digest !== hash(unsigned) || accepted.mode !== 'resume-initialized-quarantine'
+ || accepted.transactionId !== state.id || accepted.repoPath !== ctx.repoPath
+ || !sameRelease(accepted.release, state.release) || !state.proof?.manifestSha256
+ || !accepted.quarantineResumption) fail('quarantine-resumption-evidence-missing');
+ return { transactionDir: directory, manifestSha256: state.proof.manifestSha256,
+ quarantineResumption: accepted.quarantineResumption };
+ };
const branchReview = async ({ directory, state, ctx }) => {
- if (state.phase !== 'quarantined' || state.branchDeleted) fail('retirement-branch-phase-not-ready');
+ const transitioned = state.phase === 'quarantined-with-metadata-transitions';
+ if ((!transitioned && 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', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, mode: 'restore' });
- if (['working', 'administration'].some(part => proof.placements?.[part]?.state !== 'quarantine')) fail('retirement-originals-not-quarantined');
+ const proof = await native(transitioned
+ ? { command: 'verify-completed-quarantine', ...quarantineProofInput({ directory, state, ctx }) }
+ : { command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, mode: 'restore' });
+ if ((transitioned && (proof.verified !== true || proof.quarantineResumptionAccepted !== true))
+ || ['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');
const runGit = deps.execGit || execGit;
@@ -252,15 +267,24 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
if (head.exitCode !== 0 || head.stdout.trim() !== state.release.head) fail('branch-ref-changed');
const facts = await forge(ctx, state.release, state.review.forge.prUrl);
const base = await comparison(ctx, state.release, facts.prUrl, state.review.snapshot, policy, facts);
+ if (JSON.stringify(await ensureOwner(ctx, state.release, false)) !== JSON.stringify(policy)) fail('retirement-evidence-changed');
const evidence = { ...base, mode: 'quarantined-branch', transactionId: state.id,
- journalDigest: hash(state), archiveFingerprint: proof.fingerprint };
+ journalDigest: hash(state), archiveFingerprint: proof.fingerprint,
+ ...(transitioned ? { quarantineResumptionReview: state.quarantineResumptionReview,
+ quarantineResumptionObservation: state.quarantineResumptionObservation ?? null } : {}) };
delete evidence.digest;
return { digest: hash(evidence), ...evidence };
};
const reviewBranch = input => fenced(async () => {
- const bound = await loadBoundTransaction(input);
- return (await admission()).withCheckoutPublication(bound.ctx.repoPath,
- async () => ({ ok: true, review: await branchReview(bound) }));
+ const executor = await native({ command: 'lock', transactionDir: location(input.transactionId) }, { keepOpen: true });
+ try {
+ const bound = await loadBoundTransaction(input);
+ return await (await admission()).withCheckoutPublication(bound.ctx.repoPath, async () => {
+ executor.assertHeld();
+ if (hash(await readJournal(bound.directory)) !== hash(bound.state)) fail('retirement-journal-changed');
+ return { ok: true, review: await branchReview(bound) };
+ });
+ } finally { await executor.release(); }
}).catch(error => ({ ok: false, reason: error.message }));
// A receiver success was fsynced before recording the schedule receipt. Replay
// only those completed phases: this never issues a Git mutation or recreates
@@ -273,18 +297,30 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
const verify = async () => {
executor.assertHeld();
await ensureOwner(ctx, state.release, false);
- 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');
+ let placement;
+ if (state.quarantineResumptionReview) {
+ placement = await native({ command: 'verify-retired-quarantine', ...quarantineProofInput({ directory, state, ctx }),
+ confirmedDeletion: { journalDigest: hash(state), branch: state.release.branch, head: state.release.head, phase: state.phase } });
+ } else {
+ await native({ command: 'verify', manifestSha256: state.proof?.manifestSha256, transactionDir: directory, mode: 'standalone' });
+ placement = await native({ command: 'status', manifestSha256: state.proof?.manifestSha256, transactionDir: directory });
+ }
+ if ((state.quarantineResumptionReview && (placement.verified !== true || placement.quarantineResumptionAccepted !== true))
+ || ['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');
- const result = await (deps.execGit || execGit)(['show-ref', '--verify', '--quiet', `refs/heads/${state.release.branch}`], ctx.repoPath, { ignoreExitCode: true });
- if (result.exitCode !== 1) fail('retirement-deleted-branch-not-absent');
+ const absence = await native({ command: 'verify-deleted-branch', transactionDir: directory,
+ manifestSha256: state.proof?.manifestSha256, confirmedDeletion: { journalDigest: hash(state),
+ branch: state.release.branch, head: state.release.head, phase: state.phase } });
+ if (absence.verified !== true || absence.branchAbsent !== true) fail('retirement-deleted-branch-not-absent');
+ await ensureOwner(ctx, state.release, false);
+ executor.assertHeld();
};
const reservation = await gate.readCheckoutReservation(ctx.repoPath, state.id).catch(error => {
if (error.code === 'ENOENT' && state.phase === 'retired' && state.receiptRecorded === true) return null;
throw error;
});
+ if (reservation && JSON.stringify(reservation) !== JSON.stringify(state.reservation)) fail('retirement-reservation-changed');
const finish = async () => {
await verify();
if (state.phase === 'branch-retired') {
@@ -308,12 +344,13 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
// An interrupted receiver may have completed without its journal result.
// It is an explicit uncertainty hold, never permission to recreate a ref.
if (state.phase === 'branch-retirement-intent') fail('retirement-branch-deletion-uncertain');
- const current = await branchReview(bound);
- assertReview(current, input.review);
const executor = await native({ command: 'lock', transactionDir: directory }, { keepOpen: true });
const gate = await admission();
try {
if (hash(await readJournal(directory)) !== hash(state)) fail('retirement-journal-changed');
+ executor.assertHeld();
+ const current = await branchReview(bound);
+ assertReview(current, input.review);
const reservation = await gate.reserveCheckoutRetirement(ctx.repoPath, state.id);
return await gate.withCheckoutReservation(reservation, async () => {
assertReview(await branchReview(bound), input.review);
@@ -360,6 +397,8 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
...(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 } : {}),
+ ...(state.quarantineResumptionReview ? { quarantineResumption: state.quarantineResumptionReview.quarantineResumption,
+ quarantineResumptionComplete: state.phase === 'quarantined-with-metadata-transitions' } : {}),
...(state.metadataRestoreReview ? { metadataRecovery: state.metadataRestoreReview.metadataRecovery,
metadataChangeCounts: state.metadataRestoreReview.changeCounts,
metadataRestored: state.phase === 'restored-with-metadata-transitions' } : {}),
@@ -482,6 +521,11 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
const restoreMetadata = input => withMetadataRestore(input, async (bound, { executor, gate, reservation }) => {
const current = await metadataReview(bound);
if (current.digest !== input.review?.digest) fail('metadata-recovery-review-changed');
+ if (current.initialPlacements.working === 'original' && current.initialPlacements.administration === 'original'
+ && bound.state.metadataRestoreReview && bound.state.metadataRestoreObservations?.some(row => row.part === 'working' && row.proof)) {
+ restoredFinalizationInputs(bound);
+ fail('metadata-recovery-already-restored-use-finalization');
+ }
const { directory } = bound;
let state = await appendStep(directory, bound.state, 'metadata-restore-approved',
{ metadataRestoreReview: current, metadataRestoreObservations: [], reservation });
@@ -506,6 +550,74 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
return { ok: true, transactionId: state.id, phase: state.phase, restored: true, archivesRetained: true,
metadataTransitionsPreserved: true, metadataRecovery: current.metadataRecovery, archiveDir: directory };
});
+ const quarantineSafety = async (bound, administrationQuarantined = false) => {
+ const { ctx, state } = bound;
+ const policy = await metadataRestoreSafety(bound);
+ if (administrationQuarantined) {
+ 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');
+ }
+ const facts = await forge(ctx, state.release, state.review.forge.prUrl);
+ const evidence = await comparison(ctx, state.release, facts.prUrl, state.review.snapshot, policy, facts);
+ const result = { ...evidence, policy, forge: facts };
+ delete result.digest;
+ return result;
+ };
+ const quarantineReview = async (bound, reservation) => {
+ const { state, directory, ctx } = bound;
+ const allowed = ['quarantine-working-intent', 'quarantined-working', 'quarantine-administration-intent',
+ 'quarantined-administration', 'quarantine-resumption-approved', 'quarantine-resumption-administration-intent',
+ 'quarantine-resumption-administration-complete', 'quarantined-with-metadata-transitions'];
+ if (!allowed.includes(state.phase) || state.branchDeleted || !state.proof?.manifestSha256) fail('quarantine-resumption-phase-not-ready');
+ if (JSON.stringify(reservation) !== JSON.stringify(state.reservation)) fail('quarantine-resumption-reservation-changed');
+ const before = await quarantineSafety(bound);
+ const proof = await native({ command: 'review-quarantine-resumption', transactionDir: directory,
+ manifestSha256: state.proof.manifestSha256 });
+ if (proof.initialPlacements?.working !== 'quarantine'
+ || !['original', 'quarantine'].includes(proof.initialPlacements?.administration)) fail('quarantine-resumption-placement-not-ready');
+ const current = await quarantineSafety(bound, proof.initialPlacements.administration === 'quarantine');
+ if (JSON.stringify(current) !== JSON.stringify(before)) fail('retirement-evidence-changed');
+ const evidence = { ...current, safetyEvidence: current, version: 1, mode: 'resume-initialized-quarantine', transactionId: state.id,
+ repoPath: ctx.repoPath, release: state.release, journalDigest: hash(state), phase: state.phase, reservation,
+ quarantineResumption: proof.quarantineResumption, initialPlacements: proof.initialPlacements,
+ changeCounts: proof.changeCounts, changedPaths: proof.changedPaths };
+ return { digest: hash(evidence), ...evidence };
+ };
+ const reviewQuarantineResumption = input => withMetadataRestore(input,
+ async (bound, { reservation }) => ({ ok: true, review: await quarantineReview(bound, reservation) }));
+ const resumeQuarantine = input => withMetadataRestore(input, async (bound, { executor, gate, reservation }) => {
+ const current = await quarantineReview(bound, reservation);
+ assertReview(current, input.review);
+ const { directory } = bound;
+ let state = await appendStep(directory, bound.state, 'quarantine-resumption-approved',
+ { quarantineResumptionReview: current, quarantineResumptionObservation: null });
+ const proof = quarantineProofInput({ ...bound, state });
+ const assertSafety = async administrationQuarantined => {
+ const fresh = await quarantineSafety({ ...bound, state }, administrationQuarantined);
+ if (JSON.stringify(fresh) !== JSON.stringify(current.safetyEvidence)) fail('retirement-evidence-changed');
+ executor.assertHeld();
+ };
+ await assertSafety(current.initialPlacements.administration === 'quarantine');
+ await native({ command: 'verify-quarantine-resumption', ...proof });
+ if (current.initialPlacements.administration === 'original') {
+ await assertSafety(false);
+ state = await appendStep(directory, state, 'quarantine-resumption-administration-intent');
+ const moved = await native({ command: 'resume-quarantine', ...proof });
+ if (moved.moved !== true || !moved.postMoveObservation?.file
+ || !/^[a-f0-9]{64}$/.test(moved.postMoveObservation.sha256 || '')
+ || !/^[a-f0-9]{64}$/.test(moved.postMoveObservation.digest || '')) fail('quarantine-postmove-evidence-missing');
+ state = await appendStep(directory, state, 'quarantine-resumption-administration-complete',
+ { quarantineResumptionObservation: moved.postMoveObservation ?? null });
+ }
+ const complete = await native({ command: 'verify-completed-quarantine', ...proof });
+ if (complete.verified !== true || complete.quarantineResumptionAccepted !== true || ['working', 'administration'].some(part => complete.placements?.[part]?.state !== 'quarantine')) fail('retirement-originals-not-quarantined');
+ await assertSafety(true);
+ state = await appendStep(directory, state, 'quarantined-with-metadata-transitions',
+ { branchDeleted: false, branchRetainedReason: 'quarantined-checkout-rollback-ref' });
+ await gate.releaseCheckoutReservation(reservation);
+ return { ok: true, transactionId: state.id, phase: state.phase, originalsQuarantined: true,
+ branchDeleted: false, branchRetainedReason: state.branchRetainedReason, archiveDir: directory };
+ });
const restoredFinalizationInputs = ({ directory, state, ctx }) => {
const prior = state.metadataRestoreReview;
const observations = state.metadataRestoreObservations;
@@ -587,7 +699,7 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
archiveDir: directory };
}, true);
return { review, retire, status, restore, verifyArchive, reviewBranch, retireBranch, reviewMetadataRestore, restoreMetadata,
- reviewRestoredFinalization, finalizeRestored };
+ reviewRestoredFinalization, finalizeRestored, reviewQuarantineResumption, resumeQuarantine };
}
const recovery = _createInitializedCheckoutRecovery();
@@ -604,3 +716,6 @@ export const reviewInitializedCheckoutMetadataRestore = recovery.reviewMetadataR
export const restoreInitializedCheckoutMetadata = recovery.restoreMetadata;
export const reviewInitializedCheckoutRestoredFinalization = recovery.reviewRestoredFinalization;
export const finalizeInitializedCheckoutRestored = recovery.finalizeRestored;
+
+export const reviewInitializedCheckoutQuarantineResumption = recovery.reviewQuarantineResumption;
+export const resumeInitializedCheckoutQuarantine = recovery.resumeQuarantine;
diff --git a/server/services/initializedCheckoutRecovery.test.js b/server/services/initializedCheckoutRecovery.test.js
index bcb2464940..bc9cd154a8 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), finalizationToken: '7'.repeat(64) };
+ metadataToken: 'f'.repeat(64), finalizationToken: '7'.repeat(64), quarantineToken: '6'.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,6 +96,37 @@ 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 === 'verify-deleted-branch') {
+ if (fixture.deletedRefConflict) throw new Error(fixture.deletedRefConflict);
+ if (fixture.headExists || !['branch-retired', 'retired'].includes(input.confirmedDeletion?.phase)) throw new Error('retirement-deleted-branch-not-absent');
+ return { verified: true, branchAbsent: true, confirmedDeletion: input.confirmedDeletion };
+ }
+ if (input.command === 'review-quarantine-resumption') {
+ if (fixture.failArchive) throw new Error('archive-changed');
+ if (fixture.forbiddenMetadata) throw new Error('metadata-delta-not-eligible');
+ return { quarantineResumption: { version: 1, evidenceFile: 'quarantine-proof.json',
+ evidenceSha256: fixture.quarantineToken, digest: fixture.quarantineToken },
+ initialPlacements: Object.fromEntries(Object.entries(fixture.placement).map(([part, value]) => [part, value === 'quarantined' ? 'quarantine' : value])),
+ changeCounts: { residualCompressionRemoved: 3, rootProvenanceAdded: 1 }, changedPaths: 4 };
+ }
+ if (['verify-quarantine-resumption', 'resume-quarantine', 'verify-completed-quarantine', 'verify-retired-quarantine'].includes(input.command)) {
+ if (fixture.failArchive) throw new Error('archive-changed');
+ if (fixture.forbiddenMetadata) throw new Error('metadata-delta-not-eligible');
+ if (input.quarantineResumption?.digest !== fixture.quarantineToken) throw new Error('quarantine-evidence-changed');
+ if (input.command === 'resume-quarantine') {
+ if (fixture.failResume) throw new Error('resume-interrupted');
+ fixture.placement.administration = 'quarantined';
+ if (fixture.resumeDelta) { fixture.quarantineToken = '5'.repeat(64); throw new Error('quarantine-evidence-changed'); }
+ if (fixture.failResumeResult) fixture.failNextJournal = true;
+ }
+ if (input.command === 'verify-retired-quarantine'
+ && (fixture.headExists || !['branch-retired', 'retired'].includes(input.confirmedDeletion?.phase))) throw new Error('deleted-ref-proof-refused');
+ if (input.command !== 'verify-retired-quarantine' && !fixture.headExists) throw new Error('branch-ref-changed');
+ return { verified: true, quarantineResumptionAccepted: true, fingerprint: fixture.snapshot.fingerprint,
+ placements: Object.fromEntries(Object.entries(fixture.placement).map(([part, value]) => [part, { state: value === 'quarantined' ? 'quarantine' : value }])),
+ ...(input.command === 'resume-quarantine' ? { moved: true,
+ postMoveObservation: { file: 'administration-quarantine-post-move.json', sha256: fixture.quarantineToken, digest: fixture.quarantineToken } } : {}) };
+ }
if (input.command === 'review-restored-finalization') {
if (fixture.failArchive) throw new Error('archive-changed');
return { restoredFinalization: { version: 1, evidenceFile: 'finalization.json',
@@ -290,6 +321,10 @@ describe('initialized checkout transaction', () => {
const fresh = { ...input, journalDigest: status.journalDigest };
const second = await fixture.service.reviewMetadataRestore(fresh);
expect(await fixture.service.restoreMetadata({ ...fresh, review: { digest: second.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'metadata-recovery-already-restored-use-finalization' });
+ expect((await fixture.service.status(input)).journalDigest).toBe(fresh.journalDigest);
+ const finalization = await fixture.service.reviewRestoredFinalization(fresh);
+ expect(await fixture.service.finalizeRestored({ ...fresh, review: { digest: finalization.review.digest } }))
.toMatchObject({ ok: true, restored: true });
expect(fixture.cut).toBeNull();
});
@@ -344,6 +379,198 @@ describe('initialized checkout transaction', () => {
.toMatchObject({ ok: true, restored: true });
expect(fixture.cut).toBeNull();
});
+ const resumedQuarantine = async () => {
+ const input = await interruptedMetadata();
+ const prepared = await fixture.service.reviewQuarantineResumption(input);
+ expect(prepared.ok).toBe(true);
+ const result = await fixture.service.resumeQuarantine({ ...input, review: { digest: prepared.review.digest } });
+ expect(result).toMatchObject({ ok: true, phase: 'quarantined-with-metadata-transitions', branchDeleted: false });
+ const status = await fixture.service.status(input);
+ return { ...input, journalDigest: status.journalDigest };
+ };
+ it('resumes only administration quarantine under a fresh purpose-bound review, then requires a separate branch approval', async () => {
+ const input = await interruptedMetadata();
+ const moves = fixture.deps.native.mock.calls.filter(([row]) => row.command === 'move').length;
+ const prepared = await fixture.service.reviewQuarantineResumption(input);
+ expect(prepared).toMatchObject({ ok: true, review: { mode: 'resume-initialized-quarantine', initialPlacements: { working: 'quarantine', administration: 'original' } } });
+ expect(await fixture.service.resumeQuarantine({ ...input, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: true, originalsQuarantined: true, branchDeleted: false });
+ expect(fixture.deps.native.mock.calls.filter(([row]) => row.command === 'move')).toHaveLength(moves);
+ expect(fixture.deps.native.mock.calls.filter(([row]) => row.command === 'resume-quarantine')).toHaveLength(1);
+ expect(fixture.cut).toBeNull();
+ expect(fixture.headExists).toBe(true);
+ expect(fixture.deps.deleteRef).not.toHaveBeenCalled();
+ expect(await fixture.service.status(input)).toMatchObject({ quarantineResumptionComplete: true });
+ const status = await fixture.service.status(input);
+ const branchInput = { ...input, journalDigest: status.journalDigest };
+ const branch = await fixture.service.reviewBranch(branchInput);
+ expect(branch).toMatchObject({ ok: true, review: { quarantineResumptionReview: { digest: prepared.review.digest } } });
+ expect(await fixture.service.retireBranch({ ...branchInput, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'retirement-review-changed' });
+ expect(await fixture.service.retireBranch({ ...branchInput, review: { digest: branch.review.digest } })).toMatchObject({ ok: true, branchDeleted: true });
+ expect(fixture.deps.native).toHaveBeenCalledWith(expect.objectContaining({ command: 'verify-completed-quarantine' }));
+ });
+ it.each(['delta', 'owner', 'ref', 'holder', 'cut', 'archive', 'metadata', 'forge', 'default'])('retains quarantine and its cut when reviewed %s evidence changes', async change => {
+ const input = await interruptedMetadata();
+ const prepared = await fixture.service.reviewQuarantineResumption(input);
+ if (change === 'delta') fixture.quarantineToken = '4'.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 = 'foreign';
+ if (change === 'archive') fixture.failArchive = true;
+ if (change === 'metadata') fixture.forbiddenMetadata = true;
+ if (change === 'forge') fixture.facts.prHead = '9'.repeat(40);
+ if (change === 'default') fixture.facts.defaultHead = '8'.repeat(40);
+ expect(await fixture.service.resumeQuarantine({ ...input, review: { digest: prepared.review.digest } })).toMatchObject({ ok: false, recoveryRequired: true });
+ expect(fixture.cut).not.toBeNull();
+ expect(fixture.placement).toEqual({ working: 'quarantined', administration: 'original' });
+ expect(fixture.deps.native.mock.calls.filter(([row]) => row.command === 'resume-quarantine')).toHaveLength(0);
+ expect(fixture.deps.deleteRef).not.toHaveBeenCalled();
+ });
+ it('requires fresh explicit supersession acceptance for quarantine resumption', async () => {
+ const input = await interruptedMetadata();
+ fixture.superseded = true;
+ const prepared = await fixture.service.reviewQuarantineResumption(input);
+ expect(await fixture.service.resumeQuarantine({ ...input, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'retirement-supersession-not-accepted' });
+ expect(await fixture.service.resumeQuarantine({ ...input, review: { digest: prepared.review.digest, acceptSuperseded: true } }))
+ .toMatchObject({ ok: true });
+ });
+ it('does not accept restoration evidence or restoration phases for quarantine resumption', async () => {
+ const input = await interruptedMetadata();
+ const restoration = await fixture.service.reviewMetadataRestore(input);
+ expect(await fixture.service.resumeQuarantine({ ...input, review: { digest: restoration.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'retirement-review-changed' });
+ fixture.failRestorePart = 'working';
+ await fixture.service.restoreMetadata({ ...input, review: { digest: restoration.review.digest } });
+ const status = await fixture.service.status(input);
+ expect(await fixture.service.reviewQuarantineResumption({ ...input, journalDigest: status.journalDigest }))
+ .toMatchObject({ ok: false, reason: 'quarantine-resumption-phase-not-ready' });
+ });
+ it.each(['move', 'result', 'delta'])('requires a new review after quarantine %s interruption and never repeats a completed rename', async failure => {
+ const input = await interruptedMetadata();
+ const prepared = await fixture.service.reviewQuarantineResumption(input);
+ fixture.failResume = failure === 'move';
+ fixture.failResumeResult = failure === 'result';
+ fixture.resumeDelta = failure === 'delta';
+ expect(await fixture.service.resumeQuarantine({ ...input, review: { digest: prepared.review.digest } })).toMatchObject({ ok: false });
+ const status = await fixture.service.status(input);
+ const retry = { ...input, journalDigest: status.journalDigest };
+ expect(await fixture.service.resumeQuarantine({ ...retry, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'retirement-review-changed' });
+ fixture.failResume = fixture.failResumeResult = fixture.resumeDelta = false;
+ const fresh = await fixture.service.reviewQuarantineResumption(retry);
+ const calls = fixture.deps.native.mock.calls.filter(([row]) => row.command === 'resume-quarantine').length;
+ expect(await fixture.service.resumeQuarantine({ ...retry, review: { digest: fresh.review.digest } })).toMatchObject({ ok: true });
+ expect(fixture.deps.native.mock.calls.filter(([row]) => row.command === 'resume-quarantine')).toHaveLength(calls + (failure === 'move' ? 1 : 0));
+ expect(fixture.deps.deleteRef).not.toHaveBeenCalled();
+ });
+ it('never moves after interrupted publication of a resumption approval and requires a new digest', async () => {
+ const input = await interruptedMetadata();
+ const prepared = await fixture.service.reviewQuarantineResumption(input);
+ fixture.stopAfterJournalPublication = true;
+ expect(await fixture.service.resumeQuarantine({ ...input, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'journal-publication-interrupted' });
+ expect(fixture.deps.native.mock.calls.filter(([row]) => row.command === 'resume-quarantine')).toHaveLength(0);
+ const status = await fixture.service.status(input);
+ expect(status.phase).toBe('quarantine-resumption-approved');
+ expect(await fixture.service.resumeQuarantine({ ...input, journalDigest: status.journalDigest, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'retirement-review-changed' });
+ expect(fixture.cut).not.toBeNull();
+ });
+ it('requires a fresh terminal quarantine review for interrupted cut release and never recreates a released cut', async () => {
+ const input = await interruptedMetadata();
+ const prepared = await fixture.service.reviewQuarantineResumption(input);
+ fixture.deps.admission.releaseCheckoutReservation.mockRejectedValueOnce(new Error('release-ack-lost'));
+ expect(await fixture.service.resumeQuarantine({ ...input, review: { digest: prepared.review.digest } })).toMatchObject({ ok: false });
+ const status = await fixture.service.status(input);
+ expect(status.phase).toBe('quarantined-with-metadata-transitions');
+ const retry = { ...input, journalDigest: status.journalDigest };
+ expect(await fixture.service.resumeQuarantine({ ...retry, review: { digest: prepared.review.digest } })).toMatchObject({ ok: false, reason: 'retirement-review-changed' });
+ const next = await fixture.service.reviewQuarantineResumption(retry);
+ const calls = fixture.deps.native.mock.calls.filter(([row]) => row.command === 'resume-quarantine').length;
+ expect(await fixture.service.resumeQuarantine({ ...retry, review: { digest: next.review.digest } })).toMatchObject({ ok: true });
+ expect(fixture.deps.native.mock.calls.filter(([row]) => row.command === 'resume-quarantine')).toHaveLength(calls);
+ const finished = await fixture.service.status(input);
+ expect(await fixture.service.reviewQuarantineResumption({ ...input, journalDigest: finished.journalDigest })).toMatchObject({ ok: false });
+ expect(fixture.deps.admission.reserveCheckoutRetirement).toHaveBeenCalledTimes(1);
+ });
+ it('rechecks forge and ownership after native quarantine verification before releasing the cut', async () => {
+ const input = await interruptedMetadata();
+ const prepared = await fixture.service.reviewQuarantineResumption(input);
+ const original = fixture.deps.native.getMockImplementation();
+ fixture.deps.native.mockImplementation(async value => {
+ const result = await original(value);
+ if (value.command === 'verify-completed-quarantine') fixture.facts.defaultHead = '8'.repeat(40);
+ return result;
+ });
+ expect(await fixture.service.resumeQuarantine({ ...input, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'retirement-evidence-changed' });
+ expect(fixture.cut).not.toBeNull();
+ });
+ it('verifies full transitioned sources on confirmed-deletion receipt replay without Git writes', async () => {
+ const input = await resumedQuarantine();
+ const prepared = await fixture.service.reviewBranch(input);
+ fixture.deps.recordRetirement.mockRejectedValueOnce(new Error('receipt-interrupted'));
+ expect(await fixture.service.retireBranch({ ...input, review: { digest: prepared.review.digest } })).toMatchObject({ ok: false });
+ const status = await fixture.service.status(input);
+ expect(status).toMatchObject({ phase: 'branch-retired', branchDeleted: true });
+ const retry = { ...input, journalDigest: status.journalDigest };
+ fixture.forbiddenMetadata = true;
+ expect(await fixture.service.retireBranch(retry)).toMatchObject({ ok: false, reason: 'metadata-delta-not-eligible' });
+ expect(fixture.cut).not.toBeNull();
+ fixture.forbiddenMetadata = false;
+ expect(await fixture.service.retireBranch(retry)).toMatchObject({ ok: true, receiptRecorded: true });
+ expect(fixture.deps.native).toHaveBeenCalledWith(expect.objectContaining({ command: 'verify-retired-quarantine',
+ confirmedDeletion: { journalDigest: status.journalDigest, branch: release.branch, head: release.head, phase: 'branch-retired' } }));
+ expect(fixture.deps.deleteRef).toHaveBeenCalledTimes(1);
+ });
+ it.each(['source', 'archive', 'ref', 'holder', 'cut'])('refuses changed %s during a completed quarantine receipt replay', async change => {
+ const input = await resumedQuarantine();
+ const prepared = await fixture.service.reviewBranch(input);
+ fixture.deps.recordRetirement.mockRejectedValueOnce(new Error('receipt-interrupted'));
+ await fixture.service.retireBranch({ ...input, review: { digest: prepared.review.digest } });
+ const status = await fixture.service.status(input);
+ if (change === 'source') fixture.quarantineToken = '3'.repeat(64);
+ if (change === 'archive') fixture.failArchive = true;
+ if (change === 'ref') fixture.headExists = true;
+ if (change === 'holder') fixture.newHolder = true;
+ if (change === 'cut') fixture.cut.owner.id = 'another-owner';
+ expect(await fixture.service.retireBranch({ ...input, journalDigest: status.journalDigest })).toMatchObject({ ok: false });
+ expect(fixture.cut).not.toBeNull();
+ expect(fixture.deps.deleteRef).toHaveBeenCalledTimes(1);
+ expect(fixture.deps.recordRetirement).toHaveBeenCalledTimes(1);
+ });
+ it.each([false, true])('reverifies retired quarantine after uncertain release without deleting again, cutReleased=%s', async released => {
+ const input = await resumedQuarantine();
+ const prepared = await fixture.service.reviewBranch(input);
+ fixture.deps.admission.releaseCheckoutReservation.mockImplementationOnce(async () => {
+ if (released) fixture.cut = null;
+ throw new Error('release-ack-lost');
+ });
+ expect(await fixture.service.retireBranch({ ...input, review: { digest: prepared.review.digest } })).toMatchObject({ ok: false });
+ const status = await fixture.service.status(input);
+ expect(status).toMatchObject({ phase: 'retired', branchDeleted: true });
+ const before = fixture.deps.native.mock.calls.length;
+ expect(await fixture.service.retireBranch({ ...input, journalDigest: status.journalDigest })).toMatchObject({ ok: true, receiptRecorded: true });
+ expect(fixture.deps.native.mock.calls.slice(before).map(([row]) => row.command)).toEqual(['lock', 'verify-retired-quarantine', 'verify-deleted-branch']);
+ expect(fixture.deps.deleteRef).toHaveBeenCalledTimes(1);
+ expect(fixture.deps.recordRetirement).toHaveBeenCalledTimes(1);
+ expect(fixture.cut).toBeNull();
+ });
+ it('never promotes absent-ref quarantine deletion intent to success', async () => {
+ const input = await resumedQuarantine();
+ const prepared = await fixture.service.reviewBranch(input);
+ fixture.deps.deleteRef.mockImplementationOnce(async () => { fixture.headExists = false; throw new Error('receiver-outcome-lost'); });
+ await fixture.service.retireBranch({ ...input, review: { digest: prepared.review.digest } });
+ const status = await fixture.service.status(input);
+ expect(status.phase).toBe('branch-retirement-intent');
+ expect(await fixture.service.retireBranch({ ...input, journalDigest: status.journalDigest }))
+ .toMatchObject({ ok: false, reason: 'retirement-branch-deletion-uncertain' });
+ expect(fixture.deps.native.mock.calls.filter(([row]) => row.command === 'verify-retired-quarantine')).toHaveLength(0);
+ expect(fixture.cut).not.toBeNull();
+ });
const restoredWithDelayedDrift = async () => {
const input = await interruptedMetadata();
const prepared = await fixture.service.reviewMetadataRestore(input);
@@ -355,6 +582,24 @@ describe('initialized checkout transaction', () => {
expect(fixture.placement).toEqual({ working: 'original', administration: 'original' });
return { ...input, journalDigest: status.journalDigest };
};
+ it('preserves completed move evidence when a redundant metadata restore should use finalization', async () => {
+ const input = await restoredWithDelayedDrift();
+ const previousFinalization = await fixture.service.reviewRestoredFinalization(input);
+ const redundant = await fixture.service.reviewMetadataRestore(input);
+ expect(redundant).toMatchObject({ ok: true, review: { initialPlacements: { working: 'original', administration: 'original' } } });
+ const directory = join(root, input.transactionId);
+ const names = (await readdir(directory)).filter(name => /^\d{6}\.json$/.test(name)).sort();
+ const last = join(directory, names.at(-1));
+ const previousBytes = await readFile(last, 'utf8');
+ const moves = fixture.deps.native.mock.calls.filter(([row]) => row.command === 'move').length;
+ expect(await fixture.service.restoreMetadata({ ...input, review: { digest: redundant.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'metadata-recovery-already-restored-use-finalization' });
+ expect((await fixture.service.status(input)).journalDigest).toBe(input.journalDigest);
+ expect(await readFile(last, 'utf8')).toBe(previousBytes);
+ expect(fixture.deps.native.mock.calls.filter(([row]) => row.command === 'move')).toHaveLength(moves);
+ expect(await fixture.service.finalizeRestored({ ...input, review: { digest: previousFinalization.review.digest } }))
+ .toMatchObject({ ok: true, restored: true });
+ });
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 => {
@@ -650,6 +895,22 @@ describe('initialized checkout transaction', () => {
expect(fixture.deps.deleteRef).toHaveBeenCalledTimes(1);
expect(fixture.deps.recordRetirement).toHaveBeenCalledTimes(1);
});
+ it.each(['deleted-branch-loose-path-occupied', 'deleted-branch-parent-unsafe', 'deleted-branch-packed-refs-invalid'])('preserves legacy receipt recovery when native ref absence refuses: %s', async conflict => {
+ const input = await quarantinedReview();
+ fixture.deps.recordRetirement.mockRejectedValueOnce(new Error('receipt-interrupted'));
+ await fixture.service.retireBranch(input);
+ const status = await fixture.service.status(input);
+ expect(status).toMatchObject({ phase: 'branch-retired', branchDeleted: true });
+ fixture.deletedRefConflict = conflict;
+ const result = await fixture.service.retireBranch({ ...input, journalDigest: status.journalDigest });
+ expect(result).toMatchObject({ ok: false, reason: conflict });
+ expect(fixture.cut).not.toBeNull();
+ expect(fixture.deps.recordRetirement).toHaveBeenCalledTimes(1);
+ expect(fixture.deps.deleteRef).toHaveBeenCalledTimes(1);
+ expect((await fixture.service.status(input)).journalDigest).toBe(status.journalDigest);
+ expect(fixture.deps.native).toHaveBeenCalledWith(expect.objectContaining({ command: 'verify-deleted-branch',
+ confirmedDeletion: { journalDigest: status.journalDigest, branch: release.branch, head: release.head, phase: 'branch-retired' } }));
+ });
it('does not duplicate receipts or refresh their timestamps when the sink succeeded before journal failure', async () => {
const input = await quarantinedReview();
const { recordHeldCheckoutRetirement, recordBranchReconcileOutcome } = await import('./taskSchedule.js');