Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
fix: preserve and retire initialized checkouts safely (#12607)
[._.]/8937e41da094
diff --git a/docs/STORAGE.md b/docs/STORAGE.mdindex 4cf0623f96..4adf37eb77 100644--- a/docs/STORAGE.md+++ b/docs/STORAGE.md@@ -1033,3 +1033,33 @@ without a seed or creating missing caches; sync/refresh also reconcile lazily foolder cache writers. Ambiguous legacy matches are preserved rather than guessed.These fields do not add federation or a new store; older cache records remainreadable and Gmail/API IDs retain their existing meaning.++### Initialized checkout retirement evidence++`data/cos/initialized-checkout-retirements/<transaction-id>/` is machine-local,+file-primary operational recovery evidence, created only by explicit initialized+checkout retirement. Version 1 immutable numbered JSON steps form a SHA-256+linked journal; each step and containing directory is fsynced. The directory is+0700 and journal/native manifests are 0600. `archive/` preserves original bytes+and metadata, `restore/` holds a proven standalone checkout and Git stores, and+`quarantine/` retains whole original directories. `execution.lock` and+`backend.lock` serialize service executors and surviving native commands. These+are private archives, excluded from federation and never seeded, migrated into+PostgreSQL, expired or automatically purged. No existing-record migration is+needed for the new versioned store. See+[branch reconciliation](./features/branch-reconciliation.md#explicit-initialized-checkout-preservation).++`<canonical-common-git-dir>/portos-checkout-admission/` is a separate file-primary+cross-process safety fence shared by linked checkouts and server/runner processes.+It contains nonce-owned publication directories and at most one retirement cut.+Unknown, interrupted and uncertain records block rather than age out. The native+archive excludes this control subtree; it never excludes repository payload+because it is ignored or untracked. Admission metadata is not part of the+portable repository or peer synchronization.++Initialized-checkout finalization receipts keep a compact, uncapped+`branchReconcileOutcome.retirementReceiptIdentities` map alongside the bounded+recent-retirements display list. Its keys hash the exact archive path and release+identity; values preserve the original receipt timestamp. This operational+recovery evidence prevents an interrupted journal replay from becoming fresh+retirement evidence after the display row has aged out. It has no TTL purge.diff --git a/docs/features/branch-reconciliation.md b/docs/features/branch-reconciliation.mdindex c737bdd444..da22787a69 100644--- a/docs/features/branch-reconciliation.md+++ b/docs/features/branch-reconciliation.md@@ -43,3 +43,79 @@ after a second fresh match, and ownership, HEAD and content are recheckedimmediately before removal; if that recheck refuses, the original lock isrestored. A retired row leaves the inventory and appears under *Recentlyretired* with its archive path; only the next sweep can report convergence.++## Explicit initialized-checkout preservation++Automatic cleanup continues to retain initialized submodules. The separate+`/api/cos/schedule/branch-reconcile/initialized-checkouts` capability supports+operator-reviewed private-module checkouts on macOS. Other platforms and unknown+Git layouts fail closed. It never deinitializes a module, force-removes a checkout,+or purges an archive.++1. `POST /review` accepts the exact inventory tuple (`appId`, `path`, `head`,+ `branch`, `locked`, `lockReason`) and `prUrl`. The response binds the merged PR,+ current default head, ownership, completion policy, parent/module content and+ Git administration to a review digest. A repair branch alias is accepted only+ when its exact tip equals the merged PR head. Superseded work needs an explicit+ `acceptSuperseded` decision after reviewing the full comparison.+2. `POST /retire` accepts that tuple plus `review: {prUrl, digest,+ acceptSuperseded}`. It establishes a durable repository reservation and native+ executor lock, repeats the review, archives the entire checkout and private+ administration plus the parent common object store, and proves a standalone+ restore before moving either original directory. Kernel no-replace renames+ quarantine originals without unlinking them. Each intent/result is fsynced.+3. The successful phase is **quarantined**, not fully retired. The branch remains+ with reason `quarantined-checkout-rollback-ref`. `POST /review-branch` accepts+ `appId`, `transactionId` and the fresh status `journalDigest`; it verifies the+ quarantined originals and archive, exact current branch, fresh merge/default+ head, ownership and full supersession comparison. `POST /retire-branch` accepts+ those identifiers plus the newly accepted `review`. It uses exact-head native+ deletion with holder protection and preserves the branch reflog archive,+ then records the original checkout retirement receipt. No UI merged flag+ authorizes either operation.+4. `GET /status?appId=…&transactionId=…` returns the journal phase, placements and+ current `journalDigest`. `POST /restore` requires those two identifiers plus+ that digest. It restores original inodes only to vacant original locations,+ with unchanged ownership, branch and required object proof. Unrelated shared+ refs may advance; shared config, dependency changes, missing indexed objects,+ a new holder or a changed/deleted branch hold in-place rollback.+5. `POST /verify-archive` accepts the same identifiers and journal digest. It+ independently verifies the archive and prebuilt standalone checkout, returning+ `standaloneCheckoutPath`. This recovery remains usable after the original+ branch is deleted or the live parent/module object stores are unavailable.+ Parent and module staged blobs and private recovery refs are explicitly+ checked; `git fsck` alone does not prove every staged blob exists.+6. If branch deletion was conclusively journaled as `branch-retired`, but writing+ its receipt failed, or `retired` was journaled before reservation release,+ repeat `POST /retire-branch` with the latest `journalDigest`. This verifies+ archive integrity, quarantined originals, ownership, no new holder and the+ still-absent ref; it only finishes the receipt and reservation release. It+ never deletes or recreates a ref on replay. A `branch-retirement-intent`+ without a recorded receiver result remains an explicit uncertainty hold,+ even when the ref is absent. Status reports that evidence; standalone recovery+ stays available, but no automatic retry clears the uncertain reservation.++The native backend preserves file bytes, permissions, ownership, timestamps,+ACLs, xattrs, supported flags, empty directories, hard links and symlink targets+without following symlink dependencies. It retains original identity evidence;+only the standalone copy's Git pointers are rewritten to its isolated stores.+Shared/external/nested module stores, alternates, promisor dependencies, active+Git operations, insufficient space and unsupported metadata hold the operation.+A full parent store copy and a second standalone restore require bounded free+space; there is no cache deletion fallback.++Managed checkout creation/adoption/removal, claim binding, the full workspace+preparation through agent registration/spawn, and supported Git API writers+share admission under the canonical common Git directory. Read-only merge proof+may add immutable commit objects; concurrent additions conservatively invalidate+an exact archive snapshot rather than authorize removing changed evidence. A pending+reservation survives restart. Normal writers release their permits only after+settlement; timeout, overflow or signal termination retain an uncertain permit+because direct-child exit cannot establish that every helper stopped. No PID,+age, timer or automatic retry clears this evidence. Reservation release atomically+moves the intact owner into a durable private release record, preserving evidence+across a crash without leaving an ownerless cut. Receipt replay keeps the original+archive identity and timestamp so a newer checkout obligation cannot be satisfied+by replaying an older retirement. An interrupted transaction+requires explicit status and recovery; ambiguous identities remain held. The+private journal and all copies remain available after success or recovery.diff --git a/scripts/lib/initialized_checkout_archive.py b/scripts/lib/initialized_checkout_archive.pynew file mode 100644index 0000000000..dcd63e4824--- /dev/null+++ b/scripts/lib/initialized_checkout_archive.py@@ -0,0 +1,733 @@+#!/usr/bin/env python3+"""Private Darwin archive backend. JSON-line stdin/stdout; service owns authority.++Never deletes original checkouts or Git administration. A move is one reversible+RENAME_EXCL; the caller must journal and fence each half of the transaction.+"""+import ctypes+import errno+import fcntl+import hashlib+import json+import os+from pathlib import Path+import re+import shutil+import stat+import subprocess+import sys++MAX_FILES = 200000+MAX_BYTES = 20 * 1024 ** 3+COMMON_PARTS = ('HEAD', 'objects', 'refs', 'logs', 'packed-refs', 'config', 'info',+ 'description', 'hooks', 'rr-cache')+OPERATIONS = ('MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'BISECT_LOG',+ 'rebase-merge', 'rebase-apply', 'sequencer', 'shallow')+++def fail(reason):+ raise RuntimeError(reason)+++def command(args, env=None, input_data=None):+ 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:+ fail('command-failed:' + str(args[0]) + ':' + result.stderr[-1200:])+ return result.stdout+++def git(admin, work, *args, objects=None, input_data=None):+ 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,+ GIT_NO_REPLACE_OBJECTS='1', GIT_NO_LAZY_FETCH='1')+ # Relocated linked-worktree administration must never silently use a common+ # or empty index during the standalone object-closure proof.+ env['GIT_INDEX_FILE'] = str(admin / 'index')+ if objects is not None:+ # Prove the isolated restore's complete refs/index against current live+ # objects without rewriting either its pointers or the original store.+ 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()+++def digest(value):+ return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(',', ':')).encode()).hexdigest()+++def sha(path):+ h = hashlib.sha256()+ fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)+ with os.fdopen(fd, 'rb') as source:+ if not stat.S_ISREG(os.fstat(source.fileno()).st_mode):+ fail('not-regular-file')+ for chunk in iter(lambda: source.read(1024 * 1024), b''):+ h.update(chunk)+ return h.hexdigest()+++def acl(path):+ libc = ctypes.CDLL(None, use_errno=True)+ libc.acl_get_link_np.argtypes = [ctypes.c_char_p, ctypes.c_int]+ libc.acl_get_link_np.restype = ctypes.c_void_p+ libc.acl_to_text.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_ssize_t)]+ libc.acl_to_text.restype = ctypes.c_void_p+ libc.acl_free.argtypes = [ctypes.c_void_p]+ value = libc.acl_get_link_np(os.fsencode(path), 0x100)+ if not value:+ # Darwin returns ENOENT when the extended ACL itself is absent. The+ # surrounding lstat lease separately proves the filesystem entry exists.+ if ctypes.get_errno() == errno.ENOENT:+ path.lstat()+ return ''+ raise OSError(ctypes.get_errno(), 'cannot-read-acl')+ text = None+ try:+ length = ctypes.c_ssize_t()+ text = libc.acl_to_text(value, ctypes.byref(length))+ if not text:+ raise OSError(ctypes.get_errno(), 'cannot-format-acl')+ return ctypes.string_at(text, length.value).decode('utf8')+ finally:+ if text:+ libc.acl_free(text)+ libc.acl_free(value)+++def raw_xattrs(path):+ # Apple's system Python lacks os.listxattr. Use the read-only Darwin ABI+ # from sys/xattr.h, including resource/compression data and no symlink follow.+ libc = ctypes.CDLL(None, use_errno=True)+ libc.listxattr.argtypes = [ctypes.c_char_p, ctypes.c_void_p, ctypes.c_size_t, ctypes.c_int]+ libc.getxattr.argtypes = [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_void_p,+ ctypes.c_size_t, ctypes.c_uint32, ctypes.c_int]+ libc.listxattr.restype = libc.getxattr.restype = ctypes.c_ssize_t+ options = 0x0001 | 0x0020 # XATTR_NOFOLLOW | XATTR_SHOWCOMPRESSION+ def read(call):+ size = call(None, 0)+ if size < 0:+ raise OSError(ctypes.get_errno(), 'Cannot read extended attributes')+ if size > 16 * 1024 * 1024:+ raise RuntimeError('Extended attribute exceeds verification budget')+ data = ctypes.create_string_buffer(size)+ count = call(data, size)+ if count != size:+ raise RuntimeError('Extended attribute changed during read')+ return data.raw[:size]+ names = read(lambda buffer, size: libc.listxattr(os.fsencode(path), buffer, size, options))+ return {os.fsdecode(name): read(lambda buffer, size: libc.getxattr(+ os.fsencode(path), name, buffer, size, 0, options))+ for name in sorted(filter(None, names.split(b'\0')))}++++def safe_path(value, directory=True):+ if not isinstance(value, str) or not os.path.isabs(value) or os.path.normpath(value) != value:+ fail('path-must-be-canonical-absolute')+ path = Path(value)+ for component in [*reversed(path.parents), path]:+ info = component.lstat()+ if stat.S_ISLNK(info.st_mode):+ fail('symlink-path-component')+ if directory and not path.is_dir():+ fail('path-not-directory')+ return path+++def identity(path):+ info = path.lstat()+ return {'dev': info.st_dev, 'ino': info.st_ino,+ 'birthtime': getattr(info, 'st_birthtime', None)}+++def manifest(root, reject_links=False):+ rows, groups, counts = [], {}, {}+ size = 0+ def visit(path, relative):+ nonlocal size+ if len(rows) >= MAX_FILES:+ fail('file-budget-exceeded')+ before = path.lstat()+ row = {'path': relative, 'mode': stat.S_IMODE(before.st_mode),+ 'uid': before.st_uid, 'gid': before.st_gid, 'mtimeNs': before.st_mtime_ns,+ 'flags': before.st_flags, 'acl': acl(path),+ 'xattrs': {k: hashlib.sha256(v).hexdigest() for k, v in raw_xattrs(path).items()},+ 'filesystemIdentity': identity(path)}+ rows.append(row)+ if stat.S_ISLNK(before.st_mode):+ if reject_links:+ fail('git-administration-symlink')+ row.update(kind='symlink', target=os.readlink(path))+ elif stat.S_ISREG(before.st_mode):+ size += before.st_size+ if size > MAX_BYTES:+ fail('byte-budget-exceeded')+ row.update(kind='file', bytes=before.st_size, sha256=sha(path))+ if before.st_nlink > 1:+ key = (before.st_dev, before.st_ino)+ row['hardlinkGroup'] = groups.setdefault(key, relative)+ counts[key] = (counts.get(key, (0, 0))[0] + 1, before.st_nlink)+ elif stat.S_ISDIR(before.st_mode):+ row['kind'] = 'directory'+ for child in sorted(path.iterdir()):+ visit(child, f'{relative}/{child.name}' if relative else child.name)+ else:+ fail('special-file-unsupported')+ after = path.lstat()+ lease = lambda s: (s.st_dev, s.st_ino, s.st_mode, s.st_size, s.st_mtime_ns, s.st_ctime_ns)+ if lease(before) != lease(after):+ fail('source-changed-during-scan')+ visit(root, '')+ if any(count != links for count, links in counts.values()):+ fail('external-hardlink-unsupported')+ return sorted(rows, key=lambda r: r['path'])+++def same_copy(actual, expected):+ portable = lambda rows: [{k: v for k, v in row.items() if k != 'filesystemIdentity'} for row in rows]+ return portable(actual) == portable(expected)+++def fsync_dir(path):+ fd = os.open(path, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)+ try:+ os.fsync(fd)+ finally:+ os.close(fd)+++def private_json(path, data):+ with os.fdopen(os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600), 'w') as out:+ json.dump(data, out, sort_keys=True)+ out.write('\n')+ out.flush()+ os.fsync(out.fileno())+ fsync_dir(path.parent)+++def read_pointer(path, prefix='', directory=True):+ if not stat.S_ISREG(path.lstat().st_mode):+ fail('git-pointer-not-regular')+ if path.stat().st_size > 16384:+ fail('git-pointer-too-large')+ raw = path.read_text().strip()+ if prefix:+ if not raw.startswith(prefix):+ fail('invalid-git-pointer')+ raw = raw[len(prefix):].strip()+ return safe_path(os.path.abspath(path.parent / raw), directory=directory)+++def checked_config(admin):+ for name in ['config', 'config.worktree']:+ path = admin / name+ if not path.exists():+ continue+ text = command(['git', 'config', '--no-includes', '--file', str(path), '--list'])+ for line in text.splitlines():+ key = line.split('=', 1)[0].lower()+ if key.startswith(('include.', 'includeif.')) or key.endswith('.promisor') or key == 'extensions.partialclone':+ fail('external-git-configuration')+ if key.startswith('extensions.') and key not in ('extensions.objectformat', 'extensions.worktreeconfig'):+ fail('unknown-git-extension')+++def check_admin(admin, module=False):+ if any((admin / name).exists() for name in OPERATIONS):+ fail('active-or-partial-git-state')+ for name in ('objects/info/alternates', 'objects/info/http-alternates', 'info/grafts'):+ if (admin / name).exists():+ fail('external-object-dependency')+ if module and any((admin / name).exists() for name in ('commondir', 'worktrees', 'modules')):+ fail('shared-or-nested-module')+ # Only walk the current private administration; the common worktrees/ tree+ # belongs to other live agents and is deliberately outside this capture.+ for current, dirs, files in os.walk(admin, followlinks=False):+ if Path(current) == admin and not module:+ dirs[:] = [d for d in dirs if d not in ('worktrees', 'portos-checkout-admission')]+ for name in [*dirs, *files]:+ path = Path(current) / name+ if path.is_symlink():+ fail('git-administration-symlink')+ mode = path.lstat().st_mode+ if not (stat.S_ISREG(mode) or stat.S_ISDIR(mode)):+ fail('special-git-file-unsupported')+ if name.endswith(('.lock', '.promisor')) or name.startswith('sharedindex.'):+ fail('active-or-dependent-git-state')+ checked_config(admin)+++def git_facts(admin, work):+ stage = git(admin, work, 'ls-files', '--stage', '-z')+ # Split indexes may reference a sharedindex outside this private store.+ if git(admin, work, 'rev-parse', '--shared-index-path'):+ fail('split-index-unsupported')+ return {'head': git(admin, work, 'rev-parse', '--verify', 'HEAD^{commit}'),+ 'indexSha256': sha(admin / 'index'), 'stageSha256': hashlib.sha256(stage.encode()).hexdigest(),+ 'refs': git(admin, work, 'for-each-ref', '--format=%(refname) %(objectname)')}+++def prove_index_blobs(admin, work, objects=None):+ # fsck can return success for a missing staged-only blob. Enumerate every+ # index stage explicitly, excluding gitlinks whose objects belong to modules.+ oids = set()+ for row in git(admin, work, 'ls-files', '--stage', '-z').split('\0'):+ if not row:+ continue+ mode, oid, _ = row.split('\t', 1)[0].split()+ if mode == '160000':+ continue+ if mode not in ('100644', '100755', '120000') or not re.fullmatch(r'[0-9a-f]{40}|[0-9a-f]{64}', oid):+ fail('unsupported-index-entry')+ oids.add(oid)+ if len(oids) > MAX_FILES:+ fail('index-object-budget-exceeded')+ if not oids:+ return+ expected = sorted(oids)+ lines = git(admin, work, 'cat-file', '--batch-check', objects=objects,+ input_data='\n'.join(expected) + '\n').splitlines()+ if len(lines) != len(expected):+ fail('index-object-proof-incomplete')+ for oid, line in zip(expected, lines):+ fields = line.split()+ if len(fields) != 3 or fields[0] != oid or fields[1] != 'blob' or not fields[2].isdigit():+ fail('missing-or-invalid-index-object')+++def scan(request):+ release = request['release']+ work = safe_path(release['path'])+ repo = safe_path(request['repoPath'])+ admin = read_pointer(work / '.git', 'gitdir:')+ common = read_pointer(admin / 'commondir')+ if admin.parent != common / 'worktrees' or work == repo:+ fail('not-private-linked-checkout')+ repo_admin = repo / '.git'+ if not repo_admin.is_dir():+ repo_admin = read_pointer(repo_admin, 'gitdir:')+ repo_common = read_pointer(repo_admin / 'commondir') if (repo_admin / 'commondir').exists() else safe_path(str(repo_admin))+ if common != repo_common:+ fail('repository-binding-mismatch')+ if read_pointer(admin / 'gitdir', directory=False) != work / '.git':+ # gitdir points to .git (a file), handled explicitly below.+ fail('administration-backlink-mismatch')+ return work, admin, common+++def copy_tree(source, destination):+ if destination.exists() or destination.is_symlink():+ raise RuntimeError('Destination exists; never overwrite recovery evidence')+ env = {k: v for k, v in os.environ.items() if not k.startswith('DITTO')}+ env['DITTOABORT'] = '1'+ command(['/usr/bin/ditto', '--rsrc', '--extattr', '--acl', '--qtn',+ str(source), str(destination)], env)+ # ditto and clonefile omit residual decmpfs attributes when UF_COMPRESSED+ # is unset. Preserve those exact bytes on the NEW copy only. Never install+ # compression metadata onto an actually compressed file by this mechanism.+ candidates = [source] if source.is_file() else source.rglob('*')+ for original in candidates:+ if not stat.S_ISREG(original.lstat().st_mode):+ continue+ target = destination if original == source else destination / original.relative_to(source)+ attributes = raw_xattrs(original)+ name = 'com.apple.decmpfs'+ if name not in attributes or name in raw_xattrs(target):+ continue+ if original.lstat().st_flags & 0x20 or target.lstat().st_flags & 0x20:+ raise RuntimeError('Compressed file metadata requires separate preservation review')+ if not stat.S_ISREG(target.lstat().st_mode) or sha(original) != sha(target):+ raise RuntimeError('Cannot restore residual metadata onto a different file')+ libc = ctypes.CDLL(None, use_errno=True)+ libc.setxattr.argtypes = [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_void_p,+ ctypes.c_size_t, ctypes.c_uint32, ctypes.c_int]+ libc.setxattr.restype = ctypes.c_int+ value = attributes[name]+ buffer = ctypes.create_string_buffer(value)+ if libc.setxattr(os.fsencode(target), name.encode(), buffer, len(value), 0,+ 0x0001 | 0x0002): # XATTR_NOFOLLOW | XATTR_CREATE+ raise OSError(ctypes.get_errno(), 'Cannot preserve residual compression metadata')+ # ditto also omits UF_TRACKED, which the filesystem may add later while+ # verification reads the copy. Set the exact original flags before reading;+ # retain strict flags and source-incarnation comparisons in the manifests.+ for original in [source, *source.rglob('*')] if source.is_dir() else [source]:+ target = destination if original == source else destination / original.relative_to(source)+ original_stat = original.lstat()+ # ditto creates symlinks with the current timestamp. Restore the link's+ # own timestamps without resolving even a dangling dependency target.+ if stat.S_ISLNK(original_stat.st_mode):+ os.utime(target, ns=(original_stat.st_atime_ns, original_stat.st_mtime_ns),+ follow_symlinks=False)+ expected_flags = original_stat.st_flags+ actual_flags = target.lstat().st_flags+ if (expected_flags ^ actual_flags) & 0x20:+ raise RuntimeError('Compression flags differ; cannot synthesize compressed storage')+ if expected_flags != actual_flags:+ os.chflags(target, expected_flags, follow_symlinks=False)++++def inspect(request, full=False):+ if sys.platform != 'darwin':+ fail('darwin-required')+ work, admin, common = scan(request)+ release = request['release']+ check_admin(admin)+ check_admin(common)+ parent = git_facts(admin, work)+ branch = git(admin, work, 'symbolic-ref', '--short', 'HEAD')+ if parent['head'] != release['head'] or branch != release['branch']:+ fail('release-head-or-branch-changed')+ lock = admin / 'locked'+ locked = lock.exists()+ if locked != release['locked']:+ fail('release-lock-changed')+ if locked and lock.read_text().strip() != (release.get('lockReason') or ''):+ fail('release-lock-reason-changed')+ modules = []+ for item in git(admin, work, 'ls-files', '--stage', '-z').split('\0'):+ if not item:+ continue+ fields, relative = item.split('\t', 1)+ mode, oid, stage = fields.split()+ if mode != '160000':+ continue+ if stage != '0' or os.path.isabs(relative) or '..' in Path(relative).parts:+ fail('unmerged-or-unsafe-module')+ module_work = safe_path(str(work / relative))+ module_admin = read_pointer(module_work / '.git', 'gitdir:')+ if not module_admin.is_relative_to(admin / 'modules'):+ fail('external-module-administration')+ check_admin(module_admin, module=True)+ facts = git_facts(module_admin, module_work)+ if any(row.startswith('160000 ') for row in git(module_admin, module_work, 'ls-files', '--stage', '-z').split('\0')):+ fail('nested-module-unsupported')+ modules.append({'path': relative, 'gitDir': str(module_admin),+ 'administrationPath': str(module_admin.relative_to(admin)),+ 'identity': {'working': identity(module_work), 'administration': identity(module_admin)},+ 'gitlink': oid, **facts})+ if not modules:+ fail('initialized-module-required')+ expected_pointers = {'.git', *(m['path'] + '/.git' for m in modules)}+ for current, dirs, files in os.walk(work, followlinks=False):+ if '.git' in dirs:+ fail('embedded-git-store-unsupported')+ if '.git' in files and str((Path(current) / '.git').relative_to(work)) not in expected_pointers:+ fail('unregistered-git-pointer')+ if (admin / 'modules').exists():+ allowed_admin = {m['gitDir'] for m in modules}+ for current, _, files in os.walk(admin / 'modules', followlinks=False):+ if 'HEAD' in files and 'config' in files and str(Path(current)) not in allowed_admin:+ fail('unregistered-private-module')+ sources = {'working': manifest(work), 'administration': manifest(admin, True),+ 'common': {name: manifest(common / name, True) for name in COMMON_PARTS if (common / name).exists()}}+ facts = {'identity': {'working': identity(work), 'administration': identity(admin), 'common': identity(common)},+ 'privateGitDir': str(admin), 'commonGitDir': str(common), 'modules': modules, 'parent': parent,+ 'repoPath': request['repoPath'], 'release': release}+ facts['administrationFingerprint'] = digest(sources['administration'])+ facts['fingerprint'] = digest({'facts': facts, 'sources': sources})+ return {**facts, **({'sources': sources} if full else {})}+++def transaction(value):+ root = safe_path(value)+ info = root.stat()+ if stat.S_IMODE(info.st_mode) != 0o700 or info.st_uid != os.getuid():+ fail('transaction-must-be-owned-private0700')+ return root+++def lock_file(root, name):+ fd = os.open(root / name, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, 0o600)+ info = os.fstat(fd)+ 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():+ os.close(fd)+ fail('invalid-execution-lock')+ try:+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)+ except OSError:+ os.close(fd)+ fail('backend-busy')+ return fd+++def rewrite_copy(path, text):+ # Only isolated proof pointers are rewritten; archive pointer bytes remain exact.+ if not stat.S_ISREG(path.lstat().st_mode):+ fail('restore-pointer-not-regular')+ with path.open('w') as out:+ out.write(text)+ out.flush()+ os.fsync(out.fileno())+++def proof_repositories(root, facts):+ restore = root / 'restore'+ work, admin, common = restore / 'working', restore / 'administration', restore / 'common'+ if read_pointer(work / '.git', 'gitdir:') != admin or read_pointer(admin / 'commondir') != common:+ fail('restore-parent-pointer-escaped')+ if read_pointer(admin / 'gitdir', directory=False) != work / '.git':+ fail('restore-backlink-escaped')+ results = []+ for label, store, tree, expected in [('parent', admin, work, facts['parent']), *[+ (m['path'], admin / m['administrationPath'], work / m['path'], m) for m in facts['modules']+ ]]:+ if label != 'parent' and read_pointer(tree / '.git', 'gitdir:') != store:+ fail('restore-module-pointer-escaped')+ check_admin(store, module=label != 'parent')+ actual = git_facts(store, tree)+ if any(actual[k] != expected[k] for k in ('head', 'indexSha256', 'stageSha256', 'refs')):+ fail('restored-git-facts-differ')+ # fsck validates loose/packed objects and ref closure; indexed blobs get+ # a separate existence proof below. No checkout, hooks or lost-found.+ git(store, tree, 'fsck', '--full', '--strict')+ prove_index_blobs(store, tree)+ results.append({'path': label, **actual, 'fsck': 'passed'})+ return results+++def durable_tree(root):+ """Flush only owned copies before the journal may authorize a rename."""+ directories = []+ for current, dirs, files in os.walk(root, followlinks=False):+ directories.append(Path(current))+ dirs[:] = [name for name in dirs if not (Path(current) / name).is_symlink()]+ for name in files:+ path = Path(current) / name+ if path.is_symlink():+ continue+ fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)+ try:+ os.fsync(fd)+ finally:+ os.close(fd)+ for directory in reversed(directories):+ fsync_dir(directory)+++def preserve(request):+ root = transaction(request['transactionDir'])+ before = inspect(request, full=True)+ expected = request['expected']+ if any(before[k] != expected.get(k) for k in ('fingerprint', 'administrationFingerprint', 'identity')):+ fail('inspection-changed')+ work, admin, common = Path(before['release']['path']), Path(before['privateGitDir']), Path(before['commonGitDir'])+ for source in (work, admin, common):+ if root.is_relative_to(source) or source.is_relative_to(root):+ fail('transaction-source-overlap')+ if root.stat().st_dev != source.stat().st_dev:+ fail('quarantine-cross-device')+ rows = before['sources']['working'] + before['sources']['administration']+ rows += [r for section in before['sources']['common'].values() for r in section]+ size = sum(r.get('bytes', 0) for r in rows)+ if size > MAX_BYTES or shutil.disk_usage(root).free < size * 2 + 1024 ** 3:+ fail('insufficient-preservation-space')+ for name in ('archive', 'restore', 'quarantine'):+ if os.path.lexists(root / name):+ fail('backend-destination-already-exists')+ if os.path.lexists(root / 'manifest.json'):+ fail('backend-manifest-already-exists')+ for name in ('archive', 'restore', 'quarantine'):+ (root / name).mkdir(mode=0o700)+ # Persist the complete source evidence before copying. Failure leaves a+ # recognizable incomplete archive; retry never overwrites any part.+ private_json(root / 'source.json', before)+ for label, source in [('working', work), ('administration', admin)]:+ copy_tree(source, root / 'archive' / label)+ if not same_copy(manifest(root / 'archive' / label), before['sources'][label]):+ fail('archive-metadata-mismatch:' + label)+ (root / 'archive' / 'common').mkdir(mode=0o700)+ for name, expected_rows in before['sources']['common'].items():+ copy_tree(common / name, root / 'archive' / 'common' / name)+ if not same_copy(manifest(root / 'archive' / 'common' / name, True), expected_rows):+ fail('shared-archive-metadata-mismatch:' + name)+ for label in ('working', 'administration', 'common'):+ copy_tree(root / 'archive' / label, root / 'restore' / label)+ if not same_copy(manifest(root / 'archive' / label), manifest(root / 'restore' / label)):+ fail('restore-copy-metadata-mismatch')+ restore = root / 'restore'+ rewrite_copy(restore / 'working' / '.git', 'gitdir: ' + str(restore / 'administration') + '\n')+ rewrite_copy(restore / 'administration' / 'commondir', str(restore / 'common') + '\n')+ rewrite_copy(restore / 'administration' / 'gitdir', str(restore / 'working' / '.git') + '\n')+ for m in before['modules']:+ store, tree = restore / 'administration' / m['administrationPath'], restore / 'working' / m['path']+ rewrite_copy(tree / '.git', 'gitdir: ' + str(store) + '\n')+ git(store, tree, 'config', '--file', str(store / 'config'), 'core.worktree', str(tree))+ proof = proof_repositories(root, before)+ # Check source metadata again after both full copies and offline proof.+ after = inspect(request, full=True)+ if before != after:+ fail('sources-changed-during-preservation')+ restored = {label: manifest(restore / label) for label in ('working', 'administration', 'common')}+ durable_tree(root / 'archive')+ durable_tree(restore)+ saved = {'version': 1, 'transactionIdentity': identity(root), 'facts': before,+ 'restored': restored, 'restoreProof': proof}+ private_json(root / 'manifest.json', saved)+ return {'manifestPath': str(root / 'manifest.json'), 'fingerprint': before['fingerprint'],+ 'administrationFingerprint': before['administrationFingerprint'], 'restoreProof': proof}+++def load_transaction(request):+ root = transaction(request['transactionDir'])+ path = root / 'manifest.json'+ if not stat.S_ISREG(path.lstat().st_mode) or path.stat().st_size > 256 * 1024 ** 2:+ fail('invalid-archive-manifest')+ saved = json.loads(path.read_text())+ if saved['version'] != 1 or saved['transactionIdentity'] != identity(root):+ fail('transaction-incarnation-changed')+ for label in ('archive', 'restore', 'quarantine'):+ safe_path(str(root / label))+ return root, saved+++def placements(root, facts):+ result = {}+ for label, source in [('working', facts['release']['path']), ('administration', facts['privateGitDir'])]:+ original, quarantine = Path(source), root / 'quarantine' / label+ result[label] = {}+ for name, path in [('original', original), ('quarantine', quarantine)]:+ if not os.path.lexists(path):+ result[label][name] = 'absent'+ else:+ safe_path(str(path))+ result[label][name] = 'matching' if identity(path) == facts['identity'][label] else 'foreign'+ positions = result[label]+ positions['state'] = ('original' if positions == {'original': 'matching', 'quarantine': 'absent'}+ else 'quarantine' if positions == {'original': 'absent', 'quarantine': 'matching'}+ else 'ambiguous')+ return result+++def verify_saved_archive(root, saved):+ facts = saved['facts']+ for label in ('working', 'administration'):+ if not same_copy(manifest(root / 'archive' / label), facts['sources'][label]):+ fail('archive-changed:' + label)+ for name, expected in facts['sources']['common'].items():+ if not same_copy(manifest(root / 'archive' / 'common' / name, True), expected):+ fail('common-archive-changed:' + name)+ if sorted(p.name for p in (root / 'archive/common').iterdir()) != sorted(facts['sources']['common']):+ fail('common-archive-layout-changed')+ for label, expected in saved['restored'].items():+ if manifest(root / 'restore' / label) != expected:+ fail('restore-proof-changed:' + label)+ return proof_repositories(root, facts)+++def verify(request):+ root, saved = load_transaction(request)+ facts = saved['facts']+ if request.get('mode') == 'standalone':+ proof = verify_saved_archive(root, saved)+ return {'verified': True, 'standalone': True, 'fingerprint': facts['fingerprint'],+ 'restorePath': str(root / 'restore/working'), 'restoreProof': proof}+ located = placements(root, facts)+ for label in ('working', 'administration'):+ state = located[label]['state']+ if state == 'ambiguous':+ fail('ambiguous-source-placement:' + label)+ path = Path(facts['release']['path'] if label == 'working' else facts['privateGitDir']) if state == 'original' else root / 'quarantine' / label+ if manifest(path) != facts['sources'][label]:+ fail('source-content-or-identity-changed:' + label)+ common = safe_path(facts['commonGitDir'])+ check_admin(common)+ if identity(common) != facts['identity']['common']:+ fail('common-store-incarnation-changed')+ restoring = request.get('mode') == 'restore'+ 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')+ verify_saved_archive(root, saved)+ 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')+ return {'verified': True, 'placements': located, 'fingerprint': facts['fingerprint']}+++def move(request):+ part, direction = request['part'], request['direction']+ if part not in ('working', 'administration') or direction not in ('quarantine', 'restore'):+ fail('invalid-move')+ verified = verify({**request, 'mode': 'restore' if direction == 'restore' else 'fresh'})+ root, saved = load_transaction(request)+ facts = saved['facts']+ original = Path(facts['release']['path'] if part == 'working' else facts['privateGitDir'])+ quarantined = root / 'quarantine' / part+ source, destination = (original, quarantined) if direction == 'quarantine' else (quarantined, original)+ expected_state = 'original' if direction == 'quarantine' else 'quarantine'+ if direction == 'restore' and verified['placements'][part]['state'] == 'original':+ return {'moved': False, 'alreadyRestored': True, 'part': part,+ 'direction': direction, 'placements': verified['placements']}+ if verified['placements'][part]['state'] != expected_state:+ fail('move-already-executed-or-uncertain')+ safe_path(str(source))+ safe_path(str(destination.parent))+ if identity(source) != facts['identity'][part] or os.path.lexists(destination):+ fail('move-lease-or-destination-changed')+ libc = ctypes.CDLL(None, use_errno=True)+ libc.renamex_np.argtypes = [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_uint]+ libc.renamex_np.restype = ctypes.c_int+ # RENAME_EXCL = 0x00000004, sys/stdio.h; never replace any occupied path.+ if libc.renamex_np(os.fsencode(source), os.fsencode(destination), 0x00000004):+ raise OSError(ctypes.get_errno(), 'exclusive-rename-failed')+ fsync_dir(source.parent)+ fsync_dir(destination.parent)+ if identity(destination) != facts['identity'][part]:+ fail('post-move-identity-uncertain')+ return {'moved': True, 'part': part, 'direction': direction, 'placements': placements(root, facts)}+++def main():+ request = json.loads(sys.stdin.readline())+ if sys.platform != 'darwin':+ fail('darwin-required')+ action = request['command']+ if action == 'lock':+ fd = lock_file(transaction(request['transactionDir']), 'execution.lock')+ try:+ print(json.dumps({'ok': True}), flush=True)+ # No commands are interpreted while the parent holds this lease.+ while sys.stdin.buffer.read(65536):+ pass+ finally:+ os.close(fd)+ return+ if action == 'inspect':+ result = inspect(request)+ elif action == 'status':+ root, saved = load_transaction(request)+ result = {'placements': placements(root, saved['facts']), 'fingerprint': saved['facts']['fingerprint']}+ elif action in ('preserve', 'verify', 'move'):+ fd = lock_file(transaction(request['transactionDir']), 'backend.lock')+ try:+ result = {'preserve': preserve, 'verify': verify, 'move': move}[action](request)+ finally:+ os.close(fd)+ else:+ fail('unknown-command')+ print(json.dumps({'ok': True, **result}), flush=True)+++if __name__ == '__main__':+ try:+ main()+ except Exception as error:+ print(json.dumps({'ok': False, 'reason': str(error)}), flush=True)+ sys.exit(1)diff --git a/scripts/lib/initialized_checkout_archive_test.py b/scripts/lib/initialized_checkout_archive_test.pynew file mode 100644index 0000000000..238f8ae57a--- /dev/null+++ b/scripts/lib/initialized_checkout_archive_test.py@@ -0,0 +1,242 @@+"""Disposable native integration fixtures; never use an installed checkout."""+import importlib.util+import json+import os+from pathlib import Path+import shutil+import subprocess+import sys+import tempfile+import unittest++SPEC = importlib.util.spec_from_file_location('archive', Path(__file__).with_name('initialized_checkout_archive.py'))+archive = importlib.util.module_from_spec(SPEC)+SPEC.loader.exec_module(archive)++[email protected](sys.platform == 'darwin', 'Darwin metadata/rename ABI required')+class NativeArchive(unittest.TestCase):+ def setUp(self):+ self.scratch = Path(tempfile.mkdtemp(prefix='initialized-archive-test-')).resolve()+ self.repo, self.work, self.module = [self.scratch / n for n in ('repo', 'work', 'module')]+ self.env = {k: v for k, v in os.environ.items() if not k.startswith('GIT_')}+ self.env.update(GIT_CONFIG_NOSYSTEM='1', GIT_CONFIG_GLOBAL=os.devnull,+ GIT_AUTHOR_NAME='Fixture', GIT_AUTHOR_EMAIL='[email protected]',+ GIT_COMMITTER_NAME='Fixture', GIT_COMMITTER_EMAIL='[email protected]')+ for path in (self.repo, self.module):+ path.mkdir()+ self.git(path, 'init', '-b', 'main')+ (path / 'base.txt').write_text('base\n')+ self.git(path, 'add', '.')+ self.git(path, 'commit', '-m', 'fixture base')+ self.git(self.repo, '-c', 'protocol.file.allow=always', 'submodule', 'add', self.module.as_uri(), 'sub')+ self.git(self.repo, 'commit', '-am', 'fixture module')+ self.git(self.repo, 'worktree', 'add', '-b', 'feature/fixture', str(self.work))+ self.git(self.work, '-c', 'protocol.file.allow=always', 'submodule', 'update', '--init')+ self.git(self.repo, 'worktree', 'lock', '--reason', 'fixture held', str(self.work))+ for tree in (self.work, self.work / 'sub'):+ (tree / 'staged.txt').write_text('only in index\n')+ self.git(tree, 'add', 'staged.txt')+ (tree / 'staged.txt').unlink()+ recovery = self.git(tree, 'commit-tree', 'HEAD^{tree}', '-p', 'HEAD',+ '-m', 'reachable only through recovery ref')+ recovery_ref = 'refs/worktree/recovery' if tree == self.work else 'refs/private/recovery'+ self.git(tree, 'update-ref', recovery_ref, recovery)+ (self.work / 'ignored').write_text('ignored evidence\n')+ (self.work / '.gitignore').write_text('ignored\n')+ (self.work / 'empty').mkdir()+ os.link(self.work / 'ignored', self.work / 'hardlink')+ os.symlink('/unavailable/fixture/dependencies', self.work / 'node_modules')+ self.git(self.work, 'config', 'core.fsmonitor', '!must-not-run')+ self.txn = self.scratch / 'transaction'+ self.txn.mkdir(mode=0o700)+ self.request = {'repoPath': str(self.repo), 'release': {'path': str(self.work),+ 'head': self.git(self.work, 'rev-parse', 'HEAD'), 'branch': 'feature/fixture',+ 'locked': True, 'lockReason': 'fixture held'}, 'transactionDir': str(self.txn)}++ def git(self, cwd, *args):+ return subprocess.check_output(['git', '-C', str(cwd), '-c', 'core.hooksPath=' + os.devnull,+ *args], env=self.env, stderr=subprocess.PIPE, text=True).strip()++ def tearDown(self):+ for current, _, files in os.walk(self.scratch, followlinks=False):+ for name in files:+ path = Path(current) / name+ if not path.is_symlink() and archive.acl(path):+ subprocess.run(['/bin/chmod', '-N', str(path)], check=True)+ shutil.rmtree(self.scratch)++ def preserve(self):+ self.request['expected'] = archive.inspect(self.request)+ return archive.preserve(self.request)++ def test_admission_bookkeeping_does_not_change_source_review(self):+ before = archive.inspect(self.request)+ admission = Path(before['commonGitDir']) / 'portos-checkout-admission'+ admission.mkdir(mode=0o700)+ (admission / 'writer.lock').write_text('owned service bookkeeping')+ self.assertEqual(archive.inspect(self.request), before)++ def test_restore_is_offline_and_preserves_staged_private_and_metadata(self):+ subprocess.run(['/usr/bin/xattr', '-w', 'fixture.attribute', 'preserved', str(self.work / 'ignored')], check=True)+ subprocess.run(['/usr/bin/xattr', '-w', 'com.apple.decmpfs', 'fixture-residual',+ str(self.work / 'ignored')], check=True)+ subprocess.run(['/bin/chmod', '+a', 'everyone deny delete', str(self.work / 'ignored')], check=True)+ os.chflags(self.work / 'ignored', 0x40) # UF_TRACKED, omitted by ditto.+ proof = self.preserve()+ self.assertEqual(len(proof['restoreProof']), 2)+ self.assertTrue(archive.verify(self.request)['verified'])+ saved = json.loads((self.txn / 'manifest.json').read_text())+ # All original Git stores and working trees become unavailable. The proof+ # must still resolve parent and module index-only blobs from copied stores.+ self.repo.rename(self.scratch / 'repo-offline')+ self.work.rename(self.scratch / 'work-offline')+ self.module.rename(self.scratch / 'module-offline')+ archive.proof_repositories(self.txn, saved['facts'])+ for entry in saved['restoreProof']:+ self.assertEqual(entry['fsck'], 'passed')+ self.assertEqual(os.readlink(self.txn / 'archive/working/node_modules'), '/unavailable/fixture/dependencies')+ self.assertEqual((self.txn / 'archive/working/ignored').stat().st_ino,+ (self.txn / 'archive/working/hardlink').stat().st_ino)+ self.assertEqual(archive.raw_xattrs(self.txn / 'archive/working/ignored')['com.apple.decmpfs'],+ b'fixture-residual')++ def test_individual_moves_survive_restart_and_rollback_without_unlocking(self):+ self.preserve()+ before = archive.identity(self.work)+ result = archive.move({**self.request, 'part': 'working', 'direction': 'quarantine'})+ self.assertEqual(result['placements']['working']['state'], 'quarantine')+ # Freshly loaded state sees a partial move; no module operation runs.+ self.assertTrue(archive.verify(self.request)['verified'])+ archive.move({**self.request, 'part': 'administration', 'direction': 'quarantine'})+ self.assertEqual((self.txn / 'quarantine/administration/locked').read_text().strip(), 'fixture held')+ self.assertTrue(archive.verify(self.request)['verified'])+ archive.move({**self.request, 'part': 'administration', 'direction': 'restore'})+ archive.move({**self.request, 'part': 'working', 'direction': 'restore'})+ self.assertTrue(archive.move({**self.request, 'part': 'working',+ 'direction': 'restore'})['alreadyRestored'])+ self.assertEqual(archive.identity(self.work), before)+ self.assertEqual(self.git(self.work, 'rev-parse', 'HEAD'), self.request['release']['head'])++ def test_fresh_process_refuses_foreign_rollback_target(self):+ self.preserve()+ archive.move({**self.request, 'part': 'working', 'direction': 'quarantine'})+ self.work.mkdir()+ (self.work / 'new-owner').write_text('keep this incarnation')+ result = subprocess.run([sys.executable, str(Path(archive.__file__))],+ input=json.dumps({**self.request, 'command': 'move',+ 'part': 'working', 'direction': 'restore'}) + '\n',+ text=True, capture_output=True, env=self.env)+ self.assertEqual(result.returncode, 1)+ self.assertIn('ambiguous-source-placement', json.loads(result.stdout)['reason'])+ self.assertEqual((self.work / 'new-owner').read_text(), 'keep this incarnation')+ self.assertEqual((self.txn / 'quarantine/working/ignored').read_text(), 'ignored evidence\n')++ def test_rollback_allows_unrelated_refs_but_never_changes_shared_store(self):+ self.preserve()+ for part in ('working', 'administration'):+ archive.move({**self.request, 'part': part, 'direction': 'quarantine'})+ self.git(self.repo, 'update-ref', 'refs/heads/another-agent', 'HEAD')+ with self.assertRaisesRegex(RuntimeError, 'common-store-changed'):+ archive.verify(self.request)+ # The service's durable reservation is outside the captured common parts.+ before = archive.manifest(self.repo / '.git', True)+ self.assertTrue(archive.verify({**self.request, 'mode': 'restore'})['verified'])+ self.assertEqual(archive.manifest(self.repo / '.git', True), before)+ for part in ('administration', 'working'):+ archive.move({**self.request, 'part': part, 'direction': 'restore'})+ self.assertEqual(self.git(self.repo, 'rev-parse', 'another-agent'), self.git(self.repo, 'rev-parse', 'HEAD'))++ def test_rollback_holds_missing_shared_objects_or_deleted_branch(self):+ staged = self.git(self.work, 'rev-parse', ':staged.txt')+ self.preserve()+ for part in ('working', 'administration'):+ archive.move({**self.request, 'part': part, 'direction': 'quarantine'})+ self.git(self.repo, 'update-ref', '-d', 'refs/heads/feature/fixture')+ with self.assertRaisesRegex(RuntimeError, 'command-failed'):+ archive.move({**self.request, 'part': 'administration', 'direction': 'restore'})+ self.git(self.repo, 'update-ref', 'refs/heads/feature/fixture', self.request['release']['head'])+ # Simulate loss only in this disposable live store; archive remains exact.+ (self.repo / '.git/objects' / staged[:2] / staged[2:]).unlink()+ with self.assertRaisesRegex(RuntimeError, 'missing-or-invalid-index-object'):+ archive.move({**self.request, 'part': 'administration', 'direction': 'restore'})+ self.assertFalse(self.work.exists())+ self.assertTrue((self.txn / 'quarantine/administration/locked').exists())+ self.assertTrue((self.txn / 'archive/common/objects' / staged[:2] / staged[2:]).exists())+ self.git(self.repo, 'update-ref', '-d', 'refs/heads/feature/fixture')+ self.repo.rename(self.scratch / 'repo-offline')+ self.module.rename(self.scratch / 'module-offline')+ standalone = archive.verify({**self.request, 'mode': 'standalone'})+ self.assertTrue(standalone['standalone'])+ restored = Path(standalone['restorePath'])+ self.assertEqual(self.git(restored, 'rev-parse', 'HEAD'), self.request['release']['head'])+ for tree, recovery_ref in ((restored, 'refs/worktree/recovery'),+ (restored / 'sub', 'refs/private/recovery')):+ self.assertEqual(self.git(tree, '-c', 'core.fsmonitor=false', 'show', ':staged.txt'),+ 'only in index')+ self.assertNotEqual(self.git(tree, 'rev-parse', recovery_ref), self.git(tree, 'rev-parse', 'HEAD'))++ def test_execution_lock_lasts_until_parent_stdin_closes(self):+ holder = subprocess.Popen([sys.executable, str(Path(archive.__file__))],+ stdin=subprocess.PIPE, stdout=subprocess.PIPE,+ stderr=subprocess.PIPE, text=True, env=self.env)+ try:+ holder.stdin.write(json.dumps({'command': 'lock', 'transactionDir': str(self.txn)}) + '\n')+ holder.stdin.flush()+ self.assertEqual(json.loads(holder.stdout.readline()), {'ok': True})+ with self.assertRaisesRegex(RuntimeError, 'backend-busy'):+ archive.lock_file(self.txn, 'execution.lock')+ holder.stdin.close()+ self.assertEqual(holder.wait(timeout=5), 0)+ fd = archive.lock_file(self.txn, 'execution.lock')+ os.close(fd)+ finally:+ if holder.poll() is None:+ holder.terminate()+ holder.wait(timeout=5)+ holder.stdout.close()+ holder.stderr.close()++ def test_holds_changed_source_and_occupied_destination(self):+ self.preserve()+ (self.work / 'later.txt').write_text('later owner')+ with self.assertRaisesRegex(RuntimeError, 'source-content-or-identity-changed'):+ archive.move({**self.request, 'part': 'working', 'direction': 'quarantine'})+ self.assertTrue(self.work.exists())+ self.assertFalse((self.txn / 'quarantine/working').exists())+ # An occupied destination is retained regardless of its contents.+ (self.txn / 'quarantine/working').mkdir()+ with self.assertRaisesRegex(RuntimeError, 'ambiguous-source-placement'):+ archive.move({**self.request, 'part': 'working', 'direction': 'quarantine'})+ self.assertTrue((self.work / 'later.txt').exists())++ def test_rejects_alternates_shared_modules_locks_and_special_content(self):+ facts = archive.inspect(self.request)+ admin = Path(facts['modules'][0]['gitDir'])+ for relative in ('objects/info/alternates', 'commondir', 'index.lock'):+ target = admin / relative+ target.write_text('unsupported')+ try:+ with self.assertRaises(RuntimeError):+ archive.inspect(self.request)+ finally:+ target.unlink()+ os.mkfifo(self.work / 'pipe')+ with self.assertRaisesRegex(RuntimeError, 'special-file'):+ archive.inspect(self.request)++ def test_refuses_archive_corruption_and_mutual_exclusion(self):+ self.preserve()+ (self.txn / 'archive/working/ignored').write_text('corrupt')+ with self.assertRaisesRegex(RuntimeError, 'archive-changed'):+ archive.verify(self.request)+ held = archive.lock_file(self.txn, 'backend.lock')+ try:+ with self.assertRaisesRegex(RuntimeError, 'backend-busy'):+ archive.lock_file(self.txn, 'backend.lock')+ finally:+ os.close(held)+++if __name__ == '__main__':+ unittest.main()diff --git a/server/lib/README.md b/server/lib/README.mdindex 67277e0463..fb1dd5e64b 100644--- a/server/lib/README.md+++ b/server/lib/README.md@@ -25,6 +25,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub| Module | Purpose ||---|---|+| `checkoutRetirementAdmission.js` | Durable common-repository publication/cut admission for explicit initialized-checkout quarantine; pending reservations survive restart and block managed checkout mutations until verified recovery. || `branchRetirementArchive.js` | `preserveBranchRetirement` preserves the shared branch reflog verbatim, records its filesystem metadata, and verifies a standalone bundle containing the current tip and every old/new reflog commit before local branch retirement. Its final verifier holds changed refs or reflogs; unsupported storage, missing objects and archive failures retain the branch. || `reconcileRetirementEvidence.js` | Matches exact checkout retirement receipts and retains unresolved cleanup obligations. Server-created generation timestamps prevent an old archive receipt from completing a recreated checkout at the same branch, path and head. || `backupSharedAdmission.js` | Durable cross-process backup cuts and publication leases, with fail-closed owner recovery. |diff --git a/server/lib/checkoutRetirementAdmission.js b/server/lib/checkoutRetirementAdmission.jsnew file mode 100644index 0000000000..a2c03314ea--- /dev/null+++ b/server/lib/checkoutRetirementAdmission.js@@ -0,0 +1,131 @@+/** Durable repository admission shared by checkout writers and explicit quarantine. */+import { AsyncLocalStorage } from 'node:async_hooks';+import { lstat, mkdtemp, open, readFile, rename } from 'node:fs/promises';+import { isAbsolute, join } from 'node:path';+import { type as hostOsType } from 'node:os';+import { realpathSync, openSync, writeFileSync, fsyncSync, closeSync } from 'node:fs';+import { createBackupSharedAdmission } from './backupSharedAdmission.js';+import { execGit, withGitMutationLifetime } from './execGit.js';++const context = new AsyncLocalStorage();++// Filesystem capabilities follow the actual host, not an emulated platform.+async function syncDirectory(path) {+ if (hostOsType() === 'Windows_NT') return;+ const directory = await open(path, 'r');+ try { await directory.sync(); } finally { await directory.close(); }+}+const refused = () => Object.assign(new Error('checkout-retirement-reserved'), {+ code: 'CHECKOUT_RETIREMENT_RESERVED',+});++export async function _checkoutAdmission(repoPath) {+ const common = (await execGit(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoPath)).stdout.trim();+ if (!isAbsolute(common)) throw refused();+ const directory = join(realpathSync(common), 'portos-checkout-admission');+ for (const path of [directory, join(directory, 'publications'), join(directory, 'cut')]) {+ const info = await lstat(path).catch(error => {+ if (error.code === 'ENOENT') return null;+ throw error;+ });+ if (info && (!info.isDirectory() || info.isSymbolicLink()+ || (hostOsType() !== 'Windows_NT' && (info.mode & 0o777) !== 0o700))) throw refused();+ }+ return { directory, admission: createBackupSharedAdmission(directory) };+}++/** Register before testing the cut; nested operations retain their parent's lease. */+export async function withCheckoutPublication(repoPath, work) {+ const { directory, admission } = await _checkoutAdmission(repoPath);+ const parent = context.getStore();+ const joined = parent?.directory === directory+ ? parent.lease?.active ? parent.lease : parent.cutLifetime?.active+ ? { get active() { return parent.cutLifetime.active; }, path: join(directory, 'cut') } : null+ : null;+ // Every child gets a durable permit: detached fan-out can outlive its parent.+ const lease = admission.tryPublication({ parent: joined });+ if (!lease) throw refused();+ let uncertain = false;+ const retain = () => {+ if (uncertain) return;+ uncertain = true;+ lease.markUncertain();+ };+ try { return await withGitMutationLifetime(() => context.run({ directory, lease }, work), retain); }+ finally { if (!uncertain) lease.release(); }+}++/** Cut creation precedes the reader check. A busy repository is retained, not drained. */+export async function reserveCheckoutRetirement(repoPath, transactionId) {+ const { directory } = await _checkoutAdmission(repoPath);+ const admission = createBackupSharedAdmission(directory, { makeId: () => transactionId });+ const lease = admission.reserveCut();+ if (admission.publications().length) {+ lease.release();+ throw refused();+ }+ return { directory, owner: lease.owner };+}++/** Recover only the reservation already bound to this journal, never a PID/age guess. */+export async function readCheckoutReservation(repoPath, transactionId) {+ const { directory } = await _checkoutAdmission(repoPath);+ const owner = JSON.parse(await readFile(join(directory, 'cut', 'owner.json'), 'utf8'));+ if (owner.id !== transactionId || owner.generation !== transactionId || owner.kind !== 'snapshot') throw refused();+ return { directory, owner };+}++async function verifyCheckoutReservation(reservation) {+ const cut = join(reservation.directory, 'cut');+ const info = await lstat(cut);+ if (!info.isDirectory() || info.isSymbolicLink()) throw refused();+ const owner = JSON.parse(await readFile(join(cut, 'owner.json'), 'utf8'));+ if (JSON.stringify(owner) !== JSON.stringify(reservation.owner)) throw refused();+ const uncertain = await lstat(join(cut, 'uncertain')).then(() => true, error => {+ if (error.code === 'ENOENT') return false;+ throw error;+ });+ if (uncertain) throw refused();+}++/** Only the transaction executor holding its native mutex may enter or release a cut. */+export async function withCheckoutReservation(reservation, work) {+ await verifyCheckoutReservation(reservation);+ if (createBackupSharedAdmission(reservation.directory).publications().length) throw refused();+ const cutLifetime = { active: true };+ try { return await withGitMutationLifetime(() => context.run({ directory: reservation.directory, reservation, cutLifetime }, work),+ () => {+ if (cutLifetime.uncertain) return;+ cutLifetime.uncertain = true;+ const fd = openSync(join(reservation.directory, 'cut', 'uncertain'), 'wx', 0o600);+ try { writeFileSync(fd, 'Git or helper termination is uncertain; retain reservation.\n'); fsyncSync(fd); }+ finally { closeSync(fd); }+ if (hostOsType() !== 'Windows_NT') {+ const parent = openSync(join(reservation.directory, 'cut'), 'r');+ try { fsyncSync(parent); } finally { closeSync(parent); }+ }+ }); }+ finally { cutLifetime.active = false; }+}++export async function releaseCheckoutReservation(reservation) {+ const lifetime = context.getStore()?.cutLifetime;+ if (lifetime) lifetime.active = false;+ await verifyCheckoutReservation(reservation);+ if (createBackupSharedAdmission(reservation.directory).publications().length) throw refused();+ const cut = join(reservation.directory, 'cut');+ if (context.getStore()?.cutLifetime?.uncertain) throw refused();+ const uncertain = await lstat(join(cut, 'uncertain')).then(() => true, error => {+ if (error.code === 'ENOENT') return false;+ throw error;+ });+ if (uncertain) throw refused();+ // Keep the owner intact across the release crash boundary. Atomic rename+ // either leaves the complete live cut or a complete private release record;+ // it never strands an ownerless cut which another transaction might claim.+ const released = await mkdtemp(join(reservation.directory, 'released-'));+ await syncDirectory(reservation.directory);+ await rename(cut, join(released, 'cut'));+ await syncDirectory(released);+ await syncDirectory(reservation.directory);+}diff --git a/server/lib/checkoutRetirementAdmission.test.js b/server/lib/checkoutRetirementAdmission.test.jsnew file mode 100644index 0000000000..88e54185c5--- /dev/null+++ b/server/lib/checkoutRetirementAdmission.test.js@@ -0,0 +1,167 @@+import { pinPlatform } from './testHelper.js';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { EventEmitter } from 'node:events';+import { execFileSync, spawn as realSpawn } from 'node:child_process';+import { mkdtemp, rm, readdir, readFile } from 'node:fs/promises';+import { join } from 'node:path';+import { tmpdir } from 'node:os';+const delayed = vi.hoisted(() => ({ child: null, failAfterRename: false, hostType: null, rejectDirectoryOpen: false, syntheticModes: false }));+vi.mock('node:os', async importOriginal => {+ const actual = await importOriginal();+ return { ...actual, type: () => delayed.hostType || actual.type() };+});+vi.mock('node:fs', async importOriginal => {+ const actual = await importOriginal();+ return { ...actual, openSync: (path, ...args) => {+ if (delayed.rejectDirectoryOpen && actual.existsSync(path) && actual.lstatSync(path).isDirectory()) throw new Error('directory-open-unsupported');+ return actual.openSync(path, ...args);+ } };+});+vi.mock('node:fs/promises', async importOriginal => {+ const actual = await importOriginal();+ return { ...actual, lstat: async path => {+ const info = await actual.lstat(path);+ return delayed.syntheticModes ? Object.assign(Object.create(info), { mode: (info.mode & ~0o777) | 0o777 }) : info;+ }, open: async (path, ...args) => {+ if (delayed.rejectDirectoryOpen && (await actual.lstat(path).catch(() => null))?.isDirectory()) throw new Error('directory-open-unsupported');+ return actual.open(path, ...args);+ }, rename: async (...args) => {+ await actual.rename(...args);+ if (delayed.failAfterRename) { delayed.failAfterRename = false; throw new Error('release-result-lost'); }+ } };+});+vi.mock('./childProcess.js', () => ({+ spawn: (command, args, options) => args[0] === 'fixture-delayed-mutation' ? delayed.child : realSpawn(command, args, options),+}));+import { execGit } from './execGit.js';+import { _checkoutAdmission, withCheckoutPublication, reserveCheckoutRetirement,+ withCheckoutReservation, releaseCheckoutReservation, readCheckoutReservation } from './checkoutRetirementAdmission.js';+let repo;+beforeEach(async () => {+ delayed.hostType = null; delayed.rejectDirectoryOpen = delayed.syntheticModes = false;+ repo = await mkdtemp(join(tmpdir(), 'checkout-admission-'));+ execFileSync('git', ['init', '--quiet', repo]);+});+afterEach(async () => { vi.useRealTimers(); await rm(repo, { recursive: true, force: true }); });+describe('durable checkout admission', () => {+ it('releases on actual Windows capability even if process.platform is emulated', async () => {+ const cut = await reserveCheckoutRetirement(repo, 'windows-cut');+ delayed.hostType = 'Windows_NT'; delayed.rejectDirectoryOpen = delayed.syntheticModes = true;+ const restorePlatform = pinPlatform('darwin');+ try {+ await releaseCheckoutReservation(cut);+ await withCheckoutPublication(repo, async () => {});+ expect((await _checkoutAdmission(repo)).admission.status().cut).toBeNull();+ } finally { restorePlatform(); }+ });+ it('retains the live cut when Darwin directory fsync cannot open its parent', async () => {+ const cut = await reserveCheckoutRetirement(repo, 'darwin-cut');+ delayed.hostType = 'Darwin'; delayed.rejectDirectoryOpen = true;+ await expect(releaseCheckoutReservation(cut)).rejects.toThrow('directory-open-unsupported');+ expect(JSON.parse(await readFile(join(cut.directory, 'cut', 'owner.json'), 'utf8'))).toMatchObject({ id: 'darwin-cut' });+ });+ it('rejects cuts during a writer and writers after a cut, including another instance', async () => {+ await withCheckoutPublication(repo, async () => {+ await expect(reserveCheckoutRetirement(repo, 'test-cut')).rejects.toThrow('checkout-retirement-reserved');+ await withCheckoutPublication(repo, async () => {});+ });+ const cut = await reserveCheckoutRetirement(repo, 'test-cut');+ expect((await _checkoutAdmission(repo)).admission.tryPublication()).toBeNull();+ await expect(withCheckoutPublication(repo, async () => {})).rejects.toThrow('checkout-retirement-reserved');+ await withCheckoutReservation(cut, () => withCheckoutPublication(repo, async () => {}));+ await releaseCheckoutReservation(cut);+ await withCheckoutPublication(repo, async () => {});+ });+ it('does not let an inherited async context bypass a cut after its parent ended', async () => {+ let runLater;+ const ready = new Promise(resolve => { runLater = resolve; });+ let descendant;+ await withCheckoutPublication(repo, async () => { descendant = ready.then(() => withCheckoutPublication(repo, async () => 'unsafe')); });+ const cut = await reserveCheckoutRetirement(repo, 'new-cut');+ const refused = expect(descendant).rejects.toThrow('checkout-retirement-reserved');+ runLater(); await refused;+ await releaseCheckoutReservation(cut);+ });+ it('retains a child permit when admitted fan-out outlives its parent', async () => {+ let finish, entered;+ const waiting = new Promise(resolve => { finish = resolve; });+ const ready = new Promise(resolve => { entered = resolve; });+ let child;+ await withCheckoutPublication(repo, async () => {+ child = withCheckoutPublication(repo, async () => { entered(); await waiting; });+ await ready;+ });+ await expect(reserveCheckoutRetirement(repo, 'fanout-cut')).rejects.toThrow('checkout-retirement-reserved');+ finish(); await child;+ const cut = await reserveCheckoutRetirement(repo, 'fanout-cut');+ await releaseCheckoutReservation(cut);+ });+ it('retains a cut until admitted child work finishes and revokes its join capability before release', async () => {+ const cut = await reserveCheckoutRetirement(repo, 'child-cut');+ let finish, entered;+ const waiting = new Promise(resolve => { finish = resolve; });+ const ready = new Promise(resolve => { entered = resolve; });+ let child;+ await withCheckoutReservation(cut, async () => {+ child = withCheckoutPublication(repo, async () => { entered(); await waiting; });+ await ready;+ await expect(releaseCheckoutReservation(cut)).rejects.toThrow('checkout-retirement-reserved');+ await expect(withCheckoutPublication(repo, async () => {})).rejects.toThrow('checkout-retirement-reserved');+ });+ finish(); await child;+ await releaseCheckoutReservation(cut);+ });+ it('retains uncertain mutation evidence after child close and admission recreation', async () => {+ const child = new EventEmitter();+ child.stdout = new EventEmitter(); child.stderr = new EventEmitter();+ child.pid = 12345; child.kill = vi.fn(); delayed.child = child;+ let started;+ const ready = new Promise(resolve => { started = resolve; });+ const writing = withCheckoutPublication(repo, async () => {+ vi.useFakeTimers();+ const pending = execGit(['fixture-delayed-mutation'], repo, { timeout: 20 });+ started(); return pending;+ });+ let settled = false;+ const rejected = expect(writing.finally(() => { settled = true; })).rejects.toThrow('timed out');+ await ready; await vi.advanceTimersByTimeAsync(20);+ expect(child.kill).toHaveBeenCalled(); expect(settled).toBe(false);+ child.emit('close', null, 'SIGTERM'); await rejected; vi.useRealTimers();+ expect((await _checkoutAdmission(repo)).admission.publications()).toMatchObject([{ uncertain: true }]);+ await expect(reserveCheckoutRetirement(repo, 'later-cut')).rejects.toThrow('checkout-retirement-reserved');+ });+ it('retains the complete cut owner if release crashes after its atomic rename', async () => {+ const cut = await reserveCheckoutRetirement(repo, 'released-cut');+ delayed.failAfterRename = true;+ await expect(releaseCheckoutReservation(cut)).rejects.toThrow('release-result-lost');+ const released = (await readdir(cut.directory)).filter(name => name.startsWith('released-'));+ expect(released).toHaveLength(1);+ expect(JSON.parse(await readFile(join(cut.directory, released[0], 'cut', 'owner.json'), 'utf8'))).toEqual(cut.owner);+ expect((await _checkoutAdmission(repo)).admission.status().cut).toBeNull();+ await withCheckoutPublication(repo, async () => {});+ });+ it.each([false, true])('refuses reentry of a persisted uncertain cut after timeout (Windows capability=%s)', async windows => {+ const cut = await reserveCheckoutRetirement(repo, 'uncertain-cut');+ if (windows) { delayed.hostType = 'Windows_NT'; delayed.rejectDirectoryOpen = true; }+ const child = new EventEmitter();+ child.stdout = new EventEmitter(); child.stderr = new EventEmitter();+ child.pid = 12345; child.kill = vi.fn(); delayed.child = child;+ let started;+ const ready = new Promise(resolve => { started = resolve; });+ const running = withCheckoutReservation(cut, async () => {+ vi.useFakeTimers();+ const pending = execGit(['fixture-delayed-mutation'], repo, { timeout: 20 });+ started(); return pending;+ });+ const rejected = expect(running).rejects.toThrow('timed out');+ await ready; await vi.advanceTimersByTimeAsync(20);+ child.emit('close', null, 'SIGTERM'); await rejected; vi.useRealTimers();+ const recovered = await readCheckoutReservation(repo, 'uncertain-cut');+ const work = vi.fn();+ await expect(withCheckoutReservation(recovered, work)).rejects.toThrow('checkout-retirement-reserved');+ await expect(releaseCheckoutReservation(recovered)).rejects.toThrow('checkout-retirement-reserved');+ expect(work).not.toHaveBeenCalled();+ expect((await _checkoutAdmission(repo)).admission.status().cut).toMatchObject({ uncertain: true });+ });++});diff --git a/server/lib/execGit.js b/server/lib/execGit.jsindex 1f9fc64ee0..dc00eba5f2 100644--- a/server/lib/execGit.js+++ b/server/lib/execGit.js@@ -4,6 +4,11 @@*/import { spawn } from './childProcess.js';+import { AsyncLocalStorage } from 'node:async_hooks';++const mutationLifetime = new AsyncLocalStorage();+/** Admission owners retain their durable permit when Git/helper exit is uncertain. */+export const withGitMutationLifetime = (work, onUncertain) => mutationLifetime.run(onUncertain, work);/*** Execute a git command safely using spawn (prevents shell injection).@@ -38,15 +43,31 @@ export function execGit(args, cwd, options = {}) {...(options.env ? { env: options.env } : {})});+ const onUncertain = mutationLifetime.getStore();let stdout = '';let stderr = '';let killed = false;+ let failure = null;+ let escalation = null;+ const markUncertain = () => {+ try { onUncertain?.(); }+ catch (error) { failure ||= error; }+ };+ const terminate = error => {+ if (killed) return;+ killed = true;+ failure = error;+ // A direct-child close cannot prove detached hooks/helpers settled.+ markUncertain();+ try { child.kill(); } catch (killError) { failure ||= killError; }+ escalation = setTimeout(() => {+ try { child.kill('SIGKILL'); } catch (killError) { failure ||= killError; }+ }, 5000);+ };const timer = setTimeout(() => {if (!killed) {- killed = true;- child.kill();- reject(new Error(`git command timed out after ${timeout / 1000}s: git ${args.join(' ')}`));+ terminate(new Error(`git command timed out after ${timeout / 1000}s: git ${args.join(' ')}`));}}, timeout);@@ -54,27 +75,29 @@ export function execGit(args, cwd, options = {}) {// a runaway command can't blow past maxBuffer on either channel.const guardOverflow = () => {if (stdout.length + stderr.length > maxBuffer && !killed) {- killed = true;clearTimeout(timer);- child.kill();- reject(new Error(`git output exceeded maxBuffer (${maxBuffer} bytes)`));+ terminate(new Error(`git output exceeded maxBuffer (${maxBuffer} bytes)`));}};child.stdout.on('data', (data) => {+ if (killed) return;stdout += data.toString();guardOverflow();});child.stderr.on('data', (data) => {+ if (killed) return;stderr += data.toString();guardOverflow();});child.on('close', (code, signal) => {clearTimeout(timer);- if (killed) return;+ clearTimeout(escalation);+ if (failure) { reject(failure); return; }if (code === null && signal) {+ markUncertain();if (options.ignoreExitCode) {resolve({ stdout, stderr, exitCode: null, signal, terminated: true });} else {@@ -91,6 +114,7 @@ export function execGit(args, cwd, options = {}) {child.on('error', (err) => {clearTimeout(timer);+ if (child.pid) markUncertain();reject(err);});});diff --git a/server/lib/execGit.test.js b/server/lib/execGit.test.jsindex 0bafac1f68..787a1a111e 100644--- a/server/lib/execGit.test.js+++ b/server/lib/execGit.test.js@@ -112,6 +112,7 @@ describe('execGit', () => {spawn.mockReturnValue(child);const promise = execGit(['fetch'], '/repo', { timeout: 500 });vi.advanceTimersByTime(500);+ child.emit('close', null, 'SIGTERM');await expect(promise).rejects.toThrow(/timed out after 0\.5s/);expect(child.kill).toHaveBeenCalled();});@@ -121,6 +122,7 @@ describe('execGit', () => {spawn.mockReturnValue(child);const promise = execGitSafe(['fetch'], '/repo', { timeout: 500, ignoreExitCode: true });vi.advanceTimersByTime(500);+ child.emit('close', null, 'SIGTERM');await expect(promise).resolves.toEqual({exitCode: 1,stdout: '',@@ -133,6 +135,7 @@ describe('execGit', () => {spawn.mockReturnValue(child);const promise = execGit(['log'], '/repo', { maxBuffer: 8 });child.stdout.emit('data', Buffer.from('a'.repeat(9)));+ child.emit('close', null, 'SIGTERM');await expect(promise).rejects.toThrow(/maxBuffer/);expect(child.kill).toHaveBeenCalled();});diff --git a/server/lib/hostControlRoutes.js b/server/lib/hostControlRoutes.jsindex 46cbee1a51..5716f3401b 100644--- a/server/lib/hostControlRoutes.js+++ b/server/lib/hostControlRoutes.js@@ -416,6 +416,13 @@ export const HOST_CONTROL_ROUTES = Object.freeze([// Archives and removes a checkout and its merged branch under a scoped release.'POST /api/cos/schedule/branch-reconcile/checkouts/retire','POST /api/cos/schedule/branch-reconcile/checkouts/review',+ 'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/review',+ 'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/retire',+ 'GET /api/cos/schedule/branch-reconcile/initialized-checkouts/status',+ 'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/restore',+ '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','POST /api/cos/schedule/maintenance-runs',// Editing a pending stage changes the provider used by deferred host work.'PATCH /api/cos/schedule/maintenance-runs/:id/steps/:stepId',diff --git a/server/lib/index.js b/server/lib/index.jsindex d11924c7fc..e43b188236 100644--- a/server/lib/index.js+++ b/server/lib/index.js@@ -920,3 +920,5 @@ export * from './brainLinkLocalFields.js';export * from './branchRetirementArchive.js';export * from './reconcileRetirementEvidence.js';++export * from './checkoutRetirementAdmission.js';diff --git a/server/lib/validation.js b/server/lib/validation.jsindex fa8b3efb1f..f2c38ba29b 100644--- a/server/lib/validation.js+++ b/server/lib/validation.js@@ -2871,6 +2871,17 @@ export const heldCheckoutRetireBodySchema = z.object({}).optional(),});export const heldCheckoutReviewBodySchema = heldCheckoutRetireBodySchema.omit({ review: true }).extend({ prUrl: z.string().url() });+export const initializedCheckoutRetireBodySchema = heldCheckoutRetireBodySchema.extend({+ review: heldCheckoutRetireBodySchema.shape.review.unwrap(),+}).strict();+export const initializedCheckoutTransactionSchema = z.object({ appId: nonEmptyString, transactionId: z.string().uuid() }).strict();+export const initializedCheckoutRestoreSchema = initializedCheckoutTransactionSchema.extend({+ journalDigest: z.string().regex(/^[a-f0-9]{64}$/),+}).strict();++export const initializedCheckoutBranchRetireSchema = initializedCheckoutRestoreSchema.extend({+ review: heldCheckoutRetireBodySchema.shape.review.unwrap(),+}).strict();// Per-app task-type overrides (routes/apps/taskTypes.js)export const appTaskTypeToggleBodySchema = z.object({ enabled: z.boolean() });diff --git a/server/routes/cosAgentRoutes.ownershipResponse.test.js b/server/routes/cosAgentRoutes.ownershipResponse.test.jsindex f2e7e4e781..0aa9dc6e95 100644--- a/server/routes/cosAgentRoutes.ownershipResponse.test.js+++ b/server/routes/cosAgentRoutes.ownershipResponse.test.js@@ -5,7 +5,15 @@ import { execFile } from '../lib/childProcess.js';import { startLoopbackServer, closeLoopbackServer } from '../lib/testHelper.js';import { errorMiddleware } from '../lib/errorHandler.js';-const fixture = vi.hoisted(() => ({ state: null, apiBase: '', unreadable: false, stateGate: null, onStateQueued: null }));+const fixture = vi.hoisted(() => ({ state: null, apiBase: '', retirementReserved: false, unreadable: false, stateGate: null, onStateQueued: null }));+// The HTTP contract uses synthetic repositories; real admission is covered by+// checkoutRetirementAdmission's disposable Git fixtures.+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({+ withCheckoutPublication: async (_repo, work) => {+ if (fixture.retirementReserved) throw Object.assign(new Error('checkout-retirement-reserved'), { code: 'CHECKOUT_RETIREMENT_RESERVED' });+ return work();+ },+}));vi.mock('../services/cos.js', () => ({}));vi.mock('../services/agentOrchestrator.js', () => ({}));vi.mock('../services/apps.js', () => ({ getAppById: async () => ({ repoPath: '/synthetic/repo' }) }));@@ -50,6 +58,7 @@ let server;beforeEach(async () => {fixture.unreadable = false;+ fixture.retirementReserved = false;fixture.stateGate = fixture.onStateQueued = null;fixture.state = { agents: {[coordinator]: { id: coordinator, status: 'running', workspacePath: '/synthetic/repo', metadata: {} },@@ -110,7 +119,8 @@ describe('generated ownership recheck raw HTTP response (#11348)', () => {.toEqual({ bound: false, reason: 'owner-active' });});- it.each(['claim-owner-active', 'ownership-unreadable', 'owner-unknown', 'pr-completion-human-handoff', 'pr-completion-review-required'])('preserves the %s refusal as complete JSON without reserving', async (reason) => {+ it.each(['checkout-retirement-reserved', 'claim-owner-active', 'ownership-unreadable', 'owner-unknown', 'pr-completion-human-handoff', 'pr-completion-review-required'])('preserves the %s refusal as complete JSON without reserving', async (reason) => {+ if (reason === 'checkout-retirement-reserved') fixture.retirementReserved = true;if (reason === 'claim-owner-active') {fixture.state.agents.owner = { id: 'owner', status: 'running', metadata: { claimBranches: [branch] } };}diff --git a/server/routes/cosScheduleRoutes.js b/server/routes/cosScheduleRoutes.jsindex d159ce588b..22be49c25a 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 } from '../lib/validation.js';+import { sanitizeTaskMetadata, taskDataInputsSchema, validateRequest, parsePagination, cosScheduleTargetBodySchema, heldCheckoutRetireBodySchema, heldCheckoutReviewBodySchema, initializedCheckoutRetireBodySchema, initializedCheckoutTransactionSchema, initializedCheckoutRestoreSchema, initializedCheckoutBranchRetireSchema } 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';@@ -314,6 +314,54 @@ router.post('/schedule/branch-reconcile/checkouts/retire', asyncHandler(async (rres.json(result);}));+// Explicit operator capability; automatic cleanup retains its initialized-module guard.+router.post('/schedule/branch-reconcile/initialized-checkouts/review', asyncHandler(async (req, res) => {+ const { appId, prUrl, ...release } = validateRequest(heldCheckoutReviewBodySchema.strict(), req.body);+ const { reviewInitializedCheckout } = await import('../services/initializedCheckoutRecovery.js');+ const result = await reviewInitializedCheckout({ appId, release, prUrl });+ res.status(result.ok ? 200 : 409).json(result);+}));++router.post('/schedule/branch-reconcile/initialized-checkouts/retire', asyncHandler(async (req, res) => {+ const { appId, review, ...release } = validateRequest(initializedCheckoutRetireBodySchema, req.body);+ const { retireInitializedCheckout } = await import('../services/initializedCheckoutRecovery.js');+ const result = await retireInitializedCheckout({ appId, release, review });+ res.status(result.ok ? 200 : 409).json(result);+}));++router.get('/schedule/branch-reconcile/initialized-checkouts/status', asyncHandler(async (req, res) => {+ const input = validateRequest(initializedCheckoutTransactionSchema, req.query);+ const { initializedCheckoutStatus } = await import('../services/initializedCheckoutRecovery.js');+ res.json(await initializedCheckoutStatus(input));+}));++router.post('/schedule/branch-reconcile/initialized-checkouts/restore', asyncHandler(async (req, res) => {+ const input = validateRequest(initializedCheckoutRestoreSchema, req.body);+ const { restoreInitializedCheckout } = await import('../services/initializedCheckoutRecovery.js');+ const result = await restoreInitializedCheckout(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');+ res.json(await verifyInitializedCheckoutArchive(input));+}));++router.post('/schedule/branch-reconcile/initialized-checkouts/review-branch', asyncHandler(async (req, res) => {+ const input = validateRequest(initializedCheckoutRestoreSchema, req.body);+ const { reviewInitializedCheckoutBranch } = await import('../services/initializedCheckoutRecovery.js');+ const result = await reviewInitializedCheckoutBranch(input);+ res.status(result.ok ? 200 : 409).json(result);+}));++router.post('/schedule/branch-reconcile/initialized-checkouts/retire-branch', asyncHandler(async (req, res) => {+ const input = validateRequest(initializedCheckoutBranchRetireSchema, req.body);+ const { retireInitializedCheckoutBranch } = await import('../services/initializedCheckoutRecovery.js');+ const result = await retireInitializedCheckoutBranch(input);+ res.status(result.ok ? 200 : 409).json(result);+}));+// Manual maintenance runs — the Schedule tab's "Run maintenance now"; see// services/maintenanceRun.js for why this is not a quota burn.router.get('/schedule/deep-audits/:id', asyncHandler(async (req, res) => {diff --git a/server/routes/cosScheduleRoutes.test.js b/server/routes/cosScheduleRoutes.test.jsindex f4961af284..567d26fe55 100644--- a/server/routes/cosScheduleRoutes.test.js+++ b/server/routes/cosScheduleRoutes.test.js@@ -10,6 +10,9 @@ 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() }));+vi.mock('../services/initializedCheckoutRecovery.js', () => initialized);+vi.mock('../services/taskSchedule.js', () => ({getScheduleStatus: vi.fn(),getUpcomingTasks: vi.fn(),@@ -61,6 +64,36 @@ describe('CoS Schedule Routes', () => {expect(recovery.retireInventoriedCheckout).not.toHaveBeenCalled();});+ it('requires exact review and journal proofs for explicit initialized checkout operations', async () => {+ const base = '/api/cos/schedule/branch-reconcile/initialized-checkouts';+ const tuple = { path: '/synthetic/checkout', head: 'a'.repeat(40), branch: 'claim/42', locked: false, lockReason: null };+ const prUrl = 'https://github.com/example/repo/pull/42';+ initialized.reviewInitializedCheckout.mockResolvedValue({ ok: true, review: { digest: 'b'.repeat(64) } });+ expect((await request(app).post(`${base}/review`).send({ appId: 'app', ...tuple, prUrl })).status).toBe(200);+ expect(initialized.reviewInitializedCheckout).toHaveBeenCalledWith({ appId: 'app', release: tuple, prUrl });+ expect((await request(app).post(`${base}/retire`).send({ appId: 'app', ...tuple })).status).toBe(400);+ expect(initialized.retireInitializedCheckout).not.toHaveBeenCalled();+ const review = { prUrl, digest: 'b'.repeat(64), acceptSuperseded: false };+ initialized.retireInitializedCheckout.mockResolvedValue({ ok: false, reason: 'active-owner' });+ expect((await request(app).post(`${base}/retire`).send({ appId: 'app', ...tuple, review })).status).toBe(409);+ expect(initialized.retireInitializedCheckout).toHaveBeenCalledWith({ appId: 'app', release: tuple, review });+ const recoveryInput = { appId: 'app', transactionId: '2f800be9-6824-4726-813d-8d9ea0b2c1dc' };+ initialized.initializedCheckoutStatus.mockResolvedValue({ ok: true, phase: 'quarantined' });+ expect((await request(app).get(`${base}/status?appId=app&transactionId=${recoveryInput.transactionId}`)).status).toBe(200);+ expect((await request(app).post(`${base}/restore`).send(recoveryInput)).status).toBe(400);+ initialized.restoreInitializedCheckout.mockResolvedValue({ ok: true, restored: true });+ const restore = { ...recoveryInput, journalDigest: 'c'.repeat(64) };+ expect((await request(app).post(`${base}/restore`).send(restore)).status).toBe(200);+ expect(initialized.restoreInitializedCheckout).toHaveBeenCalledWith(restore);+ initialized.reviewInitializedCheckoutBranch.mockResolvedValue({ ok: true, review: { digest: 'd'.repeat(64) } });+ expect((await request(app).post(`${base}/review-branch`).send(restore)).status).toBe(200);+ expect((await request(app).post(`${base}/retire-branch`).send(restore)).status).toBe(400);+ initialized.retireInitializedCheckoutBranch.mockResolvedValue({ ok: true, branchDeleted: true });+ const branchInput = { ...restore, review };+ expect((await request(app).post(`${base}/retire-branch`).send(branchInput)).status).toBe(200);+ expect(initialized.retireInitializedCheckoutBranch).toHaveBeenCalledWith(branchInput);+ });+describe('GET /api/cos/schedule', () => {it('surfaces unavailable schedule inputs as errors and recovers on the next read', async () => {taskSchedule.getScheduleStatusdiff --git a/server/services/README.md b/server/services/README.mdindex 2cd6dd49a6..2a14242662 100644--- a/server/services/README.md+++ b/server/services/README.md@@ -8,6 +8,7 @@ image-generation paths below are useful entry points when tracing render jobs.| --- | --- || `branchReconcileRetirement.js` | Prepares exact, owner-checked historical review obligations and API-only review/retirement instructions; no inferred approval or deletion. || `branchReconcileCompletion.js` | Runs ownership-checked merged and superseded cleanup on coordinator completion, independent of perpetual scheduling. |+| `initializedCheckoutRecovery.js` | Explicit macOS private-module checkout archive, standalone recovery proof, durable reservation, reversible whole-directory quarantine and transaction-bound branch finalization/receipt replay; automatic module cleanup remains blocked. || `heldCheckoutReview.js` | Computes fresh forge identity, merged PR/default refs and exact code comparisons for a digest-bound operator retirement; no saved consent or policy rewrites. || `heldCheckoutRecovery.js` | Prepares scoped retirement reviews and preserves checkout content, empty gitlinks and private Git administration before ownership-checked removal and expected-head local ref deletion. Pending-merge receipts use `retirePendingMergeCheckout`, which independently verifies the merged head and refuses locks, supersession and initialized submodules. || `cosClaimOwnershipState.js` | Shared ownership lock and fail-closed live-agent reader used by claim binding and worktree cleanup. Re-exported by `cosClaimOwnership.js` for existing callers; does not import reconciliation. |diff --git a/server/services/agentLifecycle.blockAndBail.test.js b/server/services/agentLifecycle.blockAndBail.test.jsindex 03bc40b8a8..ad569cd2c7 100644--- a/server/services/agentLifecycle.blockAndBail.test.js+++ b/server/services/agentLifecycle.blockAndBail.test.js@@ -100,7 +100,7 @@ vi.mock('./agentProviderResolution.js', () => ({ resolveAgentProviderAndModel: v// Stops the spawn immediately after the pre-prep gates. The two post-prep// gates (input materialization / snapshot load) override it per test.vi.mock('./agentWorkspacePrep.js', () => ({- prepareAgentWorkspace: vi.fn().mockResolvedValue({ outcome: 'blocked', reason: 'stop here' }),+ prepareAgentWorkspace: vi.fn(async ({ onPrepared }) => onPrepared({ outcome: 'blocked', reason: 'stop here' })),}));vi.mock('./agentWorktreeCleanup.js', () => ({cleanupAgentWorktree: vi.fn(),@@ -218,12 +218,12 @@ const markerReleasedFor = (app) => vi.mocked(releaseAppReviewMarker).mock.calls* other case at, so the two post-prep gates are actually reached.*/function reachPostPrepGates() {- vi.mocked(prepareAgentWorkspace).mockResolvedValue({+ vi.mocked(prepareAgentWorkspace).mockImplementation(async ({ onPrepared }) => onPrepared({outcome: 'ready',workspacePath: join(TEMP_ROOT, 'workspace'),resolvedAppName: APP,worktreeInfo: null,- });+ }));vi.mocked(materializePublicReviewInput).mockResolvedValue(true);vi.mocked(materializePublicReviewPatches).mockResolvedValue(true);vi.mocked(readPublicReviewInputSnapshot).mockResolvedValue({ pullRequests: [] });@@ -247,7 +247,7 @@ beforeEach(() => {vi.mocked(resolveAgentProviderAndModel).mockResolvedValue({ok: true, provider: CLAUDE_TUI, selectedModel: 'sonnet', modelSelection: {},});- vi.mocked(prepareAgentWorkspace).mockResolvedValue({ outcome: 'blocked', reason: 'stop here' });+ vi.mocked(prepareAgentWorkspace).mockImplementation(async ({ onPrepared }) => onPrepared({ outcome: 'blocked', reason: 'stop here' }));});afterAll(() => rmSync(TEMP_ROOT, { recursive: true, force: true }));diff --git a/server/services/agentLifecycle.postureGate.test.js b/server/services/agentLifecycle.postureGate.test.jsindex 2836f11862..731de8a286 100644--- a/server/services/agentLifecycle.postureGate.test.js+++ b/server/services/agentLifecycle.postureGate.test.js@@ -101,7 +101,7 @@ vi.mock('./agentProviderResolution.js', () => ({ resolveAgentProviderAndModel: v// what most of this file observes, and letting the real workspace prep run// would touch git. The dispatch cases override it per test via `reachDispatch`.vi.mock('./agentWorkspacePrep.js', () => ({- prepareAgentWorkspace: vi.fn().mockResolvedValue({ outcome: 'blocked', reason: 'stop here' }),+ prepareAgentWorkspace: vi.fn(async ({ onPrepared }) => onPrepared({ outcome: 'blocked', reason: 'stop here' })),}));vi.mock('./agentWorktreeCleanup.js', () => ({cleanupAgentWorktree: vi.fn(),@@ -184,12 +184,12 @@ const postureBlockWrites = () => vi.mocked(updateTask).mock.calls.filter(* branch-jack baseline.*/function reachDispatch() {- vi.mocked(prepareAgentWorkspace).mockResolvedValueOnce({+ vi.mocked(prepareAgentWorkspace).mockImplementationOnce(async ({ onPrepared }) => onPrepared({outcome: 'ready',workspacePath: join(TEMP_ROOT, 'workspace'),resolvedAppName: 'example-app',worktreeInfo: null,- });+ }));vi.mocked(materializePublicReviewInput).mockResolvedValue(true);// The actions stage also materializes the read-only patch files; without this// its dispatch cases block on `public-review-input-missing` before routing.@@ -242,11 +242,11 @@ describe('spawn setup failure after the worktree exists', () => {// Every failed Stage 2 spawn used to leave its checkout behind: the task// stayed pending and each retry cut another worktree.it('removes the worktree this attempt cut', async () => {- vi.mocked(prepareAgentWorkspace).mockResolvedValueOnce({+ vi.mocked(prepareAgentWorkspace).mockImplementationOnce(async ({ onPrepared }) => onPrepared({outcome: 'ready',workspacePath: '/tmp/worktrees/agent-x',worktreeInfo: { worktreePath: '/tmp/worktrees/agent-x', branchName: 'cos/task-public-review/agent-x' },- });+ }));vi.mocked(materializePublicReviewInput).mockRejectedValueOnce(new Error('The "cb" argument must be of type function'));await spawnAgentForTask({diff --git a/server/services/agentManagement.claimResume.test.js b/server/services/agentManagement.claimResume.test.jsindex 0b6a8fb779..44db82adde 100644--- a/server/services/agentManagement.claimResume.test.js+++ b/server/services/agentManagement.claimResume.test.js@@ -1,3 +1,4 @@+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: async (_repo, work) => work() }));/** Resume to real spawn dispatch, registration, completion and ownership gates.* Only provider/process, git discovery and persisted IO are doubled.*/@@ -59,7 +60,7 @@ vi.mock('./workspaceContext.js', () => ({ snapshotOnRepoSwitch: vi.fn() }));vi.mock('./agentProviderResolution.js', () => ({ resolveAgentProviderAndModel: async () => ({ok: true, provider: { id: 'example-cli', type: 'cli', command: 'codex' }, selectedModel: 'example-model', modelSelection: {},}) }));-vi.mock('./agentWorkspacePrep.js', () => ({ prepareAgentWorkspace: async () => ({+vi.mock('./agentWorkspacePrep.js', () => ({ prepareAgentWorkspace: async ({ onPrepared }) => onPrepared({workspacePath: '/repos/example', worktreeInfo: null,}) }));vi.mock('./agentCliSpawning.js', () => ({diff --git a/server/services/agentSpawnDispatch.dispatching.test.js b/server/services/agentSpawnDispatch.dispatching.test.jsindex 41c46f5c2f..5d93f31aaf 100644--- a/server/services/agentSpawnDispatch.dispatching.test.js+++ b/server/services/agentSpawnDispatch.dispatching.test.js@@ -3,7 +3,12 @@*/import { beforeEach, describe, expect, it, vi } from 'vitest';-const f = vi.hoisted(() => ({ registerGate: null, prep: null }));+const f = vi.hoisted(() => ({ registerGate: null, prep: null, publicationActive: false, refusePublication: false }));+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: vi.fn(async (_repo, work) => {+ if (f.refusePublication) throw new Error('checkout-retirement-reserved');+ f.publicationActive = true;+ try { return await work(); } finally { f.publicationActive = false; }+}) }));vi.mock('./cos.js', () => ({ getConfig: async () => ({}), updateTask: async () => ({ ok: true }) }));vi.mock('./cosAgentLifecycle.js', () => ({registerAgent: vi.fn(() => f.registerGate),@@ -33,7 +38,10 @@ vi.mock('./agentProviderResolution.js', () => ({ok: true, provider: { id: 'example-cli', type: 'cli', command: 'codex' }, selectedModel: 'example-model', modelSelection: {},}),}));-vi.mock('./agentWorkspacePrep.js', () => ({ prepareAgentWorkspace: async () => f.prep }));+vi.mock('./agentWorkspacePrep.js', () => ({ prepareAgentWorkspace: vi.fn(async ({ onPrepared }) => {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication('/repos/example', () => onPrepared(f.prep));+}) }));vi.mock('./agentCliSpawning.js', () => ({buildCliSpawnConfig: () => ({ command: 'codex', args: [] }),isClaudeCliProvider: () => false,@@ -46,6 +54,9 @@ vi.mock('./agentTuiSpawning.js', () => ({ buildTuiSpawnConfig: vi.fn(), spawnTuiimport { dispatchAgentRun } from './agentSpawnDispatch.js';import { getActiveAgentIds, protectedAgentIds, setUseRunner } from './agentState.js';import { spawnDirectly } from './agentCliSpawning.js';+import { prepareAgentWorkspace } from './agentWorkspacePrep.js';+import { registerAgent } from './cosAgentLifecycle.js';+import { withCheckoutPublication } from '../lib/checkoutRetirementAdmission.js';const task = { id: 'task-example', taskType: 'user', description: 'example', metadata: {} };const newContext = () => ({@@ -58,6 +69,7 @@ const isProtected = () => getActiveAgentIds().includes('agent-x') && protectedAgbeforeEach(() => {vi.clearAllMocks();setUseRunner(false);+ f.publicationActive = f.refusePublication = false;f.registerGate = Promise.resolve();f.prep = { outcome: 'ready', workspacePath: '/repos/example', worktreeInfo: null };});@@ -75,6 +87,32 @@ describe('dispatchAgentRun ownership window', () => {expect(getActiveAgentIds()).not.toContain('agent-x');});+ it.each([{}, { claimResumeInPlace: true }, { existingBranch: 'feature/existing', useWorktree: true }])('holds workspace publication through pending registration and spawn: %j', async metadata => {+ let finishRegistration;+ f.registerGate = new Promise(resolve => { finishRegistration = resolve; });+ const context = newContext();+ context.task = { ...task, metadata: { ...metadata, app: 'example-app' } };+ const dispatched = dispatchAgentRun(context);+ await vi.waitFor(() => expect(registerAgent).toHaveBeenCalled());+ expect(withCheckoutPublication).toHaveBeenCalledWith('/repos/example', expect.any(Function));+ expect(f.publicationActive).toBe(true);+ expect(spawnDirectly).not.toHaveBeenCalled();+ spawnDirectly.mockImplementationOnce(async () => { expect(f.publicationActive).toBe(true); return 'agent-x'; });+ finishRegistration(); await dispatched;+ expect(f.publicationActive).toBe(false);+ });++ it('refuses a resumed claim before workspace preparation when retirement owns the cut', async () => {+ f.refusePublication = true;+ const context = newContext();+ context.task = { ...task, metadata: { claimResumeInPlace: 'true', app: 'example-app' } };+ await expect(dispatchAgentRun(context)).rejects.toThrow('checkout-retirement-reserved');+ expect(prepareAgentWorkspace).toHaveBeenCalledOnce();+ expect(registerAgent).not.toHaveBeenCalled();+ expect(spawnDirectly).not.toHaveBeenCalled();+ expect(getActiveAgentIds()).not.toContain('agent-x');+ });+it('releases the agent when workspace prep blocks the dispatch', async () => {f.prep = { outcome: 'blocked', reason: 'no workspace' };const context = newContext();diff --git a/server/services/agentSpawnDispatch.js b/server/services/agentSpawnDispatch.jsindex 7bf8944479..b1d88b1044 100644--- a/server/services/agentSpawnDispatch.js+++ b/server/services/agentSpawnDispatch.js@@ -95,214 +95,236 @@ async function runAgentDispatch(context, { spawnViaRunner } = {}) {const dispatchUseRunner = (publicReview || hasCredentialBootstrap(provider)) ? false : useRunner;let publicReviewPromptData = null;- const prep = await prepareAgentWorkspace({ agentId, task });- if (prep.outcome === 'deferred') {- await context.cleanupOnError(prep.reason);- cosEvents.emit('agent:deferred', { taskId: task.id, reason: prep.deferReason, branch: prep.branch });- return null;- }- if (prep.outcome === 'blocked') {- await context.cleanupOnError(prep.reason);- cosEvents.emit('agent:error', { taskId: task.id, error: prep.reason });- return null;- }- const { workspacePath, resolvedApp, resolvedAppName, worktreeInfo, jiraTicket, jiraBranchName, explicitWorktree } = prep;- if (worktreeInfo?.branchName && !worktreeInfo.existingBranch && !worktreeInfo.isPersistentWorktree) {- context.spawnWorktree = { branchName: worktreeInfo.branchName };- }+ return prepareAgentWorkspace({ agentId, task, onPrepared: async prep => {+ if (prep.outcome === 'deferred') {+ await context.cleanupOnError(prep.reason);+ cosEvents.emit('agent:deferred', { taskId: task.id, reason: prep.deferReason, branch: prep.branch });+ return null;+ }+ if (prep.outcome === 'blocked') {+ await context.cleanupOnError(prep.reason);+ cosEvents.emit('agent:error', { taskId: task.id, error: prep.reason });+ return null;+ }+ const { workspacePath, resolvedApp, resolvedAppName, worktreeInfo, jiraTicket, jiraBranchName, explicitWorktree } = prep;+ if (worktreeInfo?.branchName && !worktreeInfo.existingBranch && !worktreeInfo.isPersistentWorktree) {+ context.spawnWorktree = { branchName: worktreeInfo.branchName };+ }- if (publicReview && !privateSecurity) {- const reviewInput = await loadPublicReviewSpawnInput({- scanKey: task.metadata?.pipeline?.reviewInputKey,- workspacePath,- actionsStage: publicReviewActions,- eligibleNumbers: task.metadata?.pipeline?.eligibility?.eligibleNumbers,- noToolReviewer: publicReviewNoTools,- });- if (reviewInput.block) return context.blockAndBail(reviewInput.block);- publicReviewPromptData = reviewInput.promptData;- }+ if (publicReview && !privateSecurity) {+ const reviewInput = await loadPublicReviewSpawnInput({+ scanKey: task.metadata?.pipeline?.reviewInputKey,+ workspacePath,+ actionsStage: publicReviewActions,+ eligibleNumbers: task.metadata?.pipeline?.eligibility?.eligibleNumbers,+ noToolReviewer: publicReviewNoTools,+ });+ if (reviewInput.block) return context.blockAndBail(reviewInput.block);+ publicReviewPromptData = reviewInput.promptData;+ }- await import('./workspaceContext.js')- .then((ws) => ws.snapshotOnRepoSwitch(task.metadata?.app || null))- .catch((err) => {- emitLog('warn', `Workspace auto-snapshot skipped for task ${task.id}: ${err?.message || err}`, { taskId: task.id });- });+ await import('./workspaceContext.js')+ .then((ws) => ws.snapshotOnRepoSwitch(task.metadata?.app || null))+ .catch((err) => {+ emitLog('warn', `Workspace auto-snapshot skipped for task ${task.id}: ${err?.message || err}`, { taskId: task.id });+ });- const leanMode = isOllamaClaudeProvider(provider);- const isLightContext = isTui || provider.type === PROVIDER_TYPES.CLI;- const splitSystemPrompt = isLightContext && isClaudeCommand(provider.command);- const privatePrompt = privateSecurity- ? await import('./privateSecurityAssessment.js').then(({ preparePrivateSecurityAssessment }) => preparePrivateSecurityAssessment(task, provider, selectedModel))- : null;- const promptTrace = {};- const promptResult = privateSecurity ? privatePrompt : await buildAgentPrompt(task, config, workspacePath, worktreeInfo, {- promptTrace,- providerType: provider.type,- providerId: provider.id,- providerCommand: provider.command,- providerModel: selectedModel,- agentId,- leanMode,- split: splitSystemPrompt,- });- const basePrompt = typeof promptResult === 'string' ? promptResult : promptResult.userPrompt;- const prompt = publicReview && !privateSecurity- ? `${basePrompt}\n\n${formatPublicReviewInputPrompt(publicReviewPromptData)}`- : basePrompt;- const systemPrompt = typeof promptResult === 'string' ? null : promptResult.systemPrompt;- const requestedProvider = applyTaskGenerationOverrides(provider, task.metadata);- const { provider: runProvider, effort: taskEffort } = await dropUnsupportedOllamaThinking(- requestedProvider,- selectedModel,- requestedProvider.effort || null,- );- const localEndpoint = localEndpointOfProvider(provider);- const localPromptBudget = localEndpoint- ? planLocalPromptBudget({- prompt,- endpoint: localEndpoint,- baseDurationMs: await import('./taskLearning.js')- .then((tl) => tl.getTaskDurationEstimate(task.description, {- providerId: provider.id,- model: selectedModel,- effort: taskEffort,- }))- .then((estimate) => estimate?.estimatedDurationMs ?? null)- .catch(() => null),- })- : null;- if (localPromptBudget?.longPrefill) {- emitLog('info', `🐢 Agent ${agentId} ${describeLocalPromptBudget(localPromptBudget)}`, {+ const leanMode = isOllamaClaudeProvider(provider);+ const isLightContext = isTui || provider.type === PROVIDER_TYPES.CLI;+ const splitSystemPrompt = isLightContext && isClaudeCommand(provider.command);+ const privatePrompt = privateSecurity+ ? await import('./privateSecurityAssessment.js').then(({ preparePrivateSecurityAssessment }) => preparePrivateSecurityAssessment(task, provider, selectedModel))+ : null;+ const promptTrace = {};+ const promptResult = privateSecurity ? privatePrompt : await buildAgentPrompt(task, config, workspacePath, worktreeInfo, {+ promptTrace,+ providerType: provider.type,+ providerId: provider.id,+ providerCommand: provider.command,+ providerModel: selectedModel,agentId,- taskId: task.id,- promptTokens: localPromptBudget.promptTokens,+ leanMode,+ split: splitSystemPrompt,});- }-- const executionMode = resolveExecutionMode({ spawnHeadless, useRunner: dispatchUseRunner });- const sourceWorkspace = worktreeInfo- ? (task.metadata?.app ? await getAppWorkspace(task.metadata.app) : ROOT_DIR)- : null;- const prOpenedBy = promptOpensOwnPr(task, {- providerType: provider.type,- providerId: provider.id,- providerCommand: provider.command,- leanMode,- worktreeInfo,- });- const claimFlowTask = isClaimFlowTask(task);- const [forgeTarget, primaryCheckoutBaseline, auditSourceEvidence] = await Promise.all([- resolvedApp- ? resolveAppForgeTarget(resolvedApp, { repoPath: workspacePath }).then(r => r.target)- : resolveRepoForgeTarget(workspacePath),- sourceWorkspace ? capturePrimaryCheckoutState(sourceWorkspace) : null,- isAuditTaskType(resolveTaskHookType(task)) ? captureAuditSourceEvidence(workspacePath) : null,- ]);- const injectedMemories = promptTrace.injectedMemories || [];- let systemPromptFile = null;- const agentDir = join(AGENTS_DIR, agentId);- const { runId } = await withBackupAssetPublication(async () => {- if (!existsSync(agentDir)) {- await ensureDir(agentDir);- }- await writeFileGuarded(join(agentDir, 'prompt.txt'), prompt);- if (systemPrompt) {- systemPromptFile = join(agentDir, 'system-prompt.md');- await writeFileGuarded(systemPromptFile, systemPrompt);+ const basePrompt = typeof promptResult === 'string' ? promptResult : promptResult.userPrompt;+ const prompt = publicReview && !privateSecurity+ ? `${basePrompt}\n\n${formatPublicReviewInputPrompt(publicReviewPromptData)}`+ : basePrompt;+ const systemPrompt = typeof promptResult === 'string' ? null : promptResult.systemPrompt;+ const requestedProvider = applyTaskGenerationOverrides(provider, task.metadata);+ const { provider: runProvider, effort: taskEffort } = await dropUnsupportedOllamaThinking(+ requestedProvider,+ selectedModel,+ requestedProvider.effort || null,+ );+ const localEndpoint = localEndpointOfProvider(provider);+ const localPromptBudget = localEndpoint+ ? planLocalPromptBudget({+ prompt,+ endpoint: localEndpoint,+ baseDurationMs: await import('./taskLearning.js')+ .then((tl) => tl.getTaskDurationEstimate(task.description, {+ providerId: provider.id,+ model: selectedModel,+ effort: taskEffort,+ }))+ .then((estimate) => estimate?.estimatedDurationMs ?? null)+ .catch(() => null),+ })+ : null;+ if (localPromptBudget?.longPrefill) {+ emitLog('info', `🐢 Agent ${agentId} ${describeLocalPromptBudget(localPromptBudget)}`, {+ agentId,+ taskId: task.id,+ promptTokens: localPromptBudget.promptTokens,+ });}- const { runId } = await createAgentRun({- agentId,- task,- model: selectedModel,- provider,- workspacePath,- appName: resolvedAppName,- injectedMemories,- });- await registerAgent(agentId, task.id, buildAgentRegistration({- task,- provider,- instanceId,- workspacePath,- sourceWorkspace,- repoIssueUrl: repoIssueUrlBase(forgeTarget),- primaryCheckoutBaseline,- auditSourceEvidence,- worktreeInfo,- explicitWorktree,- jiraBranchName,- providerEndpoint: providerBaseUrl(provider),- localPromptBudget,++ const executionMode = resolveExecutionMode({ spawnHeadless, useRunner: dispatchUseRunner });+ const sourceWorkspace = worktreeInfo+ ? (task.metadata?.app ? await getAppWorkspace(task.metadata.app) : ROOT_DIR)+ : null;+ const prOpenedBy = promptOpensOwnPr(task, {+ providerType: provider.type,+ providerId: provider.id,+ providerCommand: provider.command,leanMode,- prOpenedBy,- // Same decision that put merge admission in the prompt (#11435).- mergesOwnPr: promptTrace.mergesOwnPr === true,- claimFlowTask,- selectedModel,- effort: taskEffort,- modelSelection,- runId,- dispatchUseRunner,- executionMode,- publicReviewPosture,- resolvedAppName,- injectedMemories,- }));- return { runId };- });+ worktreeInfo,+ });+ const claimFlowTask = isClaimFlowTask(task);+ const [forgeTarget, primaryCheckoutBaseline, auditSourceEvidence] = await Promise.all([+ resolvedApp+ ? resolveAppForgeTarget(resolvedApp, { repoPath: workspacePath }).then(r => r.target)+ : resolveRepoForgeTarget(workspacePath),+ sourceWorkspace ? capturePrimaryCheckoutState(sourceWorkspace) : null,+ isAuditTaskType(resolveTaskHookType(task)) ? captureAuditSourceEvidence(workspacePath) : null,+ ]);+ const injectedMemories = promptTrace.injectedMemories || [];+ let systemPromptFile = null;+ const agentDir = join(AGENTS_DIR, agentId);+ const { runId } = await withBackupAssetPublication(async () => {+ if (!existsSync(agentDir)) {+ await ensureDir(agentDir);+ }+ await writeFileGuarded(join(agentDir, 'prompt.txt'), prompt);+ if (systemPrompt) {+ systemPromptFile = join(agentDir, 'system-prompt.md');+ await writeFileGuarded(systemPromptFile, systemPrompt);+ }+ const { runId } = await createAgentRun({+ agentId,+ task,+ model: selectedModel,+ provider,+ workspacePath,+ appName: resolvedAppName,+ injectedMemories,+ });+ await registerAgent(agentId, task.id, buildAgentRegistration({+ task,+ provider,+ instanceId,+ workspacePath,+ sourceWorkspace,+ repoIssueUrl: repoIssueUrlBase(forgeTarget),+ primaryCheckoutBaseline,+ auditSourceEvidence,+ worktreeInfo,+ explicitWorktree,+ jiraBranchName,+ providerEndpoint: providerBaseUrl(provider),+ localPromptBudget,+ leanMode,+ prOpenedBy,+ // Same decision that put merge admission in the prompt (#11435).+ mergesOwnPr: promptTrace.mergesOwnPr === true,+ claimFlowTask,+ selectedModel,+ effort: taskEffort,+ modelSelection,+ runId,+ dispatchUseRunner,+ executionMode,+ publicReviewPosture,+ resolvedAppName,+ injectedMemories,+ }));+ return { runId };+ });- emitLog('info', `Agent ${agentId} initializing...${worktreeInfo ? ' (worktree)' : ''}${jiraBranchName ? ` (JIRA: ${jiraTicket?.ticketId})` : ''}`, { agentId, taskId: task.id });- const newSpawnCount = (Number(task.metadata?.totalSpawnCount) || 0) + 1;- const updateResult = await updateTask(task.id, {- status: 'in_progress',- metadata: {- ...task.metadata,- totalSpawnCount: newSpawnCount,- lastSpawnedAt: new Date().toISOString(),- ...buildClaim(instanceId),- },- }, task.taskType || 'user')- .catch(err => {- console.error(`❌ Failed to mark task ${task.id} as in_progress: ${err.message}`);+ emitLog('info', `Agent ${agentId} initializing...${worktreeInfo ? ' (worktree)' : ''}${jiraBranchName ? ` (JIRA: ${jiraTicket?.ticketId})` : ''}`, { agentId, taskId: task.id });+ const newSpawnCount = (Number(task.metadata?.totalSpawnCount) || 0) + 1;+ const updateResult = await updateTask(task.id, {+ status: 'in_progress',+ metadata: {+ ...task.metadata,+ totalSpawnCount: newSpawnCount,+ lastSpawnedAt: new Date().toISOString(),+ ...buildClaim(instanceId),+ },+ }, task.taskType || 'user')+ .catch(err => {+ console.error(`❌ Failed to mark task ${task.id} as in_progress: ${err.message}`);+ return null;+ });+ if (updateResult?.error) {+ emitLog('warn', `⚠️ in_progress claim for task ${task.id} returned an error (taskType=${task.taskType}): ${updateResult.error}`, { taskId: task.id, error: updateResult.error });+ }+ if (!updateResult) {+ await context.cleanupOnError('Failed to update task status');return null;- });- if (updateResult?.error) {- emitLog('warn', `⚠️ in_progress claim for task ${task.id} returned an error (taskType=${task.taskType}): ${updateResult.error}`, { taskId: task.id, error: updateResult.error });- }- if (!updateResult) {- await context.cleanupOnError('Failed to update task status');- return null;- }+ }- if (task.metadata?.autonomousJob && task.metadata?.jobId) {- cosEvents.emit('job:spawned', { jobId: task.metadata.jobId });- }- const cliSettingsEnv = !publicReview && isClaudeCliProvider(provider)- ? await getClaudeSettingsEnv()- : {};- const maxConcurrentThreads = cloudSwarmThreadCapacity(runProvider, task.metadata?.swarmCount);- const safetyProfile = publicReview ? executionProfile : null;- const cliConfig = !spawnHeadless- ? buildTuiSpawnConfig(runProvider, selectedModel, { systemPromptFile, effort: taskEffort, maxConcurrentThreads, safetyProfile })- : buildCliSpawnConfig(runProvider, selectedModel, cliSettingsEnv, { systemPromptFile, effort: taskEffort, maxConcurrentThreads, safetyProfile });- const securityScanGrant = dispatchUseRunner && resolveTaskHookType(task) === 'security' && isCodexProvider(runProvider)- ? securityScanGrantFromArgs(cliConfig.args)- : null;- if (securityScanGrant) await updateAgent(agentId, { metadata: { securityScanGrant, taskAnalysisType: 'security' } });+ if (task.metadata?.autonomousJob && task.metadata?.jobId) {+ cosEvents.emit('job:spawned', { jobId: task.metadata.jobId });+ }+ const cliSettingsEnv = !publicReview && isClaudeCliProvider(provider)+ ? await getClaudeSettingsEnv()+ : {};+ const maxConcurrentThreads = cloudSwarmThreadCapacity(runProvider, task.metadata?.swarmCount);+ const safetyProfile = publicReview ? executionProfile : null;+ const cliConfig = !spawnHeadless+ ? buildTuiSpawnConfig(runProvider, selectedModel, { systemPromptFile, effort: taskEffort, maxConcurrentThreads, safetyProfile })+ : buildCliSpawnConfig(runProvider, selectedModel, cliSettingsEnv, { systemPromptFile, effort: taskEffort, maxConcurrentThreads, safetyProfile });+ const securityScanGrant = dispatchUseRunner && resolveTaskHookType(task) === 'security' && isCodexProvider(runProvider)+ ? securityScanGrantFromArgs(cliConfig.args)+ : null;+ if (securityScanGrant) await updateAgent(agentId, { metadata: { securityScanGrant, taskAnalysisType: 'security' } });- emitLog('success', `Spawning agent for task ${task.id}`, {- agentId,- model: selectedModel,- mode: executionMode,- cli: cliConfig.command,- lane: laneName,- worktree: !!worktreeInfo,- });+ emitLog('success', `Spawning agent for task ${task.id}`, {+ agentId,+ model: selectedModel,+ mode: executionMode,+ cli: cliConfig.command,+ lane: laneName,+ worktree: !!worktreeInfo,+ });- context.handedOff = true;- if (!spawnHeadless) {- return await spawnTuiAgent({+ context.handedOff = true;+ if (!spawnHeadless) {+ return await spawnTuiAgent({+ agentId,+ task,+ prompt,+ workspacePath,+ model: selectedModel,+ provider: runProvider,+ runId,+ tuiConfig: cliConfig,+ agentDir,+ executionId: toolExecution.id,+ laneName,+ leanMode,+ prOpenedBy,+ useDurableRunner: dispatchUseRunner,+ safetyProfile,+ securityScanGrant,+ });+ }+ if (dispatchUseRunner) {+ return await spawnViaRunner(agentId, task, { prompt, workspacePath, model: selectedModel, provider: runProvider, runId, cliConfig, executionId: toolExecution.id, laneName, securityScanGrant });+ }+ return await spawnDirectly({agentId,task,prompt,@@ -310,33 +332,12 @@ async function runAgentDispatch(context, { spawnViaRunner } = {}) {model: selectedModel,provider: runProvider,runId,- tuiConfig: cliConfig,+ cliConfig,agentDir,executionId: toolExecution.id,laneName,- leanMode,prOpenedBy,- useDurableRunner: dispatchUseRunner,safetyProfile,- securityScanGrant,});- }- if (dispatchUseRunner) {- return await spawnViaRunner(agentId, task, { prompt, workspacePath, model: selectedModel, provider: runProvider, runId, cliConfig, executionId: toolExecution.id, laneName, securityScanGrant });- }- return await spawnDirectly({- agentId,- task,- prompt,- workspacePath,- model: selectedModel,- provider: runProvider,- runId,- cliConfig,- agentDir,- executionId: toolExecution.id,- laneName,- prOpenedBy,- safetyProfile,- });+ } });}diff --git a/server/services/agentWorkspacePrep.js b/server/services/agentWorkspacePrep.jsindex c9b342e40b..20c60da282 100644--- a/server/services/agentWorkspacePrep.js+++ b/server/services/agentWorkspacePrep.js@@ -364,13 +364,13 @@ async function admitClaimContinuation({ task, agentId, sourceWorkspace, claimWor* @param {{ agentId: string, task: object }} params* @returns {Promise<object>} discriminated outcome (see module doc)*/-export async function prepareAgentWorkspace({ agentId, task }) {+export async function prepareAgentWorkspace({ agentId, task, onPrepared = result => result }) {if (isPrivateSecurityTask(task)) {const { privateSecurityScratchCwd } = await import('../lib/privateSecuritySandbox.js');const workspacePath = privateSecurityScratchCwd(agentId);await ensureDir(workspacePath);- return { outcome: 'ready', workspacePath, resolvedApp: null, resolvedAppName: null, worktreeInfo: null,- jiraTicket: null, jiraBranchName: null, explicitWorktree: false };+ return onPrepared({ outcome: 'ready', workspacePath, resolvedApp: null, resolvedAppName: null, worktreeInfo: null,+ jiraTicket: null, jiraBranchName: null, explicitWorktree: false });}// Creative Director treatment/plan/evaluate tasks are HTTP-PATCH deliverables@@ -392,7 +392,7 @@ export async function prepareAgentWorkspace({ agentId, task }) {emitLog('info', `📂 Agent workspace: ${workspacePath} (creative-director scratch)`, {taskId: task.id, workspace: workspacePath,});- return {+ return onPrepared({outcome: 'ready',workspacePath,resolvedApp: null,@@ -401,7 +401,7 @@ export async function prepareAgentWorkspace({ agentId, task }) {jiraTicket: null,jiraBranchName: null,explicitWorktree: false,- };+ });}// Pre-change investigation tasks may already be persisted without delivery@@ -443,7 +443,7 @@ export async function prepareAgentWorkspace({ agentId, task }) {+ `(The agent was not started, so it could not write into the PortOS directory by mistake.)`;emitLog('error', `❌ ${reason}`, { taskId: task.id });await blockTask(task, reason, 'app-unresolved');- return { outcome: 'blocked', reason };+ return onPrepared({ outcome: 'blocked', reason });}// Same resolver the /runs spawn paths use, so a `~/Projects/App` repoPath// expands here too and a repoPath pointing at a FILE is rejected up front@@ -462,9 +462,25 @@ export async function prepareAgentWorkspace({ agentId, task }) {// unusable, which is a different problem than a mis-configured app record —// don't file it under the app category.await blockTask(task, reason, task.metadata?.app ? 'app-unresolved' : 'workspace-invalid');- return { outcome: 'blocked', reason };+ return onPrepared({ outcome: 'blocked', reason });}+ const prepareAndRegister = async () => onPrepared(await prepareResolvedWorkspace({+ agentId, task, workspacePath, resolvedApp, resolvedAppName, isReadOnly,+ }));+ // Resolve once, then admit the entire preparation → registration → spawn+ // lifetime. A create/adopt helper's shorter permit cannot protect dependency+ // changes or an owner which has not yet been durably registered.+ const probe = await execGit(['rev-parse', '--is-inside-work-tree'], workspacePath, { ignoreExitCode: true });+ if (probe.stdout.trim() !== 'true') {+ if (probe.exitCode === 128 && /^fatal: not a git repository \(or any (?:of the parent directories|parent up to mount point)/im.test(probe.stderr || '')) return prepareAndRegister();+ throw new Error('Cannot establish workspace repository identity before dispatch');+ }+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(workspacePath, prepareAndRegister);+}++async function prepareResolvedWorkspace({ agentId, task, workspacePath, resolvedApp, resolvedAppName, isReadOnly }) {const remediationPin = resolveTaskPinnedHead(task.metadata);if (remediationPin !== null && (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(remediationPin)|| !resolveTaskRemoteBranch(task.metadata))) {diff --git a/server/services/agentWorkspacePrep.test.js b/server/services/agentWorkspacePrep.test.jsindex 84605e259a..7125f20f4c 100644--- a/server/services/agentWorkspacePrep.test.js+++ b/server/services/agentWorkspacePrep.test.js@@ -11,9 +11,15 @@import { describe, it, expect, beforeEach, vi } from 'vitest';+const publication = vi.hoisted(() => ({ active: false, refuse: false }));+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: vi.fn(async (_repo, work) => {+ if (publication.refuse) throw new Error('checkout-retirement-reserved');+ publication.active = true;+ try { return await work(); } finally { publication.active = false; }+}) }));vi.mock('./cosEvents.js', () => ({ emitLog: vi.fn() }));vi.mock('../lib/execGit.js', () => ({- execGit: vi.fn().mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 }),+ execGit: vi.fn().mockImplementation(async args => ({ stdout: args.includes('--is-inside-work-tree') ? 'true' : '', stderr: '', exitCode: 0 })),}));vi.mock('./cos.js', () => ({updateTask: vi.fn().mockResolvedValue({}),@@ -83,7 +89,7 @@ import { PINNED_HEAD_MOVED, createWorktree, adoptWorktree, findAdoptableWorktreeimport { ensureDir, PATHS } from '../lib/fileUtils.js';import { creativeDirectorScratchCwd } from '../lib/spawnCwd.js';-beforeEach(() => { vi.clearAllMocks(); listWorktrees.mockResolvedValue([]); });+beforeEach(() => { vi.clearAllMocks(); listWorktrees.mockResolvedValue([]); publication.active = publication.refuse = false; });describe('prepareAgentWorkspace — Creative Director scratch cwd (#4650)', () => {it('pins a CD no-worktree task to an isolated scratch dir and skips the git pull', async () => {@@ -1036,3 +1042,63 @@ describe('resolveTaskExistingBranch', () => {expect.objectContaining({ existingBranch: 'cos/task-x/agent-y' }));});});+++describe('durable workspace preparation and registration lifetime', () => {+ it('retains admission after ordinary creation until its registration continuation settles', async () => {+ let finish;+ const registration = new Promise(resolve => { finish = resolve; });+ createWorktree.mockImplementationOnce(async () => {+ expect(publication.active).toBe(true);+ return { worktreePath: '/mock/worktrees/new', branchName: 'cos/new' };+ });+ const onPrepared = vi.fn(async result => {+ expect(result.outcome).toBe('ready');+ expect(publication.active).toBe(true);+ await registration;+ expect(publication.active).toBe(true);+ return 'registered-and-spawned';+ });+ const result = prepareAgentWorkspace({ agentId: 'new', task: {+ id: 'new', metadata: { useWorktree: true },+ }, onPrepared });+ await vi.waitFor(() => expect(onPrepared).toHaveBeenCalledOnce());+ expect(publication.active).toBe(true);+ finish();+ expect(await result).toBe('registered-and-spawned');+ expect(publication.active).toBe(false);+ });++ it('refuses before ordinary preparation can mutate or call registration', async () => {+ publication.refuse = true;+ const onPrepared = vi.fn();+ await expect(prepareAgentWorkspace({ agentId: 'new', task: {+ id: 'new', metadata: { useWorktree: true },+ }, onPrepared })).rejects.toThrow('checkout-retirement-reserved');+ expect(createWorktree).not.toHaveBeenCalled();+ expect(ensureLatest).not.toHaveBeenCalled();+ expect(onPrepared).not.toHaveBeenCalled();+ });++ it('continues non-Git read-only tasks without a repository permit', async () => {+ execGit.mockResolvedValueOnce({ stdout: '', stderr: 'fatal: not a git repository (or any of the parent directories): .git', exitCode: 128 });+ const onPrepared = vi.fn(async result => {+ expect(publication.active).toBe(false);+ return result;+ });+ const result = await prepareAgentWorkspace({ agentId: 'docs', task: {+ id: 'docs', metadata: { readOnly: true },+ }, onPrepared });+ expect(result.outcome).toBe('ready');+ expect(onPrepared).toHaveBeenCalledOnce();+ });++ it.each(['fatal: permission denied', 'fatal: not a git repository: /broken/gitdir'])('does not treat an unreadable repository as non-Git: %s', async stderr => {+ execGit.mockResolvedValueOnce({ stdout: '', stderr, exitCode: 128 });+ const onPrepared = vi.fn();+ await expect(prepareAgentWorkspace({ agentId: 'new', task: { id: 'new', metadata: {} }, onPrepared }))+ .rejects.toThrow('Cannot establish workspace repository identity');+ expect(ensureLatest).not.toHaveBeenCalled();+ expect(onPrepared).not.toHaveBeenCalled();+ });+});diff --git a/server/services/appQualitySnapshotAdmission.test.js b/server/services/appQualitySnapshotAdmission.test.jsindex aa5a842625..d56b316e7d 100644--- a/server/services/appQualitySnapshotAdmission.test.js+++ b/server/services/appQualitySnapshotAdmission.test.js@@ -6,6 +6,8 @@ import { claimMergeAdmission } from './cosMergeAdmission.js';// The publisher's immediate merge shares the claim flow's REAL admission logic// over a synthetic runtime store: only the store and the git remote are doubled.const admissionState = vi.hoisted(() => ({ state: { agents: {}, mergeAdmissions: {} }, saveFails: false }));+// Workspace Git is synthetic here; keep the merge-admission boundary real.+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (_repo, work) => work() }));vi.mock('./cosState.js', async () => {const { createFileWriteQueue } = await import('../lib/fileWriteQueue.js');return {diff --git a/server/services/appQualitySnapshotFile.js b/server/services/appQualitySnapshotFile.jsindex ff6d4c25f3..c765485281 100644--- a/server/services/appQualitySnapshotFile.js+++ b/server/services/appQualitySnapshotFile.js@@ -421,7 +421,7 @@ async function landExistingBranchPr(app, git, defaultBranch, deps) {async function landSnapshotPr(app, { body, count, defaultBranch, git, deps, message, removeLegacy = false, remoteSha }) {const makeTemp = deps.mkdtemp || mkdtemp;- const worktreePath = await makeTemp(join(tmpdir(), 'portos-quality-'));+ let worktreePath;const addWorktree = deps.addWorktree || (async (args, repo) => {const { addWorktreeWithRetry } = await import('./worktreeManager.js');return addWorktreeWithRetry(args, repo);@@ -475,7 +475,11 @@ async function landSnapshotPr(app, { body, count, defaultBranch, git, deps, mess};};- return run().finally(() => cleanupSnapshotWorktree(app, git, worktreePath, removeTemp));+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(app.repoPath, async () => {+ worktreePath = await makeTemp(join(tmpdir(), 'portos-quality-'));+ return run().finally(() => cleanupSnapshotWorktree(app, git, worktreePath, removeTemp));+ });}const removeWorktreeRegistration = (git, repoPath, worktreePath) => gitdiff --git a/server/services/appQualitySnapshotFile.test.js b/server/services/appQualitySnapshotFile.test.jsindex 9d9c4e661e..d4fdbb81d3 100644--- a/server/services/appQualitySnapshotFile.test.js+++ b/server/services/appQualitySnapshotFile.test.js@@ -1,4 +1,6 @@import { it, expect, vi, beforeEach, afterEach } from 'vitest';+// Git/filesystem are synthetic in this suite; real durable admission has its own boundary tests.+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (_repo, work) => work() }));import { basename, join } from 'node:path';import {APP_QUALITY_SNAPSHOT_FILENAME, APP_QUALITY_SNAPSHOT_MAX_BYTES, QUALITY_SNAPSHOT_BRANCH,diff --git a/server/services/branchCompletionPolicy.test.js b/server/services/branchCompletionPolicy.test.jsindex dfe68e6b0c..62ec3a998a 100644--- a/server/services/branchCompletionPolicy.test.js+++ b/server/services/branchCompletionPolicy.test.js@@ -9,6 +9,8 @@ const runtime = vi.hoisted(() => ({ dir: null, agents: {}, trusted: true, tip: 'const repoPath = '/synthetic/repository';const branch = 'feature/handoff';const prUrl = 'https://github.com/example/repository/pull/42';+// Synthetic Git contracts do not create a filesystem repository.+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (_repo, work) => work() }));vi.mock('../lib/fileUtils.js', async () => ({...await vi.importActual('../lib/fileUtils.js'),PATHS: { root: '/synthetic/repository', data: '/synthetic/data', worktrees: '/synthetic/worktrees', get cos() { return runtime.dir; } },diff --git a/server/services/cosClaimOwnership.js b/server/services/cosClaimOwnership.jsindex e4e4bcec73..e49387776b 100644--- a/server/services/cosClaimOwnership.js+++ b/server/services/cosClaimOwnership.js@@ -104,12 +104,20 @@ export async function updateClaimOwnership({ agentId, action, branch }) {return ownershipTransaction(action === 'bind' ? 'bind' : 'release', done, async (state, save) => {const agent = state.agents?.[agentId];if (!agent || agent.id !== agentId) return { [done]: false, reason: 'owner-unknown' };- const patch = action === 'bind' ? bindClaimBranch(agent, branch, Object.values(state.agents)) : releaseClaimBranch(agent, branch);- if (patch.refused) return { [done]: false, reason: patch.refused };- state.agents[agentId] = { ...agent, metadata: { ...agent.metadata, ...patch } };- await save();- cosEvents.emit('agent:updated', state.agents[agentId]);- return { [done]: true, branch };+ const repoPath = agent.sourceWorkspace || agent.metadata?.sourceWorkspace || agent.workspacePath || agent.metadata?.workspacePath;+ if (!repoPath) return { [done]: false, reason: 'ownership-unreadable' };+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(repoPath, async () => {+ const patch = action === 'bind' ? bindClaimBranch(agent, branch, Object.values(state.agents)) : releaseClaimBranch(agent, branch);+ if (patch.refused) return { [done]: false, reason: patch.refused };+ state.agents[agentId] = { ...agent, metadata: { ...agent.metadata, ...patch } };+ await save();+ cosEvents.emit('agent:updated', state.agents[agentId]);+ return { [done]: true, branch };+ }).catch(error => {+ if (error.code === 'CHECKOUT_RETIREMENT_RESERVED') return { [done]: false, reason: 'checkout-retirement-reserved' };+ throw error;+ });});}@@ -159,12 +167,14 @@ export async function checkReconcileOwnership(input, deps = {}) {}) || claimCheckoutOwnerReason({ branchName: branch, holderPath: holder?.path || null, sourceWorkspace: repoPath, agents: others });return reason ? { admitted: false, reason } : { admitted: true };};- if (!agentId) return admit();+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ if (!agentId) return withCheckoutPublication(repoPath, admit)+ .catch(() => ({ admitted: false, reason: 'checkout-retirement-reserved' }));const { cosEvents } = await import('./cosEvents.js');// Decided inside the lock a bind takes, so no bind can land between// "admitted" and "reserved".- return ownershipTransaction('reserve', 'admitted', async (state, save) => {+ return ownershipTransaction('reserve', 'admitted', async (state, save) => withCheckoutPublication(repoPath, async () => {const admission = await admit();if (!admission.admitted) return admission;const agent = state.agents?.[agentId];@@ -176,7 +186,7 @@ export async function checkReconcileOwnership(input, deps = {}) {await save();cosEvents.emit('agent:updated', state.agents[agentId]);return admission;- });+ }).catch(() => ({ admitted: false, reason: 'checkout-retirement-reserved' })));}/** Read-only snapshot publication gate. Registered review work remains owneddiff --git a/server/services/cosClaimOwnership.test.js b/server/services/cosClaimOwnership.test.jsindex 9ec76065a9..93c5578b89 100644--- a/server/services/cosClaimOwnership.test.js+++ b/server/services/cosClaimOwnership.test.js@@ -1,4 +1,6 @@import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';+// Git/filesystem are synthetic in this suite; real durable admission has its own boundary tests.+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (_repo, work) => work() }));const store = { state: null, stateGate: null, readGate: null, saveGate: null, unreadable: false, stale: false };const deferred = () => {diff --git a/server/services/cosMergeAdmission.reviewCoordinator.test.js b/server/services/cosMergeAdmission.reviewCoordinator.test.jsindex 19ba4ac5fe..9791dd2636 100644--- a/server/services/cosMergeAdmission.reviewCoordinator.test.js+++ b/server/services/cosMergeAdmission.reviewCoordinator.test.js@@ -1,3 +1,4 @@+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: async (_repo, work) => work() }));import { beforeEach, describe, expect, it, vi } from 'vitest';import { createFileWriteQueue } from '../lib/fileWriteQueue.js';import { generateTasksMarkdown, parseTasksMarkdown } from '../lib/taskParser.js';@@ -29,7 +30,7 @@ vi.mock('./taskConflict.js', () => ({ detectConflicts: vi.fn() }));vi.mock('../lib/execGit.js', () => ({ execGit: async args => {let stdout;if (args[0] === 'symbolic-ref') stdout = f.branch;- if (args[0] === 'rev-parse') stdout = f.head;+ if (args[0] === 'rev-parse') stdout = args.includes('--is-inside-work-tree') ? 'true' : f.head;if (args[0] === 'remote') stdout = args.includes('--push') ? f.pushRemote : f.remote;if (args[0] === 'config') stdout = args[2].endsWith('.remote') ? f.upstream.remote : f.upstream.merge;if (typeof stdout !== 'string') throw new Error('unreadable git fixture');diff --git a/server/services/deepAudit.workspace.test.js b/server/services/deepAudit.workspace.test.jsindex 7d5e42aa6e..537f0c485d 100644--- a/server/services/deepAudit.workspace.test.js+++ b/server/services/deepAudit.workspace.test.js@@ -19,7 +19,7 @@ vi.mock('fs/promises', async original => {});vi.mock('../lib/execGit.js', async original => {const actual = await original();- return { execGit: (...args) => {+ return { ...actual, execGit: (...args) => {if (fault.rejectAdd && args[0][0] === 'worktree' && args[0][1] === 'add') throw new Error('Synthetic add failure');return actual.execGit(...args);} };diff --git a/server/services/git.commit.test.js b/server/services/git.commit.test.jsindex 3e62d430b1..f7074ba6a4 100644--- a/server/services/git.commit.test.js+++ b/server/services/git.commit.test.js@@ -1,3 +1,5 @@+// These command-contract fixtures use synthetic repositories; real admission is exercised in git.publication.test.js.+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (_dir, work) => work() }));import { describe, it, expect, vi, beforeEach } from 'vitest';vi.mock('../lib/execGit.js', () => {diff --git a/server/services/git.deleteMergedBranches.test.js b/server/services/git.deleteMergedBranches.test.jsindex 6f27ea2c2e..bd0f2ed163 100644--- a/server/services/git.deleteMergedBranches.test.js+++ b/server/services/git.deleteMergedBranches.test.js@@ -1,4 +1,6 @@import { beforeEach, describe, expect, it, vi } from 'vitest';+// Git/filesystem are synthetic in this suite; real durable admission has its own boundary tests.+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (_repo, work) => work() }));vi.mock('../lib/execGit.js', () => {const execGit = vi.fn();return { execGit, execGitSafe: (...args) => execGit(...args).catch(error => ({ exitCode: 1, stdout: '', stderr: error.message })) };diff --git a/server/services/git.fetchOrigin.test.js b/server/services/git.fetchOrigin.test.jsindex 3c3c0cb8ce..96f35f6841 100644--- a/server/services/git.fetchOrigin.test.js+++ b/server/services/git.fetchOrigin.test.js@@ -1,3 +1,5 @@+// Synthetic command fixtures; git.publication.test.js exercises the real repository fence.+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (_dir, work) => work() }));import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';const execGitMock = vi.hoisted(() => vi.fn());@@ -89,18 +91,23 @@ describe('getRemoteBranches fetch freshness window & deduplication', () => {it('deduplicates concurrent calls to getRemoteBranches for the same repo', async () => {let resolveFetch;+ let markFetchStarted;+ const fetchStarted = new Promise(resolve => { markFetchStarted = resolve; });const fetchPromise = new Promise(r => { resolveFetch = r; });execGitMock.mockImplementation((args) => {if (args[0] === 'fetch') {+ markFetchStarted();return fetchPromise.then(() => ({ stdout: '', stderr: '', exitCode: 0 }));}return Promise.resolve({ stdout: '', stderr: '', exitCode: 0 });});- // Launch two calls concurrently+ // Keep the first fetch pending while the second call passes its async admission.const p1 = getRemoteBranches('/repo-concurrent');+ await fetchStarted;const p2 = getRemoteBranches('/repo-concurrent');+ await vi.dynamicImportSettled();resolveFetch();await Promise.all([p1, p2]);diff --git a/server/services/git.js b/server/services/git.jsindex a3226aac7a..a64dc5e5aa 100644--- a/server/services/git.js+++ b/server/services/git.js@@ -134,6 +134,11 @@ export async function getDiffStats(dir) {* that exact file, and a crafted `*` can't expand to the whole tree.*/export async function stageFiles(dir, files) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => stageFilesAdmitted(dir, files));+}++async function stageFilesAdmitted(dir, files) {const safePaths = validateFilePaths(files).map(toLiteralPathspec);await execGit(['add', '--', ...safePaths], dir);return true;@@ -143,6 +148,11 @@ export async function stageFiles(dir, files) {* Unstage files (same literal-pathspec handling as stageFiles).*/export async function unstageFiles(dir, files) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => unstageFilesAdmitted(dir, files));+}++async function unstageFilesAdmitted(dir, files) {const safePaths = validateFilePaths(files).map(toLiteralPathspec);await execGit(['reset', 'HEAD', '--', ...safePaths], dir);return true;@@ -156,6 +166,11 @@ export async function unstageFiles(dir, files) {* Same `:(literal)` pathspec handling as stageFiles. Omitted = commit the index as-is.*/export async function commit(dir, message, { paths = [] } = {}) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => commitAdmitted(dir, message, { paths }));+}++async function commitAdmitted(dir, message, { paths = [] } = {}) {const pathspecs = paths.length ? ['--', ...validateFilePaths(paths).map(toLiteralPathspec)] : [];// Using spawn with -m argument passes message safely without shell interpretationconst result = await execGit(['commit', '-m', message, ...pathspecs], dir);@@ -257,7 +272,12 @@ function fetchOriginAttempt(dir, attempt, prune = false) {* @param {{prune?: boolean}} [opts] - `prune` also drops remote-tracking refs whose* remote branch is gone, for callers that go on to reason about what origin still has.*/-export function fetchOrigin(dir, { prune = false } = {}) {+export async function fetchOrigin(dir, { prune = false } = {}) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => fetchOriginAdmitted(dir, { prune }));+}++function fetchOriginAdmitted(dir, { prune = false } = {}) {return fetchOriginAttempt(dir, 1, prune);}@@ -267,6 +287,11 @@ export function fetchOrigin(dir, { prune = false } = {}) {* would swap files on disk and trigger HMR/server restarts).*/export async function updateBranches(dir) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => updateBranchesAdmitted(dir));+}++async function updateBranchesAdmitted(dir) {await fetchOrigin(dir);const status = await getStatus(dir);@@ -328,6 +353,11 @@ export async function getBranchComparison(dir, baseBranch = 'main', headBranch =* Push to origin*/export async function push(dir, branch = null) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => pushAdmitted(dir, branch));+}++async function pushAdmitted(dir, branch = null) {if (branch) assertSafeRef(branch);const args = branch ? ['push', 'origin', branch] : ['push'];const result = await execGit(args, dir);@@ -339,6 +369,11 @@ export async function push(dir, branch = null) {* Never uses --force. Returns per-branch results.*/export async function pushAll(dir) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => pushAllAdmitted(dir));+}++async function pushAllAdmitted(dir) {const allBranches = await getBranches(dir);const pushable = allBranches.filter(b => b.tracking && b.ahead > 0);@@ -370,6 +405,11 @@ export async function pushAll(dir) {* Create and switch to a new branch*/export async function createBranch(dir, branchName) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => createBranchAdmitted(dir, branchName));+}++async function createBranchAdmitted(dir, branchName) {await execGit(['checkout', '-b', branchName], dir);return { success: true, branch: branchName };}@@ -378,6 +418,11 @@ export async function createBranch(dir, branchName) {* Switch to an existing branch*/export async function checkout(dir, branchName) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => checkoutAdmitted(dir, branchName));+}++async function checkoutAdmitted(dir, branchName) {assertSafeRef(branchName);await execGit(['checkout', branchName], dir);return { success: true, branch: branchName };@@ -804,6 +849,11 @@ export async function getBranches(dir, { strict = false } = {}) {* Pull changes from remote for current branch*/export async function pull(dir) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => pullAdmitted(dir));+}++async function pullAdmitted(dir) {const result = await execGit(['pull', '--rebase', '--autostash'], dir).catch((err) => {// A rebase killed mid-flight can leave the repo in a rebase-in-progress// state, so a lock found here is cleared but NOT retried — blindly@@ -903,6 +953,11 @@ async function updatePinnedSubmodules(dir) {* @returns {Promise<{success: boolean, branch: string, output: string, conflict: boolean, rebased?: boolean, error?: string}>}*/export async function updateDefaultBranch(dir) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => updateDefaultBranchAdmitted(dir));+}++async function updateDefaultBranchAdmitted(dir) {// Git splits a failed pull across both streams — fetch progress and rebase// instructions on stderr, the `CONFLICT (content): …` lines naming the files// on stdout — so an `stderr || stdout` pick would drop exactly the part that@@ -1036,6 +1091,11 @@ export async function updateDefaultBranch(dir) {* Sync branch - pull then push*/export async function syncBranch(dir, branch = null) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => syncBranchAdmitted(dir, branch));+}++async function syncBranchAdmitted(dir, branch = null) {if (branch) assertSafeRef(branch);const currentBranch = branch || await getBranch(dir);@@ -1094,7 +1154,20 @@ export function hasChangelogDir(dir) {// FIRST agent's in-flight rebase.const ensureLatestTails = new Map();-export function ensureLatest(dir) {+export async function ensureLatest(dir) {+ const gitCheck = await execGit(['rev-parse', '--is-inside-work-tree'], dir, { ignoreExitCode: true });+ if (gitCheck.exitCode === 128+ && /^fatal: not a git repository \(or any (?:of the parent directories|parent up to mount point)/im.test(gitCheck.stderr || '')) {+ return { success: true, branch: null, conflict: false, error: null, skipped: 'not-a-repo' };+ }+ if (gitCheck.exitCode !== 0 || gitCheck.stdout.trim() !== 'true') {+ throw new Error(gitCheck.stderr?.trim() || 'Could not verify Git working tree');+ }+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => ensureLatestAdmitted(dir));+}++function ensureLatestAdmitted(dir) {const key = resolve(dir);const prev = ensureLatestTails.get(key) || Promise.resolve();const run = prev.catch(() => {}).then(() => ensureLatestUnserialized(dir));@@ -1150,9 +1223,6 @@ function summarizeRebaseConflict({ stdout = '', stderr = '' } = {}) {}async function ensureLatestUnserialized(dir) {- const gitCheck = await isRepo(dir).catch(() => false);- if (!gitCheck) return { success: true, branch: null, conflict: false, error: null, skipped: 'not-a-repo' };-// A rebase left in progress is someone's (a person's, or an agent resolving a// conflict) — never start a second one on top of it, and never abort it.if (await rebaseInProgress(dir)) {@@ -1271,22 +1341,25 @@ async function ensureLatestUnserialized(dir) {export async function getRemoteBranches(dir, { force = false } = {}) {// Fetch latest refs if forced or not fresh within windowif (force || !isFetchFresh(dir)) {- if (activeFetches.has(dir)) {- await activeFetches.get(dir);- } else {- const fetchPromise = execGit(['fetch', 'origin', '--prune'], dir, { ignoreExitCode: true })- .then(res => {- if (res.exitCode === 0 || isBenignConcurrentFetchRefRace(res.stderr || res.stdout || '')) {- recordFetchSuccess(dir);- }- return res;- })- .finally(() => {- activeFetches.delete(dir);- });- activeFetches.set(dir, fetchPromise);- await fetchPromise;- }+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ await withCheckoutPublication(dir, async () => {+ if (activeFetches.has(dir)) {+ await activeFetches.get(dir);+ } else {+ const fetchPromise = execGit(['fetch', 'origin', '--prune'], dir, { ignoreExitCode: true })+ .then(res => {+ if (res.exitCode === 0 || isBenignConcurrentFetchRefRace(res.stderr || res.stdout || '')) {+ recordFetchSuccess(dir);+ }+ return res;+ })+ .finally(() => {+ activeFetches.delete(dir);+ });+ activeFetches.set(dir, fetchPromise);+ await fetchPromise;+ }+ });}// Detect default branch@@ -1360,7 +1433,12 @@ export async function getWorktreeBranches(dir) {* @param {boolean} options.remote - Delete remote branch* @param {Set<string>} options.excludeBranches - Additional branches to protect (e.g., active agent branches)*/-export async function deleteBranch(dir, branchName, { local = false, remote = false, excludeBranches } = {}) {+export async function deleteBranch(dir, branchName, options = {}) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => deleteBranchAdmitted(dir, branchName, options));+}++async function deleteBranchAdmitted(dir, branchName, { local = false, remote = false, excludeBranches } = {}) {const { baseBranch } = await getRepoBranches(dir);const protectedSet = new Set(PROTECTED_BRANCHES);if (baseBranch) protectedSet.add(baseBranch);@@ -1418,6 +1496,11 @@ export async function deleteBranch(dir, branchName, { local = false, remote = fa* @returns {Promise<{success: boolean, output: string}>}*/export async function mergeBranch(dir, branchName) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => mergeBranchAdmitted(dir, branchName));+}++async function mergeBranchAdmitted(dir, branchName) {assertSafeRef(branchName);const result = await execGit(['merge', '--no-ff', branchName], dir);return { success: true, output: (result.stdout + result.stderr).trim() };@@ -1493,6 +1576,8 @@ export async function hasBranchMergeEvidence(dir, branch, target) {// Write a synthetic commit object with the branch's full tree atop the merge base.// commit-tree uses the repo's configured identity; if that's unset it fails and// no merge evidence is established (the worktree is preserved).+ // This immutable object addition moves no refs or checkout state. A concurrent+ // complete-checkout archive still refuses if its exact common-store snapshot drifts.const synthesized = await execGit(['commit-tree', branchTree, '-p', mergeBase, '-m', 'merged-check-probe'], dir, { ignoreExitCode: true }).then(r => (r.exitCode === 0 ? r.stdout.trim() : null)).catch(() => null);@@ -1517,6 +1602,11 @@ export const isBranchMergedInto = hasBranchMergeEvidence;* @returns {Promise<{success: boolean, branch: string}>}*/export async function checkoutRemoteBranch(dir, branchName) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => checkoutRemoteBranchAdmitted(dir, branchName));+}++async function checkoutRemoteBranchAdmitted(dir, branchName) {assertSafeRef(branchName);await execGit(['checkout', '-b', branchName, `origin/${branchName}`], dir);return { success: true, branch: branchName };@@ -1639,6 +1729,11 @@ export async function findActiveAgentInWorkspace(dir, { includePaused = false, f* fetched: boolean}>}*/export async function resetToDefaultBranch(dir) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(dir, () => resetToDefaultBranchAdmitted(dir));+}++async function resetToDefaultBranchAdmitted(dir) {// A linked worktree cannot check out the default branch — the main checkout// already holds it — and hard-resetting one would discard an agent's// in-flight work on a branch that is not the default anyway. Fail with adiff --git a/server/services/git.publication.test.js b/server/services/git.publication.test.jsnew file mode 100644index 0000000000..0b1498e63f--- /dev/null+++ b/server/services/git.publication.test.js@@ -0,0 +1,126 @@+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { mkdir, readFile, writeFile } from 'node:fs/promises';+import { join } from 'node:path';++// Observe real command completion to attempt a retirement between pull and push.+const observation = vi.hoisted(() => ({ afterCommand: null }));+vi.mock('../lib/execGit.js', async importOriginal => {+ const actual = await importOriginal();+ return {+ ...actual,+ execGit: async (...args) => {+ const result = await actual.execGit(...args);+ await observation.afterCommand?.(...args);+ return result;+ }+ };+});+import { execGit } from '../lib/execGit.js';+import { makeGitSandbox, destroyGitSandbox } from '../lib/gitTestRepo.js';+import { reserveCheckoutRetirement, releaseCheckoutReservation, withCheckoutPublication } from '../lib/checkoutRetirementAdmission.js';+import {+ stageFiles, unstageFiles, commit, updateBranches, checkout, pull, syncBranch,+ mergeBranch, checkoutRemoteBranch, resetToDefaultBranch,+ createBranch, fetchOrigin, push, pushAll, updateDefaultBranch, ensureLatest, getRemoteBranches+} from './git.js';++let fixture;+let linked;+beforeEach(async () => {+ fixture = await makeGitSandbox({ origin: true, prefix: 'git-publication-' });+ linked = join(fixture.scratch, 'linked');+ await execGit(['worktree', 'add', '-b', 'feature', linked], fixture.repo);+});+afterEach(async () => {+ observation.afterCommand = null;+ await destroyGitSandbox(fixture?.scratch);+});++async function checkoutState(dir) {+ const index = (await execGit(['rev-parse', '--path-format=absolute', '--git-path', 'index'], dir)).stdout.trim();+ return {+ index: await readFile(index),+ head: (await execGit(['rev-parse', 'HEAD'], dir)).stdout,+ branch: (await execGit(['symbolic-ref', 'HEAD'], dir)).stdout,+ refs: (await execGit(['show-ref'], dir)).stdout,+ status: (await execGit(['--no-optional-locks', 'status', '--porcelain'], dir)).stdout,+ contents: await readFile(join(dir, 'initial.txt'), 'utf8')+ };+}++describe('Git service publication fencing', () => {+ it('keeps genuine non-Git prep as a no-op while refusing missing or malformed repositories', async () => {+ const plain = join(fixture.scratch, 'plain');+ await mkdir(plain);+ await expect(ensureLatest(plain)).resolves.toMatchObject({ success: true, skipped: 'not-a-repo' });+ await expect(ensureLatest(join(fixture.scratch, 'missing'))).rejects.toThrow();+ await writeFile(join(plain, '.git'), 'gitdir: missing-administration\n');+ await expect(ensureLatest(plain)).rejects.toThrow(/not a git repository|gitfile does not point to a valid repository/);+ });++ it('preserves both checkout indexes, contents and refs while a linked-checkout retirement is reserved', async () => {+ for (const dir of [fixture.repo, linked]) {+ await writeFile(join(dir, 'initial.txt'), 'staged work\n');+ await execGit(['add', 'initial.txt'], dir);+ await writeFile(join(dir, 'initial.txt'), 'unstaged work\n');+ }+ const before = await Promise.all([fixture.repo, linked].map(checkoutState));+ const cut = await reserveCheckoutRetirement(linked, 'retained-checkout');+ try {+ const writers = [+ dir => stageFiles(dir, ['initial.txt']),+ dir => unstageFiles(dir, ['initial.txt']),+ dir => commit(dir, 'must remain uncommitted'),+ updateBranches,+ dir => checkout(dir, 'main'),+ pull,+ dir => syncBranch(dir, 'main'),+ dir => mergeBranch(dir, 'main'),+ dir => checkoutRemoteBranch(dir, 'main'),+ resetToDefaultBranch,+ dir => createBranch(dir, 'must-not-exist'),+ fetchOrigin,+ push,+ pushAll,+ updateDefaultBranch,+ ensureLatest,+ dir => getRemoteBranches(dir, { force: true })+ ];+ for (const dir of [fixture.repo, linked]) {+ for (const writer of writers) {+ await expect(writer(dir)).rejects.toMatchObject({ code: 'CHECKOUT_RETIREMENT_RESERVED' });+ }+ }+ expect(await Promise.all([fixture.repo, linked].map(checkoutState))).toEqual(before);+ } finally {+ await releaseCheckoutReservation(cut);+ }+ await stageFiles(linked, ['initial.txt']);+ expect((await execGit(['show', ':initial.txt'], linked)).stdout).toBe('unstaged work\n');+ });++ it('keeps the publication across the complete pull-and-push sync operation', async () => {+ const phases = [];+ observation.afterCommand = async args => {+ if (!['pull', 'push'].includes(args[0])) return;+ phases.push(args[0]);+ await expect(reserveCheckoutRetirement(linked, 'mid-sync-cut')).rejects.toThrow('checkout-retirement-reserved');+ };+ await expect(syncBranch(fixture.repo, 'main')).resolves.toMatchObject({ success: true, pulled: true, pushed: true });+ expect(phases).toEqual(['pull', 'push']);+ const cut = await reserveCheckoutRetirement(linked, 'after-sync-cut');+ await releaseCheckoutReservation(cut);+ });++ it('supports nested service writers without releasing their enclosing repository publication', async () => {+ await withCheckoutPublication(fixture.repo, async () => {+ await writeFile(join(linked, 'initial.txt'), 'nested publication\n');+ await stageFiles(linked, ['initial.txt']);+ await commit(linked, 'nested publication');+ await expect(reserveCheckoutRetirement(linked, 'nested-cut')).rejects.toThrow('checkout-retirement-reserved');+ });+ expect((await execGit(['show', 'HEAD:initial.txt'], linked)).stdout).toBe('nested publication\n');+ const cut = await reserveCheckoutRetirement(linked, 'completed-cut');+ await releaseCheckoutReservation(cut);+ });+});diff --git a/server/services/git.resetToDefault.test.js b/server/services/git.resetToDefault.test.jsindex 44c331da13..e480a7b197 100644--- a/server/services/git.resetToDefault.test.js+++ b/server/services/git.resetToDefault.test.js@@ -1,3 +1,5 @@+// These command-contract fixtures use synthetic repositories; real admission is exercised in git.publication.test.js.+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (_dir, work) => work() }));/*** Tests for the "reset to origin's default branch" escape hatch behind the* Apps → Git tab button.diff --git a/server/services/git.staleLock.test.js b/server/services/git.staleLock.test.jsindex 7476e51f2f..2290dfba78 100644--- a/server/services/git.staleLock.test.js+++ b/server/services/git.staleLock.test.js@@ -1,3 +1,5 @@+// These command-contract fixtures use synthetic repositories; real admission is exercised in git.publication.test.js.+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (_dir, work) => work() }));import { beforeEach, describe, expect, it, vi } from 'vitest';const execGitMock = vi.hoisted(() => vi.fn());diff --git a/server/services/git.submodules.test.js b/server/services/git.submodules.test.jsindex bdcb1849cc..902d3dba32 100644--- a/server/services/git.submodules.test.js+++ b/server/services/git.submodules.test.js@@ -2,6 +2,8 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';// Drive updateSubmodule off a scripted git, so the test asserts the exact// command sequence (and the commit guard) rather than re-implementing it.+// Synthetic Git contracts do not create a filesystem repository.+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (_repo, work) => work() }));vi.mock('../lib/execGit.js', () => {const execGit = vi.fn();return {diff --git a/server/services/git.updateDefaultBranch.test.js b/server/services/git.updateDefaultBranch.test.jsindex 0b60ec42b2..1d109f80db 100644--- a/server/services/git.updateDefaultBranch.test.js+++ b/server/services/git.updateDefaultBranch.test.js@@ -1,3 +1,5 @@+// Synthetic command fixtures; git.publication.test.js exercises the real repository fence.+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (_dir, work) => work() }));import { beforeEach, describe, expect, it, vi } from 'vitest';const execGitMock = vi.hoisted(() => vi.fn());diff --git a/server/services/heldCheckoutRecovery.js b/server/services/heldCheckoutRecovery.jsindex d4ac76189c..be15a5a6f4 100644--- a/server/services/heldCheckoutRecovery.js+++ b/server/services/heldCheckoutRecovery.js@@ -303,9 +303,10 @@ async function writeArchive(dir, { repoPath, tree, branch, defaultBranch, releas// A bundle keeps the original commit objects, merges included, which a// squash-merged branch would otherwise lose to garbage collection.const bundle = join(dir, 'commits.bundle');- // Private reflogs and operation files may name commits no longer reachable- // from HEAD. Preserve their objects too, not just text that later GC would- // make useless. Unknown/missing recovery objects hold the checkout.+ // Private refs and operation files can name any Git object: ort's AUTO_MERGE+ // names a tree containing conflict-resolution evidence, not a commit.+ // Named bundle roots preserve their reachable objects too. Unknown/missing+ // recovery objects still hold the checkout.const recoveryHeads = new Set([tree.head]);for (const file of administration.files) {if (file.path === 'git-indirection' || /\/(index|gitdir|commondir|locked)$/.test(file.path)) continue;@@ -320,7 +321,7 @@ async function writeArchive(dir, { repoPath, tree, branch, defaultBranch, releastry {for (const head of recoveryHeads) {const type = (await git(['cat-file', '-t', head], repoPath)).trim();- if (type !== 'commit') throw new Error('private recovery object is not a commit');+ if (!['commit', 'tree', 'blob', 'tag'].includes(type)) throw new Error('private recovery object has an unsupported type');const ref = `${namespace}/${head}`;await git(['update-ref', ref, head, ''], repoPath);recoveryRefs.push({ ref, head });@@ -363,6 +364,7 @@ async function writeArchive(dir, { repoPath, tree, branch, defaultBranch, releascaptured: { commitBundle: true, recoveryHeads: [...recoveryHeads], ...(snapshot.missingCheckout ? { missingCheckout: true } : {}), gitlinks: snapshot.gitlinks, indexDiff: Boolean(snapshot.indexDiff), worktreeDiff: Boolean(snapshot.worktreeDiff), files, symlinks },restore: ['git -C <repo> fetch commits.bundle HEAD:refs/heads/<restored-branch>',+ 'git -C <repo> fetch commits.bundle "+refs/portos/archive/*:refs/portos/recovered/*"',`git -C <repo> worktree add <checkout> ${tree.head}`,snapshot.indexDiff ? 'git -C <checkout> apply --index index.diff' : null,snapshot.worktreeDiff ? 'git -C <checkout> apply worktree.diff' : null,@@ -412,6 +414,20 @@ async function matchRelease(repoPath, release) {return { tree };}+/** Shared live policy/owner check for the explicit whole-checkout transaction.+ * It does not archive, unlock or infer integration.+ */+export async function inspectCheckoutRetirementOwnership({ repoPath, release, registration = true }, opts = {}) {+ if (!release.branch || PROTECTED_BRANCHES.includes(release.branch)) return { ok: false, reason: 'protected-branch' };+ const matched = registration ? await matchRelease(repoPath, release) : { tree: release };+ if (!matched.tree) return { ok: false, reason: matched.reason };+ const reason = await ownerReason({ repoPath, tree: matched.tree, branch: release.branch,+ readAgents: opts.readAgents || readClaimOwnershipAgents, reviewed: true });+ if (reason) return { ok: false, reason };+ const policy = await retirementPolicy(repoPath, release.branch, opts);+ return policy.reason ? { ok: false, reason: policy.reason } : { ok: true, tree: matched.tree, policy };+}+/*** Archive and retire one held checkout under an operator's scoped release.*diff --git a/server/services/heldCheckoutRecovery.test.js b/server/services/heldCheckoutRecovery.test.jsindex c294609791..32f5b934b8 100644--- a/server/services/heldCheckoutRecovery.test.js+++ b/server/services/heldCheckoutRecovery.test.js@@ -5,7 +5,7 @@* its lock and its branch as found.*/import { describe, it, expect, beforeEach, afterEach, afterAll, vi } from 'vitest';-import { mkdtemp, mkdir, rm, writeFile, readFile, readdir, symlink, utimes } from 'fs/promises';+import { mkdtemp, mkdir, rm, rename, writeFile, readFile, readdir, symlink, utimes } from 'fs/promises';import { existsSync, realpathSync } from 'fs';import { tmpdir } from 'os';import { join } from 'path';@@ -137,6 +137,57 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()expect(await saved.verify(tree)).toBe(null);});+ it('recovers AUTO_MERGE trees and private blob/tag roots without the original object store', async () => {+ const path = join(external, 'private-objects');+ await execGit(['worktree', 'add', '-b', 'feature/private-objects', path, 'main'], repo);+ await writeFile(join(path, 'conflict.txt'), '<<<<<<< ours\nprivate conflict bytes\n=======\nother side\n>>>>>>> theirs\n');+ await execGit(['add', 'conflict.txt'], path);+ const autoMerge = (await execGit(['write-tree'], path)).stdout.trim();+ const conflictBlob = (await execGit(['rev-parse', ':conflict.txt'], path)).stdout.trim();+ await execGit(['tag', '-a', 'temporary-tree-tag', autoMerge, '-m', 'private tree evidence'], path);+ const tag = (await execGit(['rev-parse', 'refs/tags/temporary-tree-tag'], path)).stdout.trim();+ await execGit(['tag', '-d', 'temporary-tree-tag'], path);+ await execGit(['reset', '--hard', 'main'], path);+ await writeFile(join(path, 'blob-source'), 'private root blob bytes');+ const blob = (await execGit(['hash-object', '-w', 'blob-source'], path)).stdout.trim();+ await rm(join(path, 'blob-source'));+ const admin = (await execGit(['rev-parse', '--absolute-git-dir'], path)).stdout.trim();+ await writeFile(join(admin, 'AUTO_MERGE'), `${autoMerge}\n`);+ await execGit(['update-ref', 'refs/worktree/private-blob', blob], path);+ await execGit(['update-ref', 'refs/worktree/private-tag', tag], path);+ const tree = { path, branch: 'refs/heads/feature/private-objects', head: (await execGit(['rev-parse', 'HEAD'], path)).stdout.trim() };+ const saved = await preserveMergedCheckout(repo, tree, 'main', { cosDir });+ const manifest = JSON.parse(await readFile(join(saved.archiveDir, 'manifest.json'), 'utf8'));+ expect(manifest.captured.recoveryHeads).toEqual(expect.arrayContaining([autoMerge, blob, tag]));+ expect(await readFile(join(saved.archiveDir, 'administration', 'gitdir', 'AUTO_MERGE'), 'utf8')).toBe(`${autoMerge}\n`);+ expect(await saved.verify(tree)).toBe(null);+ // The archive must supply the conflict tree's children, not just list roots+ // whose missing bytes happen to be available from the original repository.+ await rename(repo, `${repo}-unavailable`);+ const restored = join(scratch, 'restored-private-objects');+ await execGit(['init', '--bare', restored], scratch);+ await execGit(['fetch', join(saved.archiveDir, 'commits.bundle'), '+refs/portos/archive/*:refs/recovered/*'], restored);+ expect((await execGit(['show', `${autoMerge}:conflict.txt`], restored)).stdout).toContain('private conflict bytes');+ expect((await execGit(['cat-file', 'blob', conflictBlob], restored)).stdout).toContain('>>>>>>> theirs');+ expect((await execGit(['cat-file', 'blob', blob], restored)).stdout).toBe('private root blob bytes');+ expect((await execGit(['rev-parse', `${tag}^{tree}`], restored)).stdout.trim()).toBe(autoMerge);+ await execGit(['fsck', '--full', '--strict'], restored);+ });++ it('retains the checkout when an AUTO_MERGE recovery tree is missing', async () => {+ const path = join(external, 'missing-auto-merge');+ await execGit(['worktree', 'add', '-b', 'feature/missing-auto-merge', path, 'main'], repo);+ const admin = (await execGit(['rev-parse', '--absolute-git-dir'], path)).stdout.trim();+ const missing = 'f'.repeat(40);+ await writeFile(join(admin, 'AUTO_MERGE'), `${missing}\n`);+ const tree = { path, branch: 'refs/heads/feature/missing-auto-merge', head: (await execGit(['rev-parse', 'HEAD'], path)).stdout.trim() };+ await expect(preserveMergedCheckout(repo, tree, 'main', { cosDir })).rejects.toThrow();+ expect(existsSync(path)).toBe(true);+ expect(await readFile(join(admin, 'AUTO_MERGE'), 'utf8')).toBe(`${missing}\n`);+ expect(await archives()).toEqual([]);+ expect((await execGit(['for-each-ref', '--format=%(refname)', 'refs/portos/archive'], repo)).stdout).toBe('');+ });+it.each([false, true])('archives a missing checkout private index and staged contents before pruning, parentAlias=%s', async parentAlias => {const path = join(external, 'missing');await execGit(['worktree', 'add', '-b', 'feature/missing', path, 'main'], repo);@@ -447,7 +498,7 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()expect((await execGit(['rev-parse', c.release.branch], repo)).stdout.trim()).toBe(c.release.head);expect(existsSync(join(repo, '.git', 'FETCH_HEAD'))).toBe(false);expect(await c.confirm(before.review)).toMatchObject({ ok: false, reason: 'retirement-review-changed' });- expect(await lockText(c.path)).toBe(c.release.lockReason);+ expect(await lockText(c.release.path)).toBe(c.release.lockReason);expect(await archives()).toEqual([]);expect(await readFile(join(c.path, 'ignored.txt'), 'utf8')).toBe('ignored work\n');});diff --git a/server/services/heldCheckoutReview.js b/server/services/heldCheckoutReview.jsindex 3ad9cf2025..f883e9a2c3 100644--- a/server/services/heldCheckoutReview.js+++ b/server/services/heldCheckoutReview.js@@ -10,7 +10,7 @@ const oid = value => typeof value === 'string' && /^[a-f0-9]{40}(?:[a-f0-9]{24})const safePath = value => typeof value === 'string' && value.length > 0 && !value.includes('\0') && !value.startsWith('/') && !value.split('/').some(part => part === '..' || part === '.');const git = (args, cwd) => execGit(args, cwd, { maxBuffer: 4 * 1024 * 1024 }).then(r => r.stdout);-export async function readRetirementForgeEvidence(repoPath, branch, prUrl, { forgeAccount = null } = {}) {+export async function readRetirementForgeEvidence(repoPath, branch, prUrl, { forgeAccount = null, exactAliasHead = null } = {}) {const origin = await getOriginInfo(repoPath);const parsed = parsePullRequestUrl(prUrl);if (!origin || !parsed || parsed.host !== origin.host || `${parsed.owner}/${parsed.repo}` !== origin.fullName) {@@ -23,7 +23,10 @@ export async function readRetirementForgeEvidence(repoPath, branch, prUrl, { forconst remote = await read(['pr', 'view', prUrl, '--json', 'url,state,headRefName,headRefOid,isCrossRepository,mergeCommit,baseRefName']);const repository = await api(`repos/${origin.fullName}`);const defaultBranch = repository.default_branch;- if (remote.url !== prUrl || remote.state !== 'MERGED' || remote.headRefName !== branch+ // Explicit whole-checkout review may name a local repair alias, but only+ // when its exact tip is the merged PR head. Similar names are never evidence.+ const alias = remote.headRefName !== branch && oid(exactAliasHead) && exactAliasHead === remote.headRefOid;+ if (remote.url !== prUrl || remote.state !== 'MERGED' || (remote.headRefName !== branch && !alias)|| remote.isCrossRepository !== false || remote.baseRefName !== defaultBranch || !oid(remote.headRefOid) || !oid(remote.mergeCommit?.oid)) {throw new Error('retirement-pr-not-matching-merged');}@@ -60,8 +63,12 @@ export async function readRetirementForgeEvidence(repoPath, branch, prUrl, { forconst remoteHead = (await git(['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], repoPath).catch(() => { throw new Error('retirement-remote-ref-unreadable'); })).trim();if (remoteHead && remoteHead !== `${remote.headRefOid}\trefs/heads/${branch}`) throw new Error('retirement-remote-head-changed');+ const publishedRemoteHead = alias ? (await git(['ls-remote', '--heads', 'origin', `refs/heads/${remote.headRefName}`], repoPath)+ .catch(() => { throw new Error('retirement-remote-ref-unreadable'); })).trim() : null;+ if (publishedRemoteHead && publishedRemoteHead !== `${remote.headRefOid}\trefs/heads/${remote.headRefName}`) throw new Error('retirement-remote-head-changed');return { repository: `${origin.host}/${origin.fullName}`, prUrl, prHead: remote.headRefOid,- mergeCommit: remote.mergeCommit.oid, changedPaths, changeBase, firstCommit, defaultBranch, defaultHead: target.object.sha, remoteHead: remoteHead || null };+ mergeCommit: remote.mergeCommit.oid, changedPaths, changeBase, firstCommit, defaultBranch, defaultHead: target.object.sha, remoteHead: remoteHead || null,+ ...(alias ? { exactAliasHead, publishedBranch: remote.headRefName, publishedRemoteHead: publishedRemoteHead || null } : {}) };}/** Returned differences are review material, not executable instructions or andiff --git a/server/services/heldCheckoutReview.test.js b/server/services/heldCheckoutReview.test.jsindex a090170261..87ca1c6130 100644--- a/server/services/heldCheckoutReview.test.js+++ b/server/services/heldCheckoutReview.test.js@@ -44,6 +44,17 @@ describe('retirement forge verification', () => {await expect(readRetirementForgeEvidence('/synthetic/repo', 'claim/42', prUrl)).rejects.toThrow('retirement-pr-not-matching-merged');});+ it('accepts a local repair alias only with exact merged head proof', async () => {+ const evidence = await readRetirementForgeEvidence('/synthetic/repo', 'repair/42', prUrl, { exactAliasHead: pr.headRefOid });+ expect(evidence).toMatchObject({ exactAliasHead: pr.headRefOid, publishedBranch: 'claim/42', publishedRemoteHead: null });+ await expect(readRetirementForgeEvidence('/synthetic/repo', 'repair/42', prUrl, { exactAliasHead: 'e'.repeat(40) }))+ .rejects.toThrow('retirement-pr-not-matching-merged');+ mock.git.mockImplementation(async args => ({ exitCode: 0, stdout: args.at(-1) === 'refs/heads/claim/42'+ ? `${'f'.repeat(40)}\trefs/heads/claim/42\n` : '' }));+ await expect(readRetirementForgeEvidence('/synthetic/repo', 'repair/42', prUrl, { exactAliasHead: pr.headRefOid }))+ .rejects.toThrow('retirement-remote-head-changed');+ });+it('includes renamed previous paths and complete paginated file scope literally', async () => {detail.changed_files = 2;files = [[{ filename: ':(exclude)*', previous_filename: 'old.txt', status: 'renamed' }], [{ filename: 'new.txt', status: 'added' }]];diff --git a/server/services/initializedCheckoutRecovery.js b/server/services/initializedCheckoutRecovery.jsnew file mode 100644index 0000000000..8db7f989a7--- /dev/null+++ b/server/services/initializedCheckoutRecovery.js@@ -0,0 +1,424 @@+/**+ * Explicit initialized-private-module retirement. Original directories are+ * quarantined whole, never unlinked. Immutable journal steps and a durable+ * repository reservation survive an interrupted request or server restart.+ */+import { spawn } from '../lib/childProcess.js';+import { createHash, randomUUID } from 'node:crypto';+import { lstat, mkdir, open, readFile, readdir } from 'node:fs/promises';+import { join } from 'node:path';+import { type as hostOsType } from 'node:os';+import { fileURLToPath } from 'node:url';+import { PATHS } from '../lib/paths.js';+import { execGit } from '../lib/execGit.js';+import { assertNotRealDataWrite } from '../lib/testDataIsolation.js';+import { withClaimOwnershipLock } from './cosClaimOwnershipState.js';++const helper = fileURLToPath(new URL('../../scripts/lib/initialized_checkout_archive.py', import.meta.url));+const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');+const fail = reason => { throw new Error(reason); };+const sameRelease = (a, b) => ['path', 'head', 'branch', 'locked', 'lockReason'].every(key => (a[key] ?? null) === (b[key] ?? null));+const transactionRoot = () => join(PATHS.cos, 'initialized-checkout-retirements');++/** Native helper holds its own flock until the actual child exits. */+function runInitializedCheckoutNative(input, { keepOpen = false } = {}) {+ if (process.platform !== 'darwin') return Promise.reject(new Error('retirement-platform-unsupported'));+ return new Promise((resolve, reject) => {+ const child = spawn('/usr/bin/python3', [helper], { stdio: ['pipe', 'pipe', 'pipe'], env: {+ PATH: process.env.PATH, HOME: process.env.HOME, TMPDIR: process.env.TMPDIR,+ PYTHONDONTWRITEBYTECODE: '1',+ } });+ let output = '';+ let failure = null;+ let acquired = false;+ let closed = false;+ let escalation;+ const stop = error => {+ failure ||= error;+ child.kill('SIGTERM');+ escalation ||= setTimeout(() => child.kill('SIGKILL'), 5000);+ };+ const timer = setTimeout(() => stop(new Error('retirement-native-timeout')), keepOpen ? 30_000 : 20 * 60_000);+ const exited = new Promise(done => child.once('close', done));+ child.on('error', error => { failure = error; });+ child.on('close', code => {+ closed = true;+ clearTimeout(timer);+ clearTimeout(escalation);+ if (keepOpen && acquired) return;+ if (failure) return reject(failure);+ try {+ const result = JSON.parse(output);+ if (code !== 0 || result.ok !== true) throw new Error(result.reason || 'retirement-native-failed');+ resolve(result);+ } catch (error) { reject(error); }+ });+ child.stdout.on('data', data => {+ output += data;+ if (output.length > 4 * 1024 * 1024) return stop(new Error('retirement-native-output-limit'));+ if (keepOpen && !acquired && output.includes('\n')) {+ try {+ const result = JSON.parse(output.slice(0, output.indexOf('\n')));+ if (!result.ok) return stop(new Error(result.reason || 'retirement-executor-busy'));+ acquired = true;+ clearTimeout(timer);+ resolve({ assertHeld: () => { if (closed) fail('retirement-executor-lost'); },+ release: async () => { child.stdin.end(); await exited; } });+ } catch (error) { stop(error); }+ }+ });+ // Metadata and native diagnostics stay out of public logs.+ child.stderr.resume();+ child.stdin.on('error', error => { failure ||= error; });+ child.stdin.write(`${JSON.stringify(input)}\n`);+ if (!keepOpen) child.stdin.end();+ });+}++// Native execution remains Darwin-only. Mocked workflow tests may run on+// Windows, where POSIX modes and opening directories for fsync are unsupported.+async function syncDirectory(path) {+ if (hostOsType() === 'Windows_NT') return;+ const directory = await open(path, 'r');+ try { await directory.sync(); } finally { await directory.close(); }+}++async function privateDirectory(path, create = false) {+ assertNotRealDataWrite(path, 'initialized checkout recovery');+ if (create) await mkdir(path, { recursive: true, mode: 0o700 });+ const info = await lstat(path);+ if (!info.isDirectory() || info.isSymbolicLink() || (hostOsType() !== 'Windows_NT' && (info.mode & 0o777) !== 0o700)) fail('retirement-journal-directory-unsafe');+}++async function appendStep(directory, state, phase, patch = {}) {+ await privateDirectory(directory);+ const next = { ...state, ...patch, phase, sequence: (state.sequence ?? -1) + 1,+ previous: state.sequence == null ? null : hash(state) };+ const file = await open(join(directory, `${String(next.sequence).padStart(6, '0')}.json`), 'wx', 0o600);+ try { await file.writeFile(`${JSON.stringify(next)}\n`); await file.sync(); }+ finally { await file.close(); }+ await syncDirectory(directory);+ return next;+}++async function readJournal(directory) {+ await privateDirectory(directory);+ const files = (await readdir(directory)).filter(name => /^\d{6}\.json$/.test(name)).sort();+ let previous = null;+ for (const [sequence, name] of files.entries()) {+ const info = await lstat(join(directory, name));+ if (!info.isFile() || info.isSymbolicLink() || (hostOsType() !== 'Windows_NT' && (info.mode & 0o777) !== 0o600)) fail('retirement-journal-unsafe');+ const row = JSON.parse(await readFile(join(directory, name), 'utf8'));+ if (row.version !== 1 || row.sequence !== sequence || row.previous !== (previous ? hash(previous) : null)) fail('retirement-journal-invalid');+ previous = row;+ }+ if (!previous) fail('retirement-journal-missing');+ return previous;+}++async function defaultContext(appId, release) {+ const [{ getAppById }, { getBranchReconcileOutcome }] = await Promise.all([import('./apps.js'), import('./taskSchedule.js')]);+ const app = await getAppById(appId);+ if (!app?.repoPath) fail('app-not-found');+ if (release) {+ const inventory = await getBranchReconcileOutcome(appId);+ if (!inventory?.remaining?.some(entry => sameRelease(entry, release))) fail('release-not-in-inventory');+ }+ return { repoPath: app.repoPath, forgeAccount: app.forgeAccount ?? null };+}++/** Factory allows workflow tests to replace native IO and forge/network boundaries. */+export function _createInitializedCheckoutRecovery(deps = {}) {+ const native = deps.native || runInitializedCheckoutNative;+ const root = deps.root || transactionRoot;+ const context = deps.context || defaultContext;+ const fenced = deps.fenced || withClaimOwnershipLock;+ const ownership = deps.ownership || (async input => (await import('./heldCheckoutRecovery.js')).inspectCheckoutRetirementOwnership(input));+ const admission = async () => deps.admission || await import('../lib/checkoutRetirementAdmission.js');+ const forge = deps.forge || (async (ctx, release, prUrl) => (await import('./heldCheckoutReview.js')).readRetirementForgeEvidence(+ ctx.repoPath, release.branch, prUrl, { forgeAccount: ctx.forgeAccount, exactAliasHead: release.head }));+ const comparison = deps.comparison || (async (ctx, release, prUrl, snapshot, policy, forgeFacts) => {+ const { buildCheckoutRetirementReview } = await import('./heldCheckoutReview.js');+ return buildCheckoutRetirementReview({ repoPath: ctx.repoPath, release, prUrl,+ contentFingerprint: snapshot.fingerprint, administrationFingerprint: snapshot.administrationFingerprint, policy },+ { readForge: async () => forgeFacts });+ });+ const ensureOwner = async (ctx, release, registration = true) => {+ const result = await ownership({ repoPath: ctx.repoPath, release, registration });+ if (!result.ok) fail(result.reason);+ return result.policy;+ };+ const makeReview = async ({ appId, release, prUrl }) => {+ const ctx = await context(appId, release);+ const policy = await ensureOwner(ctx, release);+ const snapshot = await native({ command: 'inspect', repoPath: ctx.repoPath, release });+ const facts = await forge(ctx, release, prUrl);+ const base = await comparison(ctx, release, prUrl, snapshot, policy, facts);+ const evidence = { ...base, mode: 'initialized-private-modules', snapshot };+ delete evidence.digest;+ return { ctx, review: { digest: hash(evidence), ...evidence } };+ };+ const review = input => fenced(async () => {+ const ctx = await context(input.appId, input.release);+ return (await admission()).withCheckoutPublication(ctx.repoPath, async () => ({ ok: true, ...(await makeReview(input)) }));+ }).then(({ review: result }) => ({ ok: true, review: result }), error => ({ ok: false, reason: error.message }));+ const assertReview = (current, accepted) => {+ if (current.digest !== accepted.digest) fail('retirement-review-changed');+ if (current.comparison.disposition === 'review-supersession' && accepted.acceptSuperseded !== true) fail('retirement-supersession-not-accepted');+ };+ const verifyFacts = async (ctx, state, registration) => {+ const policy = await ensureOwner(ctx, state.release, registration);+ const facts = await forge(ctx, state.release, state.review.forge.prUrl);+ if (JSON.stringify(policy) !== JSON.stringify(state.review.policy)+ || JSON.stringify(facts) !== JSON.stringify(state.review.forge)) fail('retirement-evidence-changed');+ };+ const location = id => {+ if (!/^[a-f0-9-]{36}$/.test(id)) fail('retirement-transaction-invalid');+ return join(root(), id);+ };+ const retire = input => fenced(async () => {+ const prepared = await makeReview({ ...input, prUrl: input.review.prUrl });+ assertReview(prepared.review, input.review);+ const { ctx } = prepared;+ const id = randomUUID();+ await privateDirectory(root(), true);+ const directory = location(id);+ await mkdir(directory, { mode: 0o700 });+ await syncDirectory(root());+ let state = await appendStep(directory, { version: 1, id, appId: input.appId,+ repoPath: ctx.repoPath, release: input.release, review: prepared.review }, 'intent');+ const executor = await native({ command: 'lock', transactionDir: directory }, { keepOpen: true });+ const gate = await admission();+ try {+ const reservation = await gate.reserveCheckoutRetirement(ctx.repoPath, id);+ state = await appendStep(directory, state, 'reserved', { reservation });+ return await gate.withCheckoutReservation(reservation, async () => {+ // Draining may have admitted earlier work. The exact review must still match.+ assertReview((await makeReview({ ...input, prUrl: input.review.prUrl })).review, input.review);+ executor.assertHeld();+ const preserved = await native({ command: 'preserve', repoPath: ctx.repoPath, release: input.release,+ expected: prepared.review.snapshot, transactionDir: directory });+ state = await appendStep(directory, state, 'preserved', { proof: preserved });+ await verifyFacts(ctx, state, true);+ await native({ command: 'verify', transactionDir: directory });+ for (const part of ['working', 'administration']) {+ executor.assertHeld();+ state = await appendStep(directory, state, `quarantine-${part}-intent`);+ await native({ command: 'move', transactionDir: directory, part, direction: 'quarantine' });+ state = await appendStep(directory, state, `quarantined-${part}`);+ }+ await native({ command: 'verify', transactionDir: directory });+ await verifyFacts(ctx, state, false);+ executor.assertHeld();+ // Keep the original ref available for exact in-place rollback. A later+ // branch-only retirement uses its own fresh proof and recovery archive.+ const branchDeleted = false;+ state = await appendStep(directory, state, 'quarantined', { branchDeleted,+ branchRetainedReason: 'quarantined-checkout-rollback-ref' });+ await gate.releaseCheckoutReservation(reservation);+ return { ok: true, transactionId: id, archiveDir: directory, branchDeleted,+ branchRetainedReason: state.branchRetainedReason, originalsQuarantined: true };+ });+ } catch (error) {+ // No automatic rollback after uncertainty: status/restore compare both+ // placements under a new native executor lock before touching either.+ return { ok: false, reason: error.message, transactionId: id, archiveDir: directory, recoveryRequired: true };+ } finally { await executor.release(); }+ }).catch(error => ({ ok: false, reason: error.message }));++ const loadBoundTransaction = async input => {+ const directory = location(input.transactionId);+ const state = await readJournal(directory);+ if (hash(state) !== input.journalDigest) fail('retirement-journal-changed');+ const ctx = await context(input.appId);+ if (state.appId !== input.appId || state.repoPath !== ctx.repoPath) fail('retirement-transaction-app-mismatch');+ return { directory, state, ctx };+ };+ const branchReview = async ({ directory, state, ctx }) => {+ if (state.phase !== 'quarantined' || state.branchDeleted) fail('retirement-branch-phase-not-ready');+ const policy = await ensureOwner(ctx, state.release, false);+ const proof = await native({ command: 'verify', transactionDir: directory, mode: 'restore' });+ if (['working', 'administration'].some(part => proof.placements?.[part]?.state !== 'quarantine')) fail('retirement-originals-not-quarantined');+ const list = deps.listWorktrees || (await import('./worktreeManager.js')).listWorktrees;+ if ((await list(ctx.repoPath)).some(tree => String(tree.branch || '').replace(/^refs\/heads\//, '') === state.release.branch)) fail('branch-has-new-holder');+ const runGit = deps.execGit || execGit;+ const head = await runGit(['rev-parse', '--verify', `refs/heads/${state.release.branch}`], ctx.repoPath, { ignoreExitCode: true });+ 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);+ const evidence = { ...base, mode: 'quarantined-branch', transactionId: state.id,+ journalDigest: hash(state), archiveFingerprint: proof.fingerprint };+ 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) }));+ }).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+ // a ref, and still refuses a new branch/holder or changed archive.+ const finishBranchReceipt = async ({ directory, ctx, state }) => {+ 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');+ const verify = async () => {+ executor.assertHeld();+ await ensureOwner(ctx, state.release, false);+ await native({ command: 'verify', transactionDir: directory, mode: 'standalone' });+ const placement = await native({ command: 'status', transactionDir: directory });+ if (['working', 'administration'].some(part => placement.placements?.[part]?.state !== 'quarantine')) fail('retirement-originals-not-quarantined');+ const list = deps.listWorktrees || (await import('./worktreeManager.js')).listWorktrees;+ if ((await list(ctx.repoPath)).some(tree => String(tree.branch || '').replace(/^refs\/heads\//, '') === state.release.branch)) fail('branch-has-new-holder');+ 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 reservation = await gate.readCheckoutReservation(ctx.repoPath, state.id).catch(error => {+ if (error.code === 'ENOENT' && state.phase === 'retired' && state.receiptRecorded === true) return null;+ throw error;+ });+ const finish = async () => {+ await verify();+ if (state.phase === 'branch-retired') {+ const record = deps.recordRetirement || (await import('./taskSchedule.js')).recordHeldCheckoutRetirement;+ await record(state.appId, { path: state.release.path, branch: state.release.branch,+ head: state.release.head, branchDeleted: true, archiveDir: directory });+ state = await appendStep(directory, state, 'retired', { receiptRecorded: true });+ }+ if (reservation) await gate.releaseCheckoutReservation(reservation);+ return { ok: true, transactionId: state.id, branchDeleted: true, receiptRecorded: true, archiveDir: directory };+ };+ return reservation ? await gate.withCheckoutReservation(reservation, finish)+ : await gate.withCheckoutPublication(ctx.repoPath, finish);+ } finally { await executor.release(); }+ };+ const retireBranch = input => fenced(async () => {+ const bound = await loadBoundTransaction(input);+ const { directory, ctx } = bound;+ let { state } = bound;+ if (['branch-retired', 'retired'].includes(state.phase) && state.branchDeleted === true) return finishBranchReceipt(bound);+ // 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');+ const reservation = await gate.reserveCheckoutRetirement(ctx.repoPath, state.id);+ return await gate.withCheckoutReservation(reservation, async () => {+ assertReview(await branchReview(bound), input.review);+ executor.assertHeld();+ state = await appendStep(directory, state, 'branch-retirement-intent', { reservation, branchReview: current });+ const remove = deps.deleteRef || (await import('./worktreeManager.js')).deleteCompletedLocalBranch;+ const deleted = await remove(ctx.repoPath, state.release.branch, state.release.head);+ if (!deleted) fail('retirement-branch-delete-refused-or-uncertain');+ state = await appendStep(directory, state, 'branch-retired', { branchDeleted: true, branchRetainedReason: null });+ const record = deps.recordRetirement || (await import('./taskSchedule.js')).recordHeldCheckoutRetirement;+ await record(state.appId, { path: state.release.path, branch: state.release.branch,+ head: state.release.head, branchDeleted: true, archiveDir: directory });+ state = await appendStep(directory, state, 'retired', { receiptRecorded: true });+ await gate.releaseCheckoutReservation(reservation);+ return { ok: true, transactionId: state.id, branchDeleted: true, receiptRecorded: true, archiveDir: directory };+ });+ } finally { await executor.release(); }+ }).catch(error => ({ ok: false, reason: error.message, transactionId: input.transactionId, recoveryRequired: true }));++ const status = async ({ appId, transactionId }) => {+ const directory = location(transactionId);+ const state = await readJournal(directory);+ const ctx = await context(appId);+ if (state.appId !== appId || state.repoPath !== ctx.repoPath) fail('retirement-transaction-app-mismatch');+ const hasManifest = await lstat(join(directory, 'manifest.json')).then(() => true, error => {+ if (error.code === 'ENOENT') return false;+ throw error;+ });+ const placement = hasManifest ? await native({ command: 'status', transactionDir: directory }) : { preserved: false };+ let branchRef;+ if (state.phase === 'branch-retirement-intent') {+ const result = await (deps.execGit || execGit)(['show-ref', '--verify', '--quiet', `refs/heads/${state.release.branch}`], ctx.repoPath, { ignoreExitCode: true }).catch(() => null);+ branchRef = result?.exitCode === 0 ? 'present' : result?.exitCode === 1 ? 'absent' : 'unreadable';+ }+ return { ok: true, transactionId, phase: state.phase, release: state.release, placement,+ branchDeleted: state.branchDeleted ?? null, journalDigest: hash(state),+ ...(state.phase === 'branch-retirement-intent' ? { branchDeletion: 'uncertain', branchRef, recoveryRequired: true } : {}),+ ...(state.phase === 'branch-retired' ? { receiptPending: true, recoveryRequired: true } : {}),+ ...(['branch-retired', 'retired'].includes(state.phase) ? { recoveryAction: 'retire-branch' } : {}) };+ };++ const verifyArchive = async input => {+ const directory = location(input.transactionId);+ const state = await readJournal(directory);+ if (hash(state) !== input.journalDigest) fail('retirement-journal-changed');+ const ctx = await context(input.appId);+ if (state.appId !== input.appId || state.repoPath !== ctx.repoPath) fail('retirement-transaction-app-mismatch');+ const proof = await native({ command: 'verify', transactionDir: directory, mode: 'standalone' });+ return { ok: true, transactionId: state.id, standaloneCheckoutPath: proof.restorePath,+ verified: true, branchDeleted: state.branchDeleted ?? false, proof };+ };++ // Explicit recovery restores the exact original inodes. It does not erase+ // archives or auto-finish an interrupted ref deletion on stale forge evidence.+ const restore = input => fenced(async () => {+ const directory = location(input.transactionId);+ const executor = await native({ command: 'lock', transactionDir: directory }, { keepOpen: true });+ const gate = await admission();+ try {+ let state = await readJournal(directory);+ if (hash(state) !== input.journalDigest) fail('retirement-journal-changed');+ const ctx = await context(input.appId);+ if (state.appId !== input.appId || state.repoPath !== ctx.repoPath) fail('retirement-transaction-app-mismatch');+ await ensureOwner(ctx, state.release, false);+ // A completed quarantine released its cut. An interrupted one retains it.+ const reservation = await gate.readCheckoutReservation(ctx.repoPath, state.id).catch(async error => {+ if (error.code !== 'ENOENT') throw error;+ return gate.reserveCheckoutRetirement(ctx.repoPath, state.id);+ });+ return await gate.withCheckoutReservation(reservation, async () => {+ // Preservation can fail before a native manifest exists. No move is+ // ever attempted before its fsynced intent; only those early phases+ // may cancel the cut after a fresh unchanged-source inspection.+ if (['intent', 'reserved', 'preserved'].includes(state.phase)) {+ const snapshot = await native({ command: 'inspect', repoPath: ctx.repoPath, release: state.release });+ if (JSON.stringify(snapshot) !== JSON.stringify(state.review.snapshot)) fail('retirement-source-changed');+ state = await appendStep(directory, state, 'restored', { reservation });+ await gate.releaseCheckoutReservation(reservation);+ return { ok: true, transactionId: state.id, restored: true, archivesRetained: true };+ }+ const { listWorktrees } = await import('./worktreeManager.js');+ const trees = await (deps.listWorktrees || listWorktrees)(ctx.repoPath);+ if (trees.some(tree => String(tree.branch || '').replace(/^refs\/heads\//, '') === state.release.branch && tree.path !== state.release.path)) fail('branch-has-new-holder');+ await native({ command: 'verify', transactionDir: directory, mode: 'restore' });+ const ref = `refs/heads/${state.release.branch}`;+ const runGit = deps.execGit || execGit;+ const existing = await runGit(['rev-parse', '--verify', ref], ctx.repoPath, { ignoreExitCode: true });+ if (existing.exitCode !== 0 || existing.stdout.trim() !== state.release.head) fail('branch-ref-changed');+ for (const part of ['administration', 'working']) {+ executor.assertHeld();+ state = await appendStep(directory, state, `restore-${part}-intent`, { reservation });+ await native({ command: 'move', transactionDir: directory, part, direction: 'restore' });+ state = await appendStep(directory, state, `restored-${part}`);+ }+ await native({ command: 'verify', transactionDir: directory, mode: 'restore' });+ state = await appendStep(directory, state, 'restored');+ await gate.releaseCheckoutReservation(reservation);+ return { ok: true, transactionId: state.id, restored: true, archivesRetained: true };+ });+ } finally { await executor.release(); }+ }).catch(error => ({ ok: false, reason: error.message, transactionId: input.transactionId, recoveryRequired: true }));+ return { review, retire, status, restore, verifyArchive, reviewBranch, retireBranch };+}++const recovery = _createInitializedCheckoutRecovery();+export const reviewInitializedCheckout = recovery.review;+export const retireInitializedCheckout = recovery.retire;+export const initializedCheckoutStatus = recovery.status;+export const restoreInitializedCheckout = recovery.restore;++export const verifyInitializedCheckoutArchive = recovery.verifyArchive;++export const reviewInitializedCheckoutBranch = recovery.reviewBranch;+export const retireInitializedCheckoutBranch = recovery.retireBranch;diff --git a/server/services/initializedCheckoutRecovery.test.js b/server/services/initializedCheckoutRecovery.test.jsnew file mode 100644index 0000000000..45a9a1f465--- /dev/null+++ b/server/services/initializedCheckoutRecovery.test.js@@ -0,0 +1,398 @@+import { pinPlatform } from '../lib/testHelper.js';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';+import { join } from 'node:path';+import { tmpdir } from 'node:os';+import { createHash } from 'node:crypto';+const persisted = vi.hoisted(() => ({ json: '{}', hostType: null, rejectDirectoryOpen: false, syntheticModes: false, fileSyncs: 0 }));+vi.mock('node:os', async importOriginal => {+ const actual = await importOriginal();+ return { ...actual, type: () => persisted.hostType || actual.type() };+});+vi.mock('./taskScheduleStore.js', () => ({+ loadSchedule: async () => JSON.parse(persisted.json),+ updateSchedule: async mutate => {+ const schedule = JSON.parse(persisted.json);+ const { result, changed } = await mutate(schedule);+ if (changed) persisted.json = JSON.stringify(schedule);+ return result;+ },+}));+vi.mock('node:fs/promises', async importOriginal => {+ const actual = await importOriginal();+ return { ...actual, lstat: async path => {+ const info = await actual.lstat(path);+ // Model POSIX permission bits even when this Darwin-capability fixture runs+ // on Windows; the unsafe-mode branch below still exercises real refusal.+ if (persisted.hostType === 'Darwin' || persisted.syntheticModes) {+ const mode = persisted.syntheticModes ? 0o777 : info.isDirectory() ? 0o700 : 0o600;+ return Object.assign(Object.create(info), { mode: (info.mode & ~0o777) | mode });+ }+ return info;+ }, open: async (path, ...args) => {+ if (persisted.rejectDirectoryOpen && (await actual.lstat(path).catch(() => null))?.isDirectory()) throw new Error('directory-open-unsupported');+ if (fixture?.failNextJournal && /[\\/]\d{6}\.json$/.test(String(path))) {+ fixture.failNextJournal = false;+ throw new Error('journal-write-interrupted');+ }+ const handle = await actual.open(path, ...args);+ const originalSync = handle.sync.bind(handle);+ handle.sync = async () => { persisted.fileSyncs++; return originalSync(); };+ return handle;+ } };+});+vi.mock('./cosClaimOwnershipState.js', () => ({ withClaimOwnershipLock: work => work() }));+import { _createInitializedCheckoutRecovery } from './initializedCheckoutRecovery.js';++let root, fixture;+const release = { path: '/fixture/checkout', branch: 'claim/42', head: 'a'.repeat(40), locked: false, lockReason: null };+const prUrl = 'https://github.com/example/repo/pull/42';+beforeEach(async () => {+ persisted.hostType = null; persisted.rejectDirectoryOpen = persisted.syntheticModes = false; persisted.fileSyncs = 0;+ root = await mkdtemp(join(tmpdir(), 'initialized-recovery-'));+ 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 };+ const admission = {+ withCheckoutPublication: async (_repo, work) => { if (fixture.cut) throw new Error('checkout-retirement-reserved'); return work(); },+ reserveCheckoutRetirement: vi.fn(async (_repo, id) => {+ if (fixture.cut) throw new Error('checkout-retirement-reserved');+ fixture.cut = { owner: { id }, directory: '/fixture/admission' }; return fixture.cut;+ }),+ withCheckoutReservation: async (_cut, work) => work(),+ readCheckoutReservation: async () => {+ if (!fixture.cut) throw Object.assign(new Error('missing'), { code: 'ENOENT' });+ return fixture.cut;+ },+ releaseCheckoutReservation: vi.fn(async () => { fixture.cut = null; }),+ };+ const native = vi.fn(async input => {+ if (input.command === 'lock') return { assertHeld: () => {}, release: async () => {} };+ if (input.command === 'inspect') return { ...fixture.snapshot };+ if (input.command === 'preserve') {+ if (fixture.failPreserve) throw new Error('archive-no-space');+ await writeFile(join(input.transactionDir, 'manifest.json'), '{}', { mode: 0o600 });+ return { ok: true, restoreProof: { verified: true } };+ }+ if (input.command === 'move') {+ if (fixture.failPart === input.part && input.direction === 'quarantine') throw new Error('move-refused');+ fixture.placement[input.part] = input.direction === 'quarantine' ? 'quarantined' : 'original';+ }+ if (fixture.failArchive && input.command === 'verify') throw new Error('archive-changed');+ return { ok: true, placement: fixture.placement, fingerprint: fixture.snapshot.fingerprint,+ placements: Object.fromEntries(Object.entries(fixture.placement).map(([part, state]) => [part, { state: state === 'quarantined' ? 'quarantine' : state }])) };+ });+ const deps = { root: () => root, fenced: work => work(), admission, native,+ context: async () => ({ repoPath: '/fixture/repo' }),+ ownership: vi.fn(async () => ({ ok: true, policy: null })),+ forge: async () => ({ ...fixture.facts }),+ comparison: async (_ctx, _release, _url, _snapshot, policy, forge) => ({+ forge, policy, comparison: { disposition: fixture.superseded ? 'review-supersession' : 'ancestor' },+ }),+ listWorktrees: async () => fixture.newHolder ? [{ path: '/fixture/new', branch: release.branch }] : [],+ execGit: vi.fn(async () => ({ exitCode: fixture.headExists ? 0 : 1, stdout: fixture.headExists ? release.head : '' })),+ deleteRef: vi.fn(async () => { fixture.headExists = false; return true; }),+ recordRetirement: vi.fn(async () => {}),+ };+ fixture.deps = deps; fixture.service = _createInitializedCheckoutRecovery(deps);+});+afterEach(async () => { await rm(root, { recursive: true, force: true }); });+const reviewed = async () => {+ const response = await fixture.service.review({ appId: 'app', release, prUrl });+ expect(response.ok).toBe(true);+ return { appId: 'app', release, review: { prUrl, digest: response.review.digest, acceptSuperseded: fixture.superseded === true } };+};++describe('initialized checkout transaction', () => {+ it('uses actual Windows filesystem capabilities for mocked workflows without suppressing file fsync', async () => {+ persisted.hostType = 'Windows_NT'; persisted.syntheticModes = true; persisted.rejectDirectoryOpen = true;+ const restorePlatform = pinPlatform('darwin');+ try {+ const result = await fixture.service.retire(await reviewed());+ expect(result).toMatchObject({ ok: true, originalsQuarantined: true });+ expect((await fixture.service.status({ appId: 'app', transactionId: result.transactionId })).phase).toBe('quarantined');+ expect(persisted.fileSyncs).toBeGreaterThan(0);+ } finally { restorePlatform(); }+ });+ it('does not suppress directory sync failure or POSIX mode checks on Darwin', async () => {+ persisted.hostType = 'Darwin'; persisted.rejectDirectoryOpen = true;+ expect(await fixture.service.retire(await reviewed())).toMatchObject({ ok: false, reason: 'directory-open-unsupported' });+ expect(fixture.deps.native.mock.calls.some(([input]) => input.command === 'move')).toBe(false);+ persisted.rejectDirectoryOpen = false; persisted.syntheticModes = true;+ expect(await fixture.service.retire(await reviewed())).toMatchObject({ ok: false, reason: 'retirement-journal-directory-unsafe' });+ });+ it('keeps the real native backend unavailable on unsupported platforms', async () => {+ const restorePlatform = pinPlatform('win32');+ try {+ const { native: _native, ...deps } = fixture.deps;+ const service = _createInitializedCheckoutRecovery(deps);+ expect(await service.review({ appId: 'app', release, prUrl })).toMatchObject({ ok: false, reason: 'retirement-platform-unsupported' });+ expect(await readdir(root)).toEqual([]);+ } finally { restorePlatform(); }+ });+ it('quarantines both original directories only after preservation, retaining the rollback ref', async () => {+ const result = await fixture.service.retire(await reviewed());+ expect(result).toMatchObject({ ok: true, originalsQuarantined: true, branchDeleted: false, branchRetainedReason: 'quarantined-checkout-rollback-ref' });+ expect(fixture.placement).toEqual({ working: 'quarantined', administration: 'quarantined' });+ expect(fixture.cut).toBeNull();+ expect(fixture.deps.execGit).not.toHaveBeenCalled();+ const commands = fixture.deps.native.mock.calls.map(([input]) => input.command);+ expect(commands.indexOf('preserve')).toBeLessThan(commands.indexOf('move'));+ const status = await fixture.service.status({ appId: 'app', transactionId: result.transactionId });+ expect(status.phase).toBe('quarantined');+ expect(status.journalDigest).toMatch(/^[a-f0-9]{64}$/);+ });+ it.each(['working', 'administration'])('retains a durable cut on %s move interruption and restores explicitly after restart', async part => {+ fixture.failPart = part;+ const result = await fixture.service.retire(await reviewed());+ expect(result).toMatchObject({ ok: false, recoveryRequired: true, reason: 'move-refused' });+ expect(fixture.cut).not.toBeNull();+ const restarted = _createInitializedCheckoutRecovery(fixture.deps);+ const status = await restarted.status({ appId: 'app', transactionId: result.transactionId });+ const restored = await restarted.restore({ appId: 'app', transactionId: result.transactionId, journalDigest: status.journalDigest });+ expect(restored).toMatchObject({ ok: true, restored: true, archivesRetained: true });+ expect(fixture.placement).toEqual({ working: 'original', administration: 'original' });+ expect(fixture.cut).toBeNull();+ });+ it('can cancel a failed preservation without deleting its partial evidence', async () => {+ fixture.failPreserve = true;+ const result = await fixture.service.retire(await reviewed());+ expect(result.reason).toBe('archive-no-space');+ const status = await fixture.service.status({ appId: 'app', transactionId: result.transactionId });+ expect(status.placement).toEqual({ preserved: false });+ expect(await fixture.service.restore({ appId: 'app', transactionId: result.transactionId, journalDigest: status.journalDigest })).toMatchObject({ ok: true });+ expect((await readdir(join(root, result.transactionId))).length).toBeGreaterThan(0);+ });+ it('requires a fresh accepted review and an explicit supersession decision', async () => {+ const input = await reviewed();+ fixture.facts.defaultHead = 'e'.repeat(40);+ expect(await fixture.service.retire(input)).toMatchObject({ ok: false, reason: 'retirement-review-changed' });+ expect(fixture.deps.admission.reserveCheckoutRetirement).not.toHaveBeenCalled();+ fixture.superseded = true;+ const superseded = await reviewed(); superseded.review.acceptSuperseded = false;+ expect(await fixture.service.retire(superseded)).toMatchObject({ ok: false, reason: 'retirement-supersession-not-accepted' });+ });+ it('rechecks ownership after preservation before any move', async () => {+ const input = await reviewed();+ fixture.deps.ownership.mockImplementation(async () => ({ ok: !fixture.deps.native.mock.calls.some(([v]) => v.command === 'preserve'), policy: null, reason: 'active-owner' }));+ expect(await fixture.service.retire(input)).toMatchObject({ ok: false, reason: 'active-owner', recoveryRequired: true });+ expect(fixture.deps.native.mock.calls.some(([v]) => v.command === 'move')).toBe(false);+ expect(fixture.cut).not.toBeNull();+ });+ it('refuses stale recovery digest, a new holder, or changed rollback ref without moving originals', async () => {+ const result = await fixture.service.retire(await reviewed());+ const status = await fixture.service.status({ appId: 'app', transactionId: result.transactionId });+ const input = { appId: 'app', transactionId: result.transactionId, journalDigest: status.journalDigest };+ expect(await fixture.service.restore({ ...input, journalDigest: 'f'.repeat(64) })).toMatchObject({ ok: false, reason: 'retirement-journal-changed' });+ fixture.newHolder = true;+ expect(await fixture.service.restore(input)).toMatchObject({ ok: false, reason: 'branch-has-new-holder' });+ fixture.newHolder = false;+ fixture.deps.execGit.mockResolvedValue({ exitCode: 1, stdout: '' });+ expect(await fixture.service.restore(input)).toMatchObject({ ok: false, reason: 'branch-ref-changed' });+ expect(fixture.placement).toEqual({ working: 'quarantined', administration: 'quarantined' });+ });+ it('verifies standalone recovery independently after the live branch is unavailable', async () => {+ const result = await fixture.service.retire(await reviewed());+ const status = await fixture.service.status({ appId: 'app', transactionId: result.transactionId });+ fixture.deps.execGit.mockResolvedValue({ exitCode: 1, stdout: '' });+ const input = { appId: 'app', transactionId: result.transactionId, journalDigest: status.journalDigest };+ expect(await fixture.service.verifyArchive(input)).toMatchObject({ ok: true, verified: true });+ expect(fixture.deps.native).toHaveBeenLastCalledWith({ command: 'verify', transactionDir: join(root, result.transactionId), mode: 'standalone' });+ expect(fixture.deps.execGit).not.toHaveBeenCalled();+ });+ const quarantinedReview = async () => {+ const result = await fixture.service.retire(await reviewed());+ const status = await fixture.service.status({ appId: 'app', transactionId: result.transactionId });+ const bound = { appId: 'app', transactionId: result.transactionId, journalDigest: status.journalDigest };+ const response = await fixture.service.reviewBranch(bound);+ expect(response.ok).toBe(true);+ return { ...bound, review: { prUrl, digest: response.review.digest, acceptSuperseded: fixture.superseded === true } };+ };+ it('finishes a quarantined branch with a new exact review and records the source checkout receipt', async () => {+ const input = await quarantinedReview();+ const result = await fixture.service.retireBranch(input);+ expect(result).toMatchObject({ ok: true, branchDeleted: true, receiptRecorded: true });+ expect(fixture.deps.deleteRef).toHaveBeenCalledWith('/fixture/repo', release.branch, release.head);+ expect(fixture.deps.recordRetirement).toHaveBeenCalledWith('app', { path: release.path, branch: release.branch,+ head: release.head, branchDeleted: true, archiveDir: join(root, input.transactionId) });+ expect(fixture.cut).toBeNull();+ expect((await fixture.service.status(input)).phase).toBe('retired');+ });+ it('invalidates branch finalization when the default advances or a holder appears', async () => {+ const input = await quarantinedReview();+ fixture.facts.defaultHead = 'e'.repeat(40);+ expect(await fixture.service.retireBranch(input)).toMatchObject({ ok: false, reason: 'retirement-review-changed' });+ fixture.newHolder = true;+ expect(await fixture.service.retireBranch(input)).toMatchObject({ ok: false, reason: 'branch-has-new-holder' });+ expect(fixture.deps.deleteRef).not.toHaveBeenCalled();+ });+ it('requires explicit fresh supersession acceptance and complete archive proof for branch finalization', async () => {+ fixture.superseded = true;+ const input = await quarantinedReview(); input.review.acceptSuperseded = false;+ expect(await fixture.service.retireBranch(input)).toMatchObject({ ok: false, reason: 'retirement-supersession-not-accepted' });+ fixture.failArchive = true;+ expect(await fixture.service.retireBranch(input)).toMatchObject({ ok: false, reason: 'archive-changed' });+ expect(fixture.deps.deleteRef).not.toHaveBeenCalled();+ });+ it('retains the delete intent and reports uncertainty after deletion without a journal outcome', async () => {+ const input = await quarantinedReview();+ fixture.deps.deleteRef.mockImplementation(async () => { fixture.headExists = false; throw new Error('receiver-result-lost'); });+ expect(await fixture.service.retireBranch(input)).toMatchObject({ ok: false, reason: 'receiver-result-lost', recoveryRequired: true });+ const restarted = _createInitializedCheckoutRecovery(fixture.deps);+ const status = await restarted.status(input);+ expect(status).toMatchObject({ phase: 'branch-retirement-intent', branchDeletion: 'uncertain', branchRef: 'absent', recoveryRequired: true });+ expect(fixture.cut).not.toBeNull();+ expect(fixture.deps.recordRetirement).not.toHaveBeenCalled();+ expect(await restarted.retireBranch({ ...input, journalDigest: status.journalDigest }))+ .toMatchObject({ ok: false, reason: 'retirement-branch-deletion-uncertain' });+ expect(fixture.deps.deleteRef).toHaveBeenCalledTimes(1);+ expect(fixture.deps.execGit.mock.calls.some(([args]) => args[0] === 'update-ref')).toBe(false);+ });+ it('preserves the completed deletion obligation when recording the schedule receipt fails', async () => {+ const input = await quarantinedReview();+ fixture.deps.recordRetirement.mockRejectedValue(new Error('receipt-disk-full'));+ expect(await fixture.service.retireBranch(input)).toMatchObject({ ok: false, reason: 'receipt-disk-full' });+ expect(await fixture.service.status(input)).toMatchObject({ phase: 'branch-retired', branchDeleted: true, receiptPending: true, recoveryRequired: true });+ expect(fixture.cut).not.toBeNull();+ });+ it('replays a conclusively completed deletion receipt after restart without another Git mutation', async () => {+ const input = await quarantinedReview();+ fixture.deps.recordRetirement.mockRejectedValueOnce(new Error('receipt-disk-full'));+ expect(await fixture.service.retireBranch(input)).toMatchObject({ ok: false });+ const restarted = _createInitializedCheckoutRecovery(fixture.deps);+ const status = await restarted.status(input);+ expect(await restarted.retireBranch({ ...input, journalDigest: status.journalDigest }))+ .toMatchObject({ ok: true, branchDeleted: true, receiptRecorded: true });+ expect(fixture.deps.deleteRef).toHaveBeenCalledTimes(1);+ expect(fixture.deps.recordRetirement).toHaveBeenCalledTimes(2);+ expect(fixture.cut).toBeNull();+ });+ it('releases the retained cut after receipt completion and is idempotent once released', async () => {+ const input = await quarantinedReview();+ fixture.deps.admission.releaseCheckoutReservation.mockRejectedValueOnce(new Error('cut-release-interrupted'));+ expect(await fixture.service.retireBranch(input)).toMatchObject({ ok: false, reason: 'cut-release-interrupted' });+ const restarted = _createInitializedCheckoutRecovery(fixture.deps);+ const status = await restarted.status(input);+ expect(status.phase).toBe('retired');+ expect(fixture.cut).not.toBeNull();+ const replay = { ...input, journalDigest: status.journalDigest };+ expect(await restarted.retireBranch(replay)).toMatchObject({ ok: true });+ expect(fixture.cut).toBeNull();+ expect(await restarted.retireBranch(replay)).toMatchObject({ ok: true });+ expect(fixture.deps.deleteRef).toHaveBeenCalledTimes(1);+ expect(fixture.deps.recordRetirement).toHaveBeenCalledTimes(1);+ });+ it.each(['headExists', 'newHolder', 'failArchive'])('retains receipt recovery on fresh %s conflict', async conflict => {+ const input = await quarantinedReview();+ fixture.deps.recordRetirement.mockRejectedValueOnce(new Error('receipt-disk-full'));+ await fixture.service.retireBranch(input);+ const status = await fixture.service.status(input);+ fixture[conflict] = true;+ expect(await fixture.service.retireBranch({ ...input, journalDigest: status.journalDigest }))+ .toMatchObject({ ok: false, recoveryRequired: true });+ expect(fixture.cut).not.toBeNull();+ expect(fixture.deps.deleteRef).toHaveBeenCalledTimes(1);+ expect(fixture.deps.recordRetirement).toHaveBeenCalledTimes(1);+ });+ 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');+ persisted.json = JSON.stringify({ executions: { 'task:branch-reconcile': { perApp: { app: {+ branchReconcileOutcome: { remaining: [release], retired: Array.from({ length: 20 }, (_, index) => ({+ path: `/other/${index}`, archiveDir: `/archives/${index}`, retiredAt: '2020-01-01T00:00:00.000Z',+ })) },+ } } } } });+ fixture.deps.recordRetirement.mockImplementationOnce(async (...args) => {+ await recordHeldCheckoutRetirement(...args);+ fixture.failNextJournal = true;+ }).mockImplementation(recordHeldCheckoutRetirement);+ expect(await fixture.service.retireBranch(input)).toMatchObject({ ok: false, reason: 'journal-write-interrupted' });+ // Evict the original from the 20-row display ring before replay.+ for (let index = 0; index < 20; index++) await recordHeldCheckoutRetirement('app', {+ path: `/later/${index}`, branch: `later/${index}`, head: 'f'.repeat(40),+ branchDeleted: true, archiveDir: `/later-archives/${index}`,+ });+ const newer = { ...release, reason: 'retirement-review-pending' };+ await recordBranchReconcileOutcome('app', { status: 'actionable', remaining: [newer] });+ const saved = JSON.parse(persisted.json);+ const outcome = saved.executions['task:branch-reconcile'].perApp.app.branchReconcileOutcome;+ const originalReceipts = structuredClone(outcome.retired);+ const originalIdentities = structuredClone(outcome.retirementReceiptIdentities);+ expect(originalReceipts.some(receipt => receipt.path === release.path)).toBe(false);+ const currentInventory = structuredClone(outcome.remaining);+ const currentObligations = structuredClone(outcome.retirementObligations);+ expect(currentObligations).toHaveLength(1);+ expect(Number.isFinite(Date.parse(currentObligations[0].createdAt))).toBe(true);+ const restarted = _createInitializedCheckoutRecovery(fixture.deps);+ const status = await restarted.status(input);+ expect(await restarted.retireBranch({ ...input, journalDigest: status.journalDigest })).toMatchObject({ ok: true });+ const replayed = JSON.parse(persisted.json).executions['task:branch-reconcile'].perApp.app.branchReconcileOutcome;+ expect(replayed.retired).toEqual(originalReceipts);+ expect(replayed.retirementReceiptIdentities).toEqual(originalIdentities);+ expect(replayed.remaining).toEqual(currentInventory);+ expect(replayed.retirementObligations).toEqual(currentObligations);+ expect(fixture.deps.deleteRef).toHaveBeenCalledTimes(1);+ expect(fixture.cut).toBeNull();+ });+ it('keeps a recreated checkout generation pending on old receipt replay and accepts its own new archive', async () => {+ const { recordHeldCheckoutRetirement, recordBranchReconcileOutcome, getBranchReconcileOutcome } = await import('./taskSchedule.js');+ persisted.json = JSON.stringify({ executions: {} });+ const pending = { ...release, reason: 'retirement-review-pending' };+ const first = await recordBranchReconcileOutcome('app', { status: 'actionable', remaining: [pending] });+ const firstCreated = first.retirementObligations[0].createdAt;+ const receipt = { ...release, branchDeleted: true, archiveDir: '/archive/original' };+ const retired = await recordHeldCheckoutRetirement('app', receipt);+ expect(retired.retirementObligations).toEqual([]);+ expect(retired.remaining).toEqual([]);+ const originalTimestamp = retired.retired[0].retiredAt;+ const recreated = await recordBranchReconcileOutcome('app', { status: 'actionable', remaining: [pending] });+ const generation = recreated.retirementObligations[0].createdAt;+ expect(Date.parse(generation)).toBeGreaterThan(Date.parse(originalTimestamp));+ expect(Date.parse(generation)).toBeGreaterThanOrEqual(Date.parse(firstCreated));+ await recordHeldCheckoutRetirement('app', receipt);+ expect(await getBranchReconcileOutcome('app')).toEqual(recreated);+ // The fresh archive is a different retirement identity, with evidence later+ // than this server-created generation. The old archive remains untouched.+ vi.useFakeTimers();+ try {+ vi.setSystemTime(Date.parse(generation) + 1);+ const completed = await recordHeldCheckoutRetirement('app', { ...receipt, archiveDir: '/archive/new-generation' });+ expect(completed.retirementObligations).toEqual([]);+ expect(completed.remaining).toEqual([]);+ expect(completed.retired.find(row => row.archiveDir === receipt.archiveDir).retiredAt).toBe(originalTimestamp);+ expect(Object.keys(completed.retirementReceiptIdentities)).toHaveLength(2);+ } finally { vi.useRealTimers(); }+ });+ it.each(['quarantined', 'branch-retired'])('rechecks the journal after executor acquisition in %s', async phase => {+ let input = await quarantinedReview();+ if (phase === 'branch-retired') {+ fixture.deps.recordRetirement.mockRejectedValueOnce(new Error('receipt-pending'));+ await fixture.service.retireBranch(input);+ input = { ...input, journalDigest: (await fixture.service.status(input)).journalDigest };+ }+ const directory = join(root, input.transactionId);+ const invoke = fixture.deps.native.getMockImplementation();+ fixture.deps.native.mockImplementation(async request => {+ if (request.command === 'lock') {+ const files = (await readdir(directory)).filter(name => /^\d{6}\.json$/.test(name)).sort();+ const previous = JSON.parse(await readFile(join(directory, files.at(-1)), 'utf8'));+ const next = { ...previous, sequence: previous.sequence + 1,+ previous: createHash('sha256').update(JSON.stringify(previous)).digest('hex') };+ await writeFile(join(directory, `${String(next.sequence).padStart(6, '0')}.json`), JSON.stringify(next), { mode: 0o600 });+ }+ return invoke(request);+ });+ const deletes = fixture.deps.deleteRef.mock.calls.length;+ const receipts = fixture.deps.recordRetirement.mock.calls.length;+ expect(await fixture.service.retireBranch(input)).toMatchObject({ ok: false, reason: 'retirement-journal-changed' });+ expect(fixture.deps.deleteRef).toHaveBeenCalledTimes(deletes);+ expect(fixture.deps.recordRetirement).toHaveBeenCalledTimes(receipts);+ });+ it('holds if immutable journal history is changed', async () => {+ const result = await fixture.service.retire(await reviewed());+ const first = join(root, result.transactionId, '000000.json');+ const value = JSON.parse(await readFile(first, 'utf8')); value.repoPath = '/different';+ await writeFile(first, JSON.stringify(value));+ await expect(fixture.service.status({ appId: 'app', transactionId: result.transactionId })).rejects.toThrow('retirement-journal-invalid');+ });+});diff --git a/server/services/taskSchedule.js b/server/services/taskSchedule.jsindex 4039e4729c..ac42b424a6 100644--- a/server/services/taskSchedule.js+++ b/server/services/taskSchedule.js@@ -21,7 +21,7 @@import { scheduleExecutionFieldsSchema } from '../lib/scheduleExecutionFieldsValidation.js';import { unresolvedRetirements, retainRetirementObligations, sameRetirementCheckout } from '../lib/reconcileRetirementEvidence.js';-import { randomUUID } from 'node:crypto';+import { createHash, randomUUID } from 'node:crypto';import { ServerError } from '../lib/errorHandler.js';import { taskExecutionKey as executionKey } from '../lib/scheduledTaskTypes.js';import { TASK_READINESS_REASON } from '../lib/taskReadinessReasons.js';@@ -778,12 +778,31 @@ export async function recordHeldCheckoutRetirement(appId, { path, branch, branchreturn updateSchedule(async (schedule) => {const record = ensureExecutionRecord(schedule, 'branch-reconcile', appId);const outcome = record.branchReconcileOutcome || {};+ // Display history is bounded; replay identity is durable. A delayed retry+ // must not become new evidence after its display row has been evicted.+ const identity = receipt => createHash('sha256').update(JSON.stringify([+ receipt.archiveDir, receipt.path, receipt.branch ?? null, receipt.head,+ receipt.branchDeleted === true,+ ])).digest('hex');+ const receipts = { ...(outcome.retirementReceiptIdentities || {}) };+ for (const receipt of outcome.retired || []) {+ if (receipt.archiveDir && receipt.retiredAt) receipts[identity(receipt)] ??= receipt.retiredAt;+ }+ const receiptId = archiveDir ? identity({ path, branch, head, archiveDir, branchDeleted }) : null;+ if (receiptId && receipts[receiptId]) {+ // Keep the original timestamp AND any newer inventory incarnation.+ const changed = JSON.stringify(receipts) !== JSON.stringify(outcome.retirementReceiptIdentities || {});+ if (changed) record.branchReconcileOutcome = { ...outcome, retirementReceiptIdentities: receipts };+ return { result: record.branchReconcileOutcome, changed };+ }const retiredAt = new Date().toISOString();+ if (receiptId) receipts[receiptId] = retiredAt;const receipt = { path, ...(branch && { branch }), head, branchDeleted, archiveDir, retiredAt };const retired = [receipt, ...(outcome.retired || [])].slice(0, RETIRED_CHECKOUTS_KEPT);const retirementObligations = unresolvedRetirements({ ...outcome, retired });record.branchReconcileOutcome = {...outcome, retirementObligations,+ retirementReceiptIdentities: receipts,updatedAt: retiredAt,remaining: Array.isArray(outcome.remaining)? outcome.remaining.filter(entry => retirementObligations.some(row => sameRetirementCheckout(row, entry))diff --git a/server/services/worktreeExternalCleanup.test.js b/server/services/worktreeExternalCleanup.test.jsindex 14339270fd..584bc55915 100644--- a/server/services/worktreeExternalCleanup.test.js+++ b/server/services/worktreeExternalCleanup.test.js@@ -1,4 +1,6 @@/** Real separate-repository fixtures for the public scheduled cleanup consumer. */+// Git/filesystem are synthetic in this suite; real durable admission has its own boundary tests.+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (_repo, work) => work() }));import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';import { existsSync, realpathSync } from 'fs';import { mkdir, open, readFile, rm, symlink, unlink, writeFile } from 'fs/promises';diff --git a/server/services/worktreeManager.js b/server/services/worktreeManager.jsindex 147b1cd766..74147cde80 100644--- a/server/services/worktreeManager.js+++ b/server/services/worktreeManager.js@@ -192,7 +192,12 @@ export function isBranchCheckedOutElsewhereError(message) {* exists`, and cleanup must NOT mistake that for "the branch pre-dated us"* (#2193) — the branch is exactly the orphan it needs to delete.*/-export function addWorktreeWithRetry(args, repo, attempt = 1, firstError = null) {+export async function addWorktreeWithRetry(args, repo, attempt = 1, firstError = null) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(repo, () => addWorktreeAdmitted(args, repo, attempt, firstError));+}++function addWorktreeAdmitted(args, repo, attempt, firstError) {return execGit(args, repo, { timeout: WORKTREE_ADD_TIMEOUT_MS }).catch((err) => {const originalError = firstError || err;if (attempt >= WORKTREE_ADD_MAX_ATTEMPTS || !isGitLockError(err.message)) {@@ -230,7 +235,10 @@ async function queueWorktreeCreate(repo, fn) {let key = common && isAbsolute(common) ? common : repo;try { key = realpathSync(key); } catch { /* invalid repositories fail in the operation itself */ }if (!key) key = '__unknown__';- return queueWorktreeCreateForKey(key, fn);+ return queueWorktreeCreateForKey(key, async () => {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(repo, fn);+ });}/** Delete one completed local ref through Git's receiver. Unlike update-ref,@@ -403,7 +411,13 @@ function removalOutcome(worktreePath, { directory, registration }, failure = nul* @returns {Promise<{removed: boolean, directory: string, registration: string, warning: string|null}>}* `warning` is set exactly when `removed` is false.*/-export async function forceRemoveWorktreeDir(repo, worktreePath, { label, log = 'remove', subject = worktreePath, verifyRemoval } = {}) {+export async function forceRemoveWorktreeDir(repo, worktreePath, opts = {}) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(repo, () => forceRemoveWorktreeDirAdmitted(repo, worktreePath, opts))+ .catch(error => ({ removed: false, reason: error.message, warning: 'Checkout retained: repository reservation unavailable' }));+}++async function forceRemoveWorktreeDirAdmitted(repo, worktreePath, { label, log = 'remove', subject = worktreePath, verifyRemoval } = {}) {const logAll = label && log === 'all';let lastFailure = null;let heldReason = null;@@ -987,7 +1001,13 @@ export const SIBLING_NEXT_HOLDER_IDLE_MS = 10 * 60 * 1000;* @param {{ activeWorkspacePaths?: string[], agents?: object[], requestingAgentId?: string, idleMs?: number, nowMs?: number, allowUntracked?: boolean }} [options]* @returns {Promise<{ path: string }|null>} the released holder, or null*/-export async function releaseIdleSiblingNextHolder(sourceWorkspace, branchName, {+export async function releaseIdleSiblingNextHolder(sourceWorkspace, branchName, options = {}) {+ if (!sourceWorkspace || !branchName?.startsWith('next/')) return null;+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(sourceWorkspace, () => releaseIdleSiblingNextHolderAdmitted(sourceWorkspace, branchName, options));+}++async function releaseIdleSiblingNextHolderAdmitted(sourceWorkspace, branchName, {activeWorkspacePaths = [],agents = null,requestingAgentId = null,@@ -1297,7 +1317,10 @@ export async function removeWorktree(agentId, sourceWorkspace, branchName, optiobranchName, holderPath: join(WORKTREES_DIR, agentId), sourceWorkspace,agents: await readClaimOwnershipAgents().catch(() => null), ignoreIds: [agentId],});- return withClaimOwnershipLock(() => removeWorktreeNow(agentId, sourceWorkspace, branchName, options, ownershipHold));+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withClaimOwnershipLock(() => withCheckoutPublication(sourceWorkspace,+ () => removeWorktreeNow(agentId, sourceWorkspace, branchName, options, ownershipHold)));+}async function removeWorktreeNow(agentId, sourceWorkspace, branchName, options, ownershipHold) {@@ -1609,6 +1632,11 @@ async function createPersistentWorktreeUnlocked(featureAgentId, sourceWorkspace,* Remove a persistent feature agent worktree*/export async function removePersistentWorktree(featureAgentId, sourceWorkspace, branchName) {+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(sourceWorkspace, () => removePersistentWorktreeAdmitted(featureAgentId, sourceWorkspace, branchName));+}++async function removePersistentWorktreeAdmitted(featureAgentId, sourceWorkspace, branchName) {const worktreePath = join(WORKTREES_DIR, '..', 'feature-agents', featureAgentId, 'worktree');if (!existsSync(worktreePath)) return { removed: false };@@ -1748,7 +1776,8 @@ async function removeIfStillOrphaned({ isOwned, branchName, holderPath, sourceWoif (isOwned()) return null;const agents = await readOwners();if (claimCheckoutOwnerReason({ branchName, holderPath, sourceWorkspace, agents })) return null;- return remove();+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ return withCheckoutPublication(sourceWorkspace, remove);});}@@ -2056,7 +2085,8 @@ async function cleanupExternalRepoWorktrees(readActiveIds, alreadyHandled, readO// Non-force removal is a final Git guard against newly dirty or locked// trees. A refusal must never fall through to recursive filesystem removal.- const removed = await removeIfStillOrphaned(+ const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');+ const removed = await withCheckoutPublication(parentRepo, () => removeIfStillOrphaned({ isOwned: () => ownership({ locked: wt.locked }), branchName, holderPath: worktreePath, sourceWorkspace: parentRepo, readOwners },async () => {const { preserveMergedCheckout } = await import('./heldCheckoutRecovery.js');@@ -2076,7 +2106,7 @@ async function cleanupExternalRepoWorktrees(readActiveIds, alreadyHandled, readO}return ok;},- ).catch(err => {+ )).catch(err => {console.warn(`⚠️ Preserved external worktree ${entry.name}: ${err.message}`);return false;});diff --git a/server/services/worktreeManager.test.js b/server/services/worktreeManager.test.jsindex 93ee38392a..d2f2f9f40a 100644--- a/server/services/worktreeManager.test.js+++ b/server/services/worktreeManager.test.js@@ -1,4 +1,7 @@import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';+// Git/filesystem are synthetic in this suite; real durable admission has its own boundary tests.+const publicationMock = vi.hoisted(() => vi.fn((_repo, work) => work()));+vi.mock('../lib/checkoutRetirementAdmission.js', () => ({ withCheckoutPublication: (...args) => publicationMock(...args) }));import { dirname, join } from 'path';// Stub every git operation; lifecycle tests exercise the real service without@@ -1699,6 +1702,7 @@ describe('cleanupOrphanedWorktrees ownership and removal', () => {const tree = agentId => join(PATHS.worktrees, agentId);beforeEach(() => {+ publicationMock.mockReset().mockImplementation((_repo, work) => work());existsSync.mockReset().mockReturnValue(true);readdir.mockReset().mockResolvedValue([]);lstat.mockReset().mockRejectedValue(Object.assign(new Error('gone'), { code: 'ENOENT' }));@@ -1710,10 +1714,29 @@ describe('cleanupOrphanedWorktrees ownership and removal', () => {});afterEach(() => {+ publicationMock.mockReset().mockImplementation((_repo, work) => work());readdir.mockReset().mockResolvedValue([]);lstat.mockReset().mockResolvedValue({});});+ it('retains an orphan before lockfile discard or merge when a durable retirement cut owns the repository', async () => {+ execGitMock.mockImplementation(async (args, cwd) => {+ if (args[0] === 'worktree' && args[1] === 'list') return { stdout: ['worktree ' + tree('agent-dead'),+ 'HEAD ' + 'a'.repeat(40), 'branch refs/heads/cos/task/agent-dead', ''].join('\n') };+ if (args[0] === 'status') return { stdout: ' M package-lock.json', exitCode: 0 };+ if (args[0] === 'rev-list') return { stdout: '1', exitCode: 0 };+ if (args[0] === 'rev-parse') return { stdout: args[1] === '--show-toplevel' ? cwd : args[1] === '--verify' ? 'a'.repeat(40) : 'main', exitCode: 0 };+ return { stdout: '', exitCode: 0 };+ });+ publicationMock.mockRejectedValueOnce(new Error('checkout-retirement-reserved'));+ expect(await cleanupOrphanedWorktrees('/repo', new Set(), { claimOwners: { agents: [] } })).toBe(0);+ expect(publicationMock).toHaveBeenCalledTimes(1);+ expect(publicationMock).toHaveBeenCalledWith('/repo', expect.any(Function));+ expect(execGitMock.mock.calls.some(([args]) => ['checkout', 'merge', 'branch', 'push'].includes(args[0])+ || (args[0] === 'worktree' && args[1] === 'remove'))).toBe(false);+ expect(rm).not.toHaveBeenCalled();+ });+it('removes only the clean inactive agent and preserves active, human, locked, dirty and detached trees', async () => {const entries = [{ path: '/repo', branch: 'main' },