worktree-for-agents 0.0.0-stage → 1.0.0

package/worktree_manager/recovery_manager.py

@@ -0,0 +1,114 @@
+"""Conservative transaction recovery: never interprets recovery as discard."""
+from __future__ import annotations
+from pathlib import Path
+import json
+from .models import ManagerError, ResultKind
+from .transaction_journal import TransactionJournal
+from .git_repository import GitRepository
+from .lock_manager import LockManager
+import hashlib
+class RecoveryManager:
+    def __init__(self,state_root: str|Path,repo_root: str|Path|None=None): self.journal=TransactionJournal(state_root); self.repo=GitRepository(repo_root) if repo_root else None
+    def recover(self,transaction_id: str|None=None,work_id: str|None=None):
+        if transaction_id is None:
+            pending=[]
+            for path in self.journal.root.glob('*/journal'):
+                try:
+                    if path.read_text(encoding='utf-8').strip() not in ('restored',): pending.append(path.parent.name)
+                except OSError: continue
+            if not pending: return ResultKind.NO_PENDING_WORK,None
+            transaction_id=sorted(pending)[-1]
+        # Distinguish an unknown transaction identity from a damaged journal.
+        # This check must precede both journal parsing and the lock barrier.
+        if not (self.journal.directory(transaction_id)/'journal').is_file():
+            raise ManagerError('invalid_identity','Transaction does not exist',3)
+        if self.repo is not None:
+            binding=self.journal.read_binding(transaction_id)
+            if (binding.get('transaction_id')!=transaction_id or
+                binding.get('repo')!=str(self.repo.root.resolve()) or
+                (work_id is not None and binding.get('work_id')!=work_id)):
+                raise ManagerError('invalid_identity','Transaction binding does not match the requested identity',3)
+        phase=self.journal.read_phase(transaction_id)
+        if phase in {'restored','closed','aborted'}: return ResultKind.NO_PENDING_WORK,{'transaction_id':transaction_id,'phase':phase}
+        if self.repo is not None:
+            # Validate transaction existence before marking/acquiring the lock.
+            key=hashlib.sha256(str(self.repo.root.resolve()).encode()).hexdigest()
+            locks=LockManager(self.journal.root.parent/'locks')
+            with locks:
+                locks.acquire([f'repository-{key}'],'recover')
+                phase=self.journal.read_phase(transaction_id)
+                current=self.journal.read_binding(transaction_id)
+                if (current.get('transaction_id')!=transaction_id or current.get('repo')!=str(self.repo.root.resolve()) or
+                    (work_id is not None and current.get('work_id')!=work_id)):
+                    raise ManagerError('invalid_identity','Transaction binding changed during recovery',3)
+                return self._recover_locked(transaction_id,phase)
+        return self._recover_locked(transaction_id,phase)
+
+    def _recover_locked(self,transaction_id,phase):
+        if phase=='pending_manual':
+            if self.repo is None: return ResultKind.PENDING_INTERVENTION,{'transaction_id':transaction_id,'phase':phase}
+            try: meta=json.loads((self.journal.directory(transaction_id)/'meta.json').read_text(encoding='utf-8'))
+            except (OSError,ValueError) as exc: raise ManagerError('invalid_journal','Recovery metadata is corrupt; backups were retained',5) from exc
+            lifecycle=__import__('worktree_manager.worktree_lifecycle',fromlist=['WorktreeLifecycle']).WorktreeLifecycle.__new__(__import__('worktree_manager.worktree_lifecycle',fromlist=['WorktreeLifecycle']).WorktreeLifecycle)
+            lifecycle.config=type('RecoveryConfig',(),{'repo_root':self.repo.root,'backup_ref_prefix':meta.get('backup_ref_prefix','worktree-manager/backups')})()
+            lifecycle.git=self.repo; lifecycle.journal=self.journal
+            lifecycle._restore_saved(transaction_id,meta)
+            self.journal.write_phase(transaction_id,'restored')
+            return ResultKind.SUCCESS,{'transaction_id':transaction_id,'phase':'restored'}
+        if phase=='restored': return ResultKind.NO_PENDING_WORK,{'transaction_id':transaction_id,'phase':phase}
+        if phase in {'captured','merge_started','merged','remove_started','removed'}:
+            if self.repo is None: raise ManagerError('recovery_requires_intervention','Repository context is required; no effects were changed',5)
+            try: meta=json.loads((self.journal.directory(transaction_id)/'meta.json').read_text(encoding='utf-8'))
+            except (OSError,ValueError) as exc: raise ManagerError('invalid_journal','Recovery metadata is corrupt; backups were retained',5) from exc
+            if meta.get('base') is None or meta.get('branch') is None or meta.get('path') is None: raise ManagerError('invalid_journal','Transaction identity is incomplete',5)
+            # Preserve-dirty captures are a separate recovery contract from a
+            # durable squash. A crash can leave captured parent state that
+            # must not be silently classified as a completed close, regardless
+            # of whether HEAD advanced. Keep every artifact for intervention.
+            if meta.get('preserve_dirty'):
+                raise ManagerError('intervention_required','Preserved changes require explicit validated recovery; resources retained',5)
+            head=self.repo.head(); before=meta.get('before'); branch=meta['branch']; path=Path(meta['path']); registered={line[9:] for line in self.repo.worktrees().splitlines() if line.startswith('worktree ')}
+            # A durable squash interrupted before the close journal advances is
+            # not a transaction recovery. Confirm the complete identity before
+            # reporting no pending work; ambiguous movement remains actionable.
+            if phase == 'merge_started' and head != before:
+                base_tip=self.repo.run(('rev-parse',f"refs/heads/{meta['base']}"),check=False)
+                worktree_head=self.repo.run(('-C',str(path),'rev-parse','HEAD'),check=False)
+                symbolic=self.repo.run(('-C',str(path),'symbolic-ref','-q','HEAD'),check=False)
+                branch_tip=self.repo.run(('rev-parse',f'refs/heads/{branch}'),check=False)
+                parents=self.repo.run(('rev-list','--parents','-n','1',head),check=False).stdout.split()
+                registered_paths={str(Path(item).resolve()) for item in registered}
+                if (base_tip.returncode or base_tip.stdout.strip()!=head or
+                    str(path.resolve()) not in registered_paths or
+                    worktree_head.returncode or worktree_head.stdout.strip()!=meta.get('origin') or
+                    symbolic.returncode or symbolic.stdout.strip()!=f'refs/heads/{branch}' or
+                    branch_tip.returncode or branch_tip.stdout.strip()!=meta.get('origin') or
+                    len(parents)!=2 or parents[0]!=head or parents[1]!=before):
+                    raise ManagerError('intervention_required','Durable squash evidence is incomplete or ambiguous; resources retained',5)
+                return ResultKind.NO_PENDING_WORK, None
+            if phase in {'captured','merge_started'} and head==before:
+                # The squash commit did not happen. Restore captured destination state once.
+                if meta.get('preserve_dirty'):
+                    from .worktree_lifecycle import WorktreeLifecycle
+                    lifecycle=WorktreeLifecycle.__new__(WorktreeLifecycle); lifecycle.config=type('RecoveryConfig',(),{'repo_root':self.repo.root,'backup_ref_prefix':meta.get('backup_ref_prefix','worktree-manager/backups')})(); lifecycle.git=self.repo; lifecycle.journal=self.journal
+                    lifecycle._restore_saved(transaction_id,meta)
+                self.journal.write_phase(transaction_id,'restored')
+                return ResultKind.SUCCESS,{'transaction_id':transaction_id,'phase':'restored','integrated':False}
+            squash=meta.get('squash')
+            if phase in {'merged','remove_started','removed'} and (not squash or head!=squash): raise ManagerError('intervention_required','Repository HEAD drifted from the recorded squash commit; resources retained',5)
+            if path.exists() or str(path) in registered:
+                if phase not in {'merged','remove_started'}: raise ManagerError('intervention_required','Worktree state is ambiguous; resources retained',5)
+                if self.repo.run(('-C',str(path),'status','--porcelain')).stdout: raise ManagerError('intervention_required','Worktree is dirty; resources retained',5)
+                self.journal.write_phase(transaction_id,'remove_started'); self.repo.run(('worktree','remove','--force','--',str(path)))
+            self.journal.write_phase(transaction_id,'removed')
+            ref=f"refs/heads/{branch}"; current=self.repo.run(('rev-parse',ref),check=False)
+            if current.returncode==0:
+                if current.stdout.strip()!=meta.get('origin'): raise ManagerError('intervention_required','Branch drifted; it was retained',5)
+                self.repo.run(('update-ref','-d',ref,meta['origin']))
+            if meta.get('preserve_dirty'):
+                from .worktree_lifecycle import WorktreeLifecycle
+                lifecycle=WorktreeLifecycle.__new__(WorktreeLifecycle); lifecycle.config=type('RecoveryConfig',(),{'repo_root':self.repo.root,'backup_ref_prefix':meta.get('backup_ref_prefix','worktree-manager/backups')})(); lifecycle.git=self.repo; lifecycle.journal=self.journal
+                lifecycle._restore_saved(transaction_id,meta)
+            self.journal.write_phase(transaction_id,'restored' if meta.get('preserve_dirty') else 'closed')
+            return ResultKind.SUCCESS,{'transaction_id':transaction_id,'phase':self.journal.read_phase(transaction_id),'integrated':True}
+        raise ManagerError('recovery_requires_intervention','Transaction requires its validated operation context; no effects were changed',5)

