Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: preserve and retire initialized checkouts safely (#12607)

[._.]/8937e41da094
diff --git a/docs/STORAGE.md b/docs/STORAGE.md
index 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 fo
older cache writers. Ambiguous legacy matches are preserved rather than guessed.
These fields do not add federation or a new store; older cache records remain
readable 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.md
index 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 rechecked
immediately before removal; if that recheck refuses, the original lock is
restored. A retired row leaves the inventory and appears under *Recently
retired* 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.md
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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 (r
res.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.js
index 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.getScheduleStatus
diff --git a/server/services/README.md b/server/services/README.md
index 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.js
index 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.js
index 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.js
index 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.js
index 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(), spawnTui
import { 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') && protectedAg
beforeEach(() => {
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.js
index 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.js
index 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.js
index 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, findAdoptableWorktree
import { 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.js
index 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.js
index 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) => git
diff --git a/server/services/appQualitySnapshotFile.test.js b/server/services/appQualitySnapshotFile.test.js
index 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.js
index 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.js
index 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 owned
diff --git a/server/services/cosClaimOwnership.test.js b/server/services/cosClaimOwnership.test.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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 interpretation
const 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 window
if (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 a
diff --git a/server/services/git.publication.test.js b/server/services/git.publication.test.js
new file mode 100644
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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, releas
try {
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, releas
captured: { 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.js
index 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.js
index 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, { for
const 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, { for
const 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 an
diff --git a/server/services/heldCheckoutReview.test.js b/server/services/heldCheckoutReview.test.js
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
index 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, branch
return 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.js
index 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.js
index 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, optio
branchName, 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, sourceWo
if (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.js
index 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' },