package/worktree_manager/state_digest.py

@@ -0,0 +1,40 @@
+"""Stable digest of repository and transaction state used by preflight plans."""
+import hashlib
+import json
+from pathlib import Path
+
+
+def canonical_hash(value):
+    return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()).hexdigest()
+
+
+def repository_state(repo_root, state_root):
+    import subprocess
+    root, state = Path(repo_root).resolve(), Path(state_root)
+    def git(*args):
+        return subprocess.run(["git", "-C", str(root), *args], check=True, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE).stdout.strip()
+    refs = git("for-each-ref", "--format=%(refname) %(objectname)").splitlines()
+    worktrees = git("worktree", "list", "--porcelain").splitlines()
+    index = Path(git("rev-parse", "--git-path", "index"))
+    if not index.is_absolute(): index = root / index
+    journal = []
+    transactions = state / "transactions"
+    if transactions.exists():
+        for entry in sorted(transactions.iterdir()):
+            if not entry.is_dir(): continue
+            phase_path = entry / "journal"
+            phase = phase_path.read_text().strip() if phase_path.is_file() else None
+            meta = (entry / "meta.json").read_bytes() if (entry / "meta.json").is_file() else b""
+            binding = (entry / "binding.json").read_bytes() if (entry / "binding.json").is_file() else b""
+            journal.append([entry.name, phase, hashlib.sha256(meta).hexdigest(), hashlib.sha256(binding).hexdigest()])
+    descriptors=[]
+    common=Path(git("rev-parse", "--git-common-dir"))
+    if not common.is_absolute(): common=root/common
+    directory=common/"worktree-manager"/"target-direct"
+    if directory.exists(): descriptors=sorted((p.relative_to(directory).as_posix(), hashlib.sha256(p.read_bytes()).hexdigest()) for p in directory.rglob("descriptor") if p.is_file())
+    state_obj={"head":git("rev-parse", "HEAD"),"index_sha256":hashlib.sha256(index.read_bytes()).hexdigest() if index.exists() else None,"refs":refs,"worktrees":worktrees,"journal":journal,"descriptors":descriptors}
+    return state_obj
+
+
+def state_digest(repo_root, state_root):
+    return canonical_hash(repository_state(repo_root, state_root))

package/worktree_manager/target_direct_adapter.py

@@ -0,0 +1,197 @@
+"""Strict reader for persisted target-direct descriptors."""
+from __future__ import annotations
+import re
+from pathlib import Path
+import hashlib, os, shutil, subprocess, tempfile
+import signal
+from .models import ManagerError, TargetDirectIdentity
+
+_KEYS=frozenset({'descriptor_version','operation','target_kind','target_repo','target_common_dir','parent_repo','parent_common_dir','submodule_path','gitlink_sha','target_head','base','base_sha','branch','worktree_path','link_parent','owner','phase','tx_id','index_snapshot_ref'})
+_SHA=re.compile(r'^[0-9a-fA-F]{40}$')
+_PHASES=frozenset('initial descriptor_written validated worktree_created ready snapshot_captured staged_started staged verified complete_validated remove_started removed closed reconciled index_reconcile_started index_restored recovered aborted blocked'.split())
+def load_descriptor(path: str|Path)->tuple[dict[str,str],TargetDirectIdentity]:
+    try: lines=Path(path).read_text(encoding='utf-8').splitlines()
+    except OSError as exc: raise ManagerError('invalid_descriptor','Target descriptor is unavailable',3) from exc
+    values={}
+    for line in lines:
+        if not line or '=' not in line or '\r' in line: raise ManagerError('invalid_descriptor','Malformed target descriptor',3)
+        key,value=line.split('=',1)
+        if key not in _KEYS or key in values or not value or '\n' in value: raise ManagerError('invalid_descriptor','Unknown, duplicate, or empty descriptor field',3)
+        values[key]=value
+    if values.keys()!=_KEYS: raise ManagerError('invalid_descriptor','Target descriptor is incomplete',3)
+    if values['descriptor_version']!='1' or values['target_kind']!='submodule' or values['link_parent']!='staged-only': raise ManagerError('invalid_descriptor','Unsupported target descriptor contract',3)
+    for key in ('target_repo','target_common_dir','parent_repo','parent_common_dir','worktree_path','index_snapshot_ref'):
+        if not Path(values[key]).is_absolute(): raise ManagerError('invalid_descriptor','Descriptor paths must be absolute',3)
+    if not re.fullmatch(r'[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*',values['submodule_path']) or any(p in ('.','..') for p in values['submodule_path'].split('/')): raise ManagerError('invalid_descriptor','Invalid submodule path',3)
+    for key in ('gitlink_sha','target_head','base_sha'):
+        if not _SHA.fullmatch(values[key]): raise ManagerError('invalid_descriptor','Invalid descriptor object ID',3)
+    if values['phase'] not in _PHASES: raise ManagerError('invalid_descriptor','Unknown target descriptor phase',3)
+    if values['operation'] not in {'create','link-parent','abort','complete'}: raise ManagerError('invalid_descriptor','Unknown target operation',3)
+    identity=TargetDirectIdentity(values['target_repo'],values['parent_repo'],values['submodule_path'],values['link_parent'])
+    return values,identity
+
+class TargetDirectAdapter:
+    """Operate on persisted submodule identity without deriving paths from cwd."""
+    def __init__(self, descriptor_path: str|Path):
+        self.path=Path(descriptor_path).resolve(); self.values,self.identity=load_descriptor(self.path)
+        self.parent=Path(self.values['parent_repo']); self.target=Path(self.values['target_repo'])
+        self.snapshot=Path(self.values['index_snapshot_ref'])
+        if self.values['link_parent']!='staged-only': raise ManagerError('invalid_descriptor','Only staged-only parent linking is supported',3)
+    @classmethod
+    def create(cls, descriptor_path: str|Path, target_repo: str|Path, parent_repo: str|Path,
+               submodule_path: str, work_id: str, base: str='main'):
+        """Create a target worktree and persist its complete recovery identity."""
+        target=Path(target_repo).resolve(); parent=Path(parent_repo).resolve()
+        def git(root,*args):
+            r=subprocess.run(['git','-C',str(root),*args],text=True,stdout=subprocess.PIPE,stderr=subprocess.PIPE)
+            if r.returncode: raise ManagerError('operation_failed',r.stderr.strip() or 'Git operation failed',5)
+            return r.stdout.strip()
+        if not re.fullmatch(r'[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*',submodule_path) or any(x in ('.','..') for x in submodule_path.split('/')):
+            raise ManagerError('invalid_identity','Invalid submodule path',3)
+        for root in (target,parent): git(root,'rev-parse','--show-toplevel')
+        base_sha=git(target,'rev-parse',f'refs/heads/{base}')
+        branch=f'worktree/{work_id}'; worktree=target/'.worktrees'/work_id
+        if worktree.exists() or subprocess.run(['git','-C',str(target),'show-ref','--verify','--quiet',f'refs/heads/{branch}']).returncode==0:
+            raise ManagerError('operation_failed','Target worktree or branch already exists',5)
+        git(target,'worktree','add','-b',branch,str(worktree),base)
+        head=git(worktree,'rev-parse','HEAD')
+        target_common=Path(git(target,'rev-parse','--git-common-dir')); target_common=(target/target_common).resolve() if not target_common.is_absolute() else target_common
+        parent_common=Path(git(parent,'rev-parse','--git-common-dir')); parent_common=(parent/parent_common).resolve() if not parent_common.is_absolute() else parent_common
+        parent_gitdir=Path(git(parent,'rev-parse','--git-dir')); parent_gitdir=(parent/parent_gitdir).resolve() if not parent_gitdir.is_absolute() else parent_gitdir
+        index=Path(git(parent,'rev-parse','--git-path','index')); index=index if index.is_absolute() else parent/index
+        tx='wt-'+work_id; snapshot=target_common/'worktree-manager'/'target-direct'/hashlib.sha256(work_id.encode()).hexdigest()/'snapshot'
+        values={'descriptor_version':'1','operation':'create','target_kind':'submodule','target_repo':str(target),'target_common_dir':str(target_common),'parent_repo':str(parent),'parent_common_dir':str(parent_common),'submodule_path':submodule_path,'gitlink_sha':git(parent,'rev-parse','HEAD'),'target_head':head,'base':base,'base_sha':base_sha,'branch':branch,'worktree_path':str(worktree),'link_parent':'staged-only','owner':'python','phase':'ready','tx_id':tx,'index_snapshot_ref':str(snapshot)}
+        path=Path(descriptor_path).resolve(); path.parent.mkdir(parents=True,exist_ok=True)
+        path.write_text(''.join(f'{k}={v}\n' for k,v in values.items()),encoding='utf-8'); path.chmod(0o600)
+        return cls(path)
+    def _git(self,root,*args,check=True):
+        result=subprocess.run(['git','-C',str(root),*args],text=True,stdout=subprocess.PIPE,stderr=subprocess.PIPE)
+        if check and result.returncode: raise ManagerError('operation_failed',result.stderr.strip() or 'Git operation failed',5)
+        return result
+    def link_parent(self):
+        """Stage the submodule commit as a gitlink and do not commit the parent."""
+        if self.values['phase'] not in {'ready','snapshot_captured','staged_started'}: raise ManagerError('invalid_descriptor','Descriptor phase does not permit parent linking',4)
+        worktree=Path(self.values['worktree_path'])
+        if worktree.is_dir():
+            self.values['target_head']=self._git(worktree,'rev-parse','HEAD').stdout.strip()
+        index=Path(self._git(self.parent,'rev-parse','--git-path','index').stdout.strip()); index=index if index.is_absolute() else self.parent/index
+        self.snapshot.mkdir(parents=True,exist_ok=True)
+        shutil.copy2(index,self.snapshot/'index.bytes')
+        (self.snapshot/'head.sha').write_text(self._git(self.parent,'rev-parse','HEAD').stdout.strip()+'\n')
+        (self.snapshot/'index.sha256').write_text(hashlib.sha256((self.snapshot/'index.bytes').read_bytes()).hexdigest()+'\n')
+        (self.snapshot/'entry').write_bytes(self._git(self.parent,'ls-files','--stage','--',self.identity.submodule_path).stdout.encode())
+        (self.snapshot/'entries').write_bytes(self._git(self.parent,'ls-files','--stage').stdout.encode())
+        self.values['phase']='snapshot_captured'; self._write_descriptor()
+        self.values['phase']='staged_started'; self._write_descriptor()
+        self._git(self.parent,'update-index','--add','--cacheinfo',f"160000,{self.values['target_head']},{self.identity.submodule_path}")
+        got=self._git(self.parent,'ls-files','--stage','--',self.identity.submodule_path).stdout.strip()
+        expected=f"160000 {self.values['target_head']} 0\t{self.identity.submodule_path}"
+        if got!=expected: self.abort(); raise ManagerError('operation_failed','Staged parent entry is not the expected gitlink',5)
+        self.values['gitlink_sha']=self.values['target_head']
+        index_path=Path(self._git(self.parent,'rev-parse','--git-path','index').stdout.strip()); index_path=index_path if index_path.is_absolute() else self.parent/index_path
+        (self.snapshot/'staged-index.sha256').write_text(hashlib.sha256(index_path.read_bytes()).hexdigest()+'\n')
+        self.values['phase']='staged'; self._write_descriptor()
+        return {'link_parent':'staged-only','gitlink':got,'parent_committed':False}
+    def abort(self):
+        if not (self.snapshot/'index.bytes').is_file(): raise ManagerError('invalid_descriptor','Index snapshot is unavailable',4)
+        expected=(self.snapshot/'index.sha256').read_text().strip()
+        index=Path(self._git(self.parent,'rev-parse','--git-path','index').stdout.strip()); index=index if index.is_absolute() else self.parent/index
+        actual=hashlib.sha256(index.read_bytes()).hexdigest()
+        head=self._git(self.parent,'rev-parse','HEAD').stdout.strip()
+        original=(self.snapshot/'head.sha').read_text().strip()
+        if head!=original or actual!=expected:
+            entry=(self.snapshot/'entry').read_text()
+            staged=self._git(self.parent,'ls-files','--stage','--',self.identity.submodule_path).stdout
+            staged_hash=(self.snapshot/'staged-index.sha256').read_text().strip() if (self.snapshot/'staged-index.sha256').exists() else ''
+            saved_entries=(self.snapshot/'entries').read_text().splitlines()
+            current_entries=self._git(self.parent,'ls-files','--stage').stdout.splitlines()
+            unchanged=sorted(current_entries)==sorted(saved_entries)
+            staged_gitlink=staged.strip()==f"160000 {self.values['target_head']} 0\t{self.identity.submodule_path}" and actual==staged_hash
+            if head!=original or not (unchanged or staged_gitlink):
+                raise ManagerError('intervention_required','Parent index drift is ambiguous; snapshot retained',5)
+        tmp=index.with_name(index.name+'.restore-'+os.urandom(4).hex())
+        shutil.copy2(self.snapshot/'index.bytes',tmp); os.replace(tmp,index)
+        self.values['phase']='aborted'; self._write_descriptor()
+        return {'aborted':True,'parent_commit_unchanged':True}
+    def complete(self):
+        if self.values['phase'] not in {'staged','verified','complete_validated','remove_started','removed','closed'}: raise ManagerError('invalid_descriptor','Descriptor phase does not permit complete',4)
+        staged=self._git(self.parent,'ls-files','--stage','--',self.identity.submodule_path).stdout.strip()
+        if staged!=f"160000 {self.values['target_head']} 0\t{self.identity.submodule_path}": raise ManagerError('intervention_required','Parent gitlink differs from the recorded target commit',5)
+        path=Path(self.values['worktree_path']); branch=self.values['branch']; head=self.values['target_head']
+        if path.exists():
+            if self._git(path,'status','--porcelain').stdout: raise ManagerError('intervention_required','Target worktree is dirty and was retained',5)
+            self._git(self.target,'worktree','remove',str(path))
+        if self._git(self.target,'show-ref','--verify','--quiet',f'refs/heads/{branch}',check=False).returncode==0:
+            self._git(self.target,'update-ref','-d',f'refs/heads/{branch}',head)
+        self.values['phase']='closed'; self._write_descriptor()
+        return {'completed':True,'parent_worktree':None}
+    def recover(self):
+        """Reconcile observed resources after interruption; repeated calls are safe."""
+        phase=self.values['phase']
+        if phase in {'aborted','blocked','closed','recovered'}:
+            return {'recovered':True,'classification':'A','phase':phase}
+        if phase in {'verified','staged','staged_started','snapshot_captured','descriptor_written','reconciled','index_reconcile_started'}:
+            # An interrupted descriptor transition is not proof that parent
+            # reconciliation completed. Persist a terminal blocked marker once;
+            # subsequent calls are idempotent and retain all recovery evidence.
+            if phase in {'descriptor_written','reconciled','index_reconcile_started','snapshot_captured','staged_started'}:
+                self.values['phase']='blocked'; self._write_descriptor()
+                raise ManagerError('intervention_required','Target recovery evidence is incomplete or ambiguous; descriptor and snapshot retained',6)
+            if not (self.snapshot/'index.bytes').is_file() or not (self.snapshot/'entries').is_file() or not (self.snapshot/'head.sha').is_file():
+                self.values['phase']='blocked'; self._write_descriptor()
+                raise ManagerError('intervention_required','Target recovery snapshot is incomplete; evidence retained',6)
+            if (self.snapshot/'index.bytes').exists():
+                original=(self.snapshot/'entries').read_text().splitlines()
+                current=self._git(self.parent,'ls-files','--stage').stdout.splitlines()
+                wanted=f"160000 {self.values['target_head']} 0\t{self.identity.submodule_path}"
+                original_target=[line for line in original if line.split('\t',1)[-1]==self.identity.submodule_path]
+                current_target=[line for line in current if line.split('\t',1)[-1]==self.identity.submodule_path]
+                # A completed link-parent is our intentional index mutation, not
+                # proof of arbitrary drift. Compare the full logical index while
+                # allowing only that exact gitlink delta; raw index bytes include
+                # Git's refreshable stat cache and are not a semantic snapshot.
+                expected=[line for line in original if line.split('\t',1)[-1]!=self.identity.submodule_path]
+                expected.append(wanted)
+                unchanged = sorted(current) == sorted(original)
+                if phase == 'staged':
+                    if current_target == [wanted] and sorted(current) == sorted(expected):
+                        raise ManagerError('intervention_required','Parent gitlink is intentionally staged; snapshot retained',6)
+                    raise ManagerError('intervention_required','Parent index drift is ambiguous; snapshot retained',6)
+                if unchanged:
+                    self.abort()
+                elif current_target == [wanted] and sorted(current) == sorted(expected):
+                    self.abort()
+                else:
+                    raise ManagerError('intervention_required','Parent index drift is ambiguous; snapshot retained',6)
+            self.values['phase']='recovered'; self._write_descriptor()
+            return {'recovered':True,'classification':'A','phase':'recovered'}
+        if phase in {'complete_validated','remove_started','removed'}:
+            path=Path(self.values['worktree_path'])
+            registered=str(path) in [line[9:] for line in self._git(self.target,'worktree','list','--porcelain').stdout.splitlines() if line.startswith('worktree ')]
+            if registered:
+                if phase not in {'complete_validated','remove_started'} or not path.exists(): raise ManagerError('intervention_required','Target worktree registration drifted; retained',5)
+                if self._git(path,'status','--porcelain').stdout: raise ManagerError('intervention_required','Target worktree is dirty; retained',5)
+                if phase=='complete_validated': self.values['phase']='remove_started'; self._write_descriptor()
+                self._git(self.target,'worktree','remove',str(path))
+            if path.exists(): raise ManagerError('intervention_required','Target worktree removal is incomplete',5)
+            self.values['phase']='removed'; self._write_descriptor()
+            branch=f"refs/heads/{self.values['branch']}"; current=self._git(self.target,'rev-parse',branch,check=False)
+            if current.returncode==0:
+                if current.stdout.strip()!=self.values['target_head']: raise ManagerError('intervention_required','Target branch drifted; retained',5)
+                self._git(self.target,'update-ref','-d',branch,self.values['target_head'])
+            self.values['phase']='closed'; self._write_descriptor()
+            return {'recovered':True,'classification':'A','phase':'closed'}
+        raise ManagerError('recovery_requires_intervention','Descriptor phase requires manual intervention',5)
+    def _write_descriptor(self):
+        self.path.parent.mkdir(parents=True,exist_ok=True)
+        text=''.join(f'{k}={v}\n' for k,v in self.values.items())
+        fd,tmp=tempfile.mkstemp(dir=self.path.parent,prefix='.descriptor-')
+        try:
+            with os.fdopen(fd,'w') as out: out.write(text); out.flush(); os.fsync(out.fileno())
+            os.chmod(tmp,0o600); os.replace(tmp,self.path)
+            # Test-only barrier models process death after a durable descriptor
+            # transition and before the next Git side effect.
+            if os.environ.get('WORKTREE_MANAGER_TEST_CRASH_AFTER_DESCRIPTOR_PHASE') == self.values['phase']:
+                os.kill(os.getpid(), signal.SIGKILL)
+        finally:
+            if os.path.exists(tmp): os.unlink(tmp)

package/worktree_manager/transaction_journal.py

@@ -0,0 +1,36 @@
+"""Atomic transaction journal storage."""
+from __future__ import annotations
+import os, tempfile
+import json
+from pathlib import Path
+from .models import ManagerError
+PHASES = frozenset({'captured','merge_started','merged','pending_manual','restored','created','removed','closed','remove_started','captured_dirty','restoring'})
+class TransactionJournal:
+    def __init__(self, state_root: str | Path): self.root = Path(state_root).resolve() / 'transactions'
+    def directory(self, tx: str) -> Path:
+        if not tx or '/' in tx or tx.startswith(('.', '-')): raise ManagerError('invalid_identity','Invalid transaction identifier',3)
+        return self.root / tx
+    @staticmethod
+    def _atomic(path: Path, text: str) -> None:
+        path.parent.mkdir(parents=True,exist_ok=True); fd,name=tempfile.mkstemp(prefix='.tmp-',dir=path.parent)
+        try:
+            with os.fdopen(fd,'w',encoding='utf-8') as stream: stream.write(text); stream.flush(); os.fsync(stream.fileno())
+            os.chmod(name,0o600); os.replace(name,path)
+        finally:
+            if os.path.exists(name): os.unlink(name)
+    def write_phase(self,tx: str,phase: str) -> None:
+        if phase not in PHASES: raise ManagerError('invalid_journal','Unknown transaction phase',3)
+        self._atomic(self.directory(tx)/'journal',phase+'\n')
+    def read_phase(self,tx: str) -> str:
+        try: value=(self.directory(tx)/'journal').read_text(encoding='utf-8')
+        except OSError as exc: raise ManagerError('invalid_journal','Transaction journal is unavailable',3) from exc
+        phase=value.removesuffix('\n')
+        if phase not in PHASES or '\n' in phase: raise ManagerError('invalid_journal','Transaction journal is corrupt',3)
+        return phase
+    def write_binding(self, tx: str, binding: dict) -> None:
+        self._atomic(self.directory(tx)/'binding.json', json.dumps(binding,sort_keys=True,separators=(',',':'))+'\n')
+    def read_binding(self, tx: str) -> dict:
+        try: value=json.loads((self.directory(tx)/'binding.json').read_text(encoding='utf-8'))
+        except (OSError,ValueError) as exc: raise ManagerError('intervention_required','Transaction binding is unavailable or corrupt',5) from exc
+        if not isinstance(value,dict): raise ManagerError('intervention_required','Transaction binding is invalid',5)
+        return value