worktree-for-agents 1.0.1 → 1.1.0

package/docs/mcp-contract.md

@@ -76,3 +76,26 @@ The dry run publishes the composed `commit_subject` and `commit_body`; execute p
 to the lifecycle. If missing, the manager uses the neutral fallback
 `Complete <work_id> (generic closure)` / `No delivery description was available
 at closure time.`.
+
+## Merge strategy
+
+`worktree_complete` accepts the optional string `merge_strategy` with the enum
+values `squash` (default) and `preserve-history`. Squash integrates the branch
+as one commit; preserve-history records an explicit merge commit that keeps the
+branch commits. Neither strategy uses a fast-forward.
+
+The field is validated as a string and against the enum before any mutation; a
+value outside the enum is rejected as `invalid_request` with exit code 3. It is
+included in the plan hash only for `worktree_complete`, so a preflight for one
+strategy cannot execute the other and reports `plan_mismatch` with exit code 5.
+
+A dry run publishes `data.merge_strategy` and the planned `mutations`:
+`squash_merge` for squash, or `merge_no_ff` for preserve-history, followed by
+`remove_worktree` and `delete_branch` in both cases. Execute returns
+`merge_strategy` and `integrated_commit`; `squash_commit` is present only for
+squash and equals `integrated_commit`. The transaction records the strategy and
+the integrated commit. Recovery validates the parent shape recorded by the
+strategy, reads a transaction without the field as squash, and reports an
+unknown value as `invalid_journal` with exit code 5 while retaining evidence.
+With `preserve-history`, a branch with no commits ahead of the base fails as
+`operation_failed` with exit code 5 without a transaction or mutation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worktree-for-agents",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Standalone Git worktree manager with a stdio MCP service usable by any coding agent",
   "type": "module",
   "engines": {

package/worktree_manager/__init__.py

@@ -1,2 +1,2 @@
 """Standalone Python worktree management backend."""
-__version__ = '1.0.1'
+__version__ = '1.1.0'

package/worktree_manager/cli.py

@@ -6,7 +6,7 @@ from .configuration import Configuration
 from .git_repository import GitRepository
 from .models import ManagerError,OperationResult,ResultKind
 from .output import emit
-from .worktree_lifecycle import WorktreeLifecycle
+from .worktree_lifecycle import WorktreeLifecycle, MERGE_STRATEGIES, DEFAULT_MERGE_STRATEGY
 from .recovery_manager import RecoveryManager
 from .target_direct_adapter import TargetDirectAdapter
 from . import __version__ as VERSION
@@ -18,7 +18,7 @@ def _parser():
     for name in ('create','complete','cleanup'):
         p=sub.add_parser(name); p.add_argument('work_id'); p.add_argument('--base');
         if name=='cleanup': p.add_argument('--discard',action='store_true')
-        if name=='complete': p.add_argument('--preserve-dirty',action='store_true'); p.add_argument('--title'); p.add_argument('--body')
+        if name=='complete': p.add_argument('--preserve-dirty',action='store_true'); p.add_argument('--title'); p.add_argument('--body'); p.add_argument('--merge-strategy',choices=MERGE_STRATEGIES,default=DEFAULT_MERGE_STRATEGY)
         if name=='create':
             p.add_argument('--init-submodules',action='store_true'); p.add_argument('--prepare',action='store_true'); p.add_argument('--verify',action='store_true')
     p=sub.add_parser('recover'); p.add_argument('transaction_id',nargs='?')
@@ -120,7 +120,7 @@ def main(argv=None)->int:
                 result=OperationResult(operation,data=data)
             elif operation=='cleanup': result=OperationResult(operation,data=lifecycle.cleanup(args.work_id,args.discard,args.base or 'main'))
             elif operation=='complete':
-                data=lifecycle.complete(args.work_id,args.base or 'main',args.preserve_dirty,commit_title=args.title,commit_body=args.body)
+                data=lifecycle.complete(args.work_id,args.base or 'main',args.preserve_dirty,commit_title=args.title,commit_body=args.body,merge_strategy=args.merge_strategy)
                 data['merge']='success'
                 result=OperationResult(operation,data=data)
         if operation=='list' and not args.json:

package/worktree_manager/mcp_contract.py

@@ -5,13 +5,14 @@ import pathlib
 
 CONTRACT_VERSION = 1
 from . import __version__ as TOOL_VERSION
+from .worktree_lifecycle import MERGE_STRATEGIES
 TOOL_NAMES = (
     "worktree_create", "worktree_complete", "worktree_cleanup",
     "worktree_recover", "worktree_list", "worktree_prune", "worktree_status",
 )
 FIELDS = {
     "worktree_create": {"repo", "work_id", "base", "dry_run", "parent_repo", "submodule_path", "confirm", "plan_hash", "init_submodules", "prepare", "verify"},
-    "worktree_complete": {"repo", "work_id", "base", "dry_run", "authorization", "confirm", "plan_hash", "transaction_id", "preserve_dirty", "target_direct", "parent_repo", "commit_title", "commit_body"},
+    "worktree_complete": {"repo", "work_id", "base", "dry_run", "authorization", "confirm", "plan_hash", "transaction_id", "preserve_dirty", "target_direct", "parent_repo", "commit_title", "commit_body", "merge_strategy"},
     "worktree_cleanup": {"repo", "work_id", "base", "dry_run", "authorization", "confirm", "plan_hash", "discard", "discard_consent"},
     "worktree_recover": {"repo", "transaction_id", "dry_run", "authorization", "confirm", "target_direct", "parent_repo"},
     "worktree_list": {"repo"}, "worktree_prune": {"repo", "dry_run", "authorization", "confirm", "plan_hash"},
@@ -40,9 +41,11 @@ def validate_request(tool: str, request: dict) -> dict:
     for key in ("dry_run", "discard", "preserve_dirty", "discard_consent", "target_direct", "confirm", "init_submodules", "prepare", "verify"):
         if key in request and type(request[key]) is not bool:
             raise ValueError(f"{key}_must_be_boolean")
-    for key in ("work_id", "base", "transaction_id", "authorization", "parent_repo", "submodule_path", "commit_title", "commit_body"):
+    for key in ("work_id", "base", "transaction_id", "authorization", "parent_repo", "submodule_path", "commit_title", "commit_body", "merge_strategy"):
         if key in request and not isinstance(request[key], str):
             raise ValueError(f"{key}_must_be_string")
+    if tool == "worktree_complete" and "merge_strategy" in request and request["merge_strategy"] not in MERGE_STRATEGIES:
+        raise ValueError("merge_strategy_invalid")
     if tool in {"worktree_create", "worktree_complete", "worktree_cleanup", "worktree_status"} and not request.get("work_id"):
         raise ValueError("work_id_required")
     if tool == "worktree_create" and bool(request.get("parent_repo")) != bool(request.get("submodule_path")):

package/worktree_manager/mcp_operations.py

@@ -32,7 +32,7 @@ def call(tool, request):
             req["transaction_id"] = __import__("uuid").uuid4().hex
         fields = ["operation", "repo", "work_id", "confirm", "transaction_id", "base", "preserve_dirty", "discard", "discard_consent", "target_direct", "parent_repo", "submodule_path", "state_digest"]
         if tool == "worktree_complete":
-            fields = fields + ["commit_title", "commit_body"]
+            fields = fields + ["commit_title", "commit_body", "merge_strategy"]
         def plan_for(digest):
             return {key: (tool if key == "operation" else digest if key == "state_digest" else bool(req.get("authorization")) if key == "confirm" else req.get(key)) for key in fields}
         if dry:
@@ -117,8 +117,9 @@ def call(tool, request):
             if lifecycle.git.run(("-C", str(path), "status", "--porcelain", "--untracked-files=all")).stdout: raise ManagerError("intervention_required", "Worktree has uncommitted changes; it was retained", 5)
             from .commit_message import compose_commit_message
             _subject, _body = compose_commit_message(req["work_id"], req.get("commit_title"), req.get("commit_body"))
-            data = {"planned": True, "work_id": req["work_id"], "transaction_id":req.get("transaction_id"), "preflight": "passed", "mutations": ["squash_merge", "remove_worktree", "delete_branch"], "plan_hash":req.get("_computed_plan_hash"), "state_digest":digest, "commit_subject": _subject, "commit_body": _body}
-        else: data = lifecycle.complete(req["work_id"], req.get("base", "main"), req.get("preserve_dirty", False), req.get("transaction_id"), req.get("plan_hash"), req)
+            strategy = req.get("merge_strategy", "squash")
+            data = {"planned": True, "work_id": req["work_id"], "transaction_id":req.get("transaction_id"), "preflight": "passed", "merge_strategy": strategy, "mutations": ["squash_merge" if strategy == "squash" else "merge_no_ff", "remove_worktree", "delete_branch"], "plan_hash":req.get("_computed_plan_hash"), "state_digest":digest, "commit_subject": _subject, "commit_body": _body}
+        else: data = lifecycle.complete(req["work_id"], req.get("base", "main"), req.get("preserve_dirty", False), req.get("transaction_id"), req.get("plan_hash"), req, merge_strategy=req.get("merge_strategy", "squash"))
     elif tool == "worktree_cleanup":
         if req.get("discard") and req.get("discard_consent") is not True:
             raise ManagerError("discard_consent_required", "Separate explicit discard consent is required", 3)

package/worktree_manager/mcp_server.py

@@ -17,7 +17,8 @@ def schemas():
               "init_submodules":{"type":"boolean"}, "prepare":{"type":"boolean"}, "verify":{"type":"boolean"},
              "dry_run": {"type": "boolean"}, "discard": {"type": "boolean"},
              "discard_consent": {"type": "boolean"}, "preserve_dirty": {"type": "boolean"},
-             "commit_title": {"type": "string"}, "commit_body": {"type": "string"}}
+             "commit_title": {"type": "string"}, "commit_body": {"type": "string"},
+             "merge_strategy": {"type": "string", "enum": ["squash", "preserve-history"]}}
     props.update({"parent_repo": {"type": "string"}, "submodule_path": {"type": "string"},
                   "target_direct": {"type": "boolean"}})
     return [{"name": name, "description": "Manage repository worktrees", "inputSchema": {

package/worktree_manager/recovery_manager.py

@@ -6,6 +6,7 @@ from .models import ManagerError, ResultKind
 from .transaction_journal import TransactionJournal
 from .git_repository import GitRepository
 from .lock_manager import LockManager
+from .worktree_lifecycle import MERGE_STRATEGIES
 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
@@ -61,6 +62,8 @@ class RecoveryManager:
             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)
+            merge_strategy=meta.get('merge_strategy','squash')
+            if merge_strategy not in MERGE_STRATEGIES: raise ManagerError('invalid_journal','Transaction merge strategy is not recognised; resources retained',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
@@ -78,13 +81,16 @@ class RecoveryManager:
                 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}
+                expected_parents=3 if merge_strategy=='preserve-history' else 2
+                valid_parents=len(parents)==expected_parents and parents[0]==head and parents[1]==before
+                if merge_strategy=='preserve-history' and valid_parents: valid_parents=parents[2]==meta.get('origin')
                 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)
+                    not valid_parents):
+                    raise ManagerError('intervention_required','Durable integration 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.
@@ -94,8 +100,8 @@ class RecoveryManager:
                     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)
+            integrated=meta.get('integrated') or meta.get('squash')
+            if phase in {'merged','remove_started','removed'} and (not integrated or head!=integrated): raise ManagerError('intervention_required','Repository HEAD drifted from the recorded integrated 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)

package/worktree_manager/worktree_lifecycle.py

@@ -21,6 +21,13 @@ def validate_work_id(value: str) -> str:
         raise ManagerError('invalid_identity','Invalid work identifier',3)
     return value
 
+MERGE_STRATEGIES = ('squash', 'preserve-history')
+DEFAULT_MERGE_STRATEGY = 'squash'
+def validate_merge_strategy(value: str) -> str:
+    if value not in MERGE_STRATEGIES:
+        raise ManagerError('invalid_merge_strategy','Invalid merge strategy',3)
+    return value
+
 class WorktreeLifecycle:
     def __init__(self, config: Configuration):
         self.config=config
@@ -132,15 +139,18 @@ class WorktreeLifecycle:
             self.git.run(('worktree','remove',*(('--force',) if discard else ()),str(path)))
             self.git.run(('branch','-D' if discard else '-d',branch))
         return {'cleaned':work_id,'branch':branch,'worktree':str(path)}
-    def complete(self,work_id: str,base: str,preserve_dirty: bool=False,transaction_id: str|None=None,plan_hash: str|None=None,request:dict|None=None,commit_title=None,commit_body=None)->dict[str,str]:
-        """Squash a worktree branch and retire it only after verified success.
+    def complete(self,work_id: str,base: str,preserve_dirty: bool=False,transaction_id: str|None=None,plan_hash: str|None=None,request:dict|None=None,commit_title=None,commit_body=None,merge_strategy: str|None=None)->dict[str,str]:
+        """Integrate a worktree branch and retire it only after verified success.
 
-        Dirty-destination preservation is intentionally rejected until its capture
-        and restoration protocol is available; it must never silently discard data.
+        Squash produces one commit on the base branch. Preserve-history records
+        an explicit merge commit that keeps the branch commits. Dirty-destination
+        state is captured and restored around the integration in both strategies.
         """
         branch=self._branch(work_id); base=self._base(base); path=self._path(work_id)
         if commit_title is None and isinstance(request,dict): commit_title=request.get('commit_title')
         if commit_body is None and isinstance(request,dict): commit_body=request.get('commit_body')
+        if merge_strategy is None and isinstance(request,dict): merge_strategy=request.get('merge_strategy')
+        merge_strategy=validate_merge_strategy(merge_strategy or DEFAULT_MERGE_STRATEGY)
         registered={item['path'] for item in self.list()}
         if str(path) not in registered or not path.is_dir():
             raise ManagerError('invalid_identity','Worktree identity does not match registration',3)
@@ -153,6 +163,12 @@ class WorktreeLifecycle:
         status=self.git.run(('status','--porcelain','--untracked-files=all')).stdout
         if status and not preserve_dirty:
             raise ManagerError('intervention_required','Destination has uncommitted changes; use --preserve-dirty to retain them',5)
+        if merge_strategy=='preserve-history':
+            ahead=self.git.run(('rev-list','--count',f'{base}..{branch}'),check=False)
+            if ahead.returncode:
+                raise ManagerError('operation_failed','Could not inspect the branch ahead of the base; nothing was merged',5)
+            if (ahead.stdout.strip() or '0')=='0':
+                raise ManagerError('operation_failed','Branch has no commits ahead of the base; nothing was merged',5)
         state=self.state_root
         locks=LockManager(state/self.config.lock_dir)
         tx=transaction_id or uuid.uuid4().hex
@@ -161,7 +177,7 @@ class WorktreeLifecycle:
             raise ManagerError('intervention_required','Transaction binding already exists; execute is blocked',5)
         before=self.git.head(); origin=self.git.run(('rev-parse',f'refs/heads/{branch}')).stdout.strip()
         meta={'work_id':work_id,'base':base,'branch':branch,'path':str(path),'before':before,'origin':origin,
-              'preserve_dirty':bool(status),'tracked_ref':None,'untracked_ref':None,
+              'preserve_dirty':bool(status),'merge_strategy':merge_strategy,'tracked_ref':None,'untracked_ref':None,
               'backup_ref_prefix':self.config.backup_ref_prefix}
         meta_path=journal.directory(tx)/'meta.json'
         def save_meta(phase):
@@ -182,6 +198,7 @@ class WorktreeLifecycle:
             try:
                 journal.write_binding(tx, {'transaction_id':tx,'repo':str(self.config.repo_root.resolve()),'work_id':work_id,
                     'operation':'worktree_complete','request':request or {},'plan_hash':plan_hash,
+                    'merge_strategy':merge_strategy,
                     'state_digest':__import__('worktree_manager.state_digest',fromlist=['state_digest']).state_digest(self.config.repo_root,state),
                     'created_at':__import__('datetime').datetime.now(__import__('datetime').timezone.utc).isoformat(),
                     'phase':'prepared','base':base,'before':before,'origin':origin})
@@ -215,19 +232,33 @@ class WorktreeLifecycle:
                 meta['commit_subject']=subject
                 meta['commit_body']=body
                 save_meta('merge_started')
-                merged=self.git.run(('merge','--squash',branch),check=False)
-                if merged.returncode or self.git.run(('diff','--cached','--quiet'),check=False).returncode==0:
-                    self.git.run(('reset','--merge'),check=False)
-                    save_meta('pending_manual')
-                    raise ManagerError('operation_failed','Squash merge failed or produced no changes; worktree and branch retained',5)
-                commit_args=['commit','-m',subject]
-                if body:
-                    commit_args += ['-m',body]
-                self.git.run(tuple(commit_args))
-                after=self.git.head()
-                if after==before or len(self.git.run(('rev-list','--parents','-n','1',after)).stdout.split())!=2:
-                    save_meta('pending_manual'); raise ManagerError('operation_failed','Squash commit verification failed; resources retained',5)
-                meta['squash']=after; save_meta('merged')
+                if merge_strategy=='preserve-history':
+                    message=subject+('\n\n'+body if body else '')
+                    merged=self.git.run(('merge','--no-ff','-m',message,branch),check=False)
+                    if merged.returncode:
+                        self.git.run(('merge','--abort'),check=False)
+                        save_meta('pending_manual')
+                        raise ManagerError('operation_failed','Preserve-history merge failed; worktree and branch retained',5)
+                    after=self.git.head()
+                    parents=self.git.run(('rev-list','--parents','-n','1',after)).stdout.split()
+                    if after==before or len(parents)!=3 or parents[0]!=after or parents[1]!=before or parents[2]!=origin:
+                        save_meta('pending_manual'); raise ManagerError('operation_failed','Merge commit verification failed; resources retained',5)
+                else:
+                    merged=self.git.run(('merge','--squash',branch),check=False)
+                    if merged.returncode or self.git.run(('diff','--cached','--quiet'),check=False).returncode==0:
+                        self.git.run(('reset','--merge'),check=False)
+                        save_meta('pending_manual')
+                        raise ManagerError('operation_failed','Squash merge failed or produced no changes; worktree and branch retained',5)
+                    commit_args=['commit','-m',subject]
+                    if body:
+                        commit_args += ['-m',body]
+                    self.git.run(tuple(commit_args))
+                    after=self.git.head()
+                    if after==before or len(self.git.run(('rev-list','--parents','-n','1',after)).stdout.split())!=2:
+                        save_meta('pending_manual'); raise ManagerError('operation_failed','Squash commit verification failed; resources retained',5)
+                meta['integrated']=after
+                if merge_strategy=='squash': meta['squash']=after
+                save_meta('merged')
                 self.git.run(('worktree','remove','--force','--',str(path)))
                 if path.exists() or str(path) in {item['path'] for item in self.list()}:
                     save_meta('pending_manual'); raise ManagerError('operation_failed','Worktree removal could not be verified',5)
@@ -236,10 +267,16 @@ class WorktreeLifecycle:
                     save_meta('pending_manual'); raise ManagerError('operation_failed','Branch changed; it was retained',5)
                 self.git.run(('update-ref','-d',f'refs/heads/{branch}',origin)); save_meta('closed')
                 if status:
-                    meta['squash']=after; save_meta('merged')
+                    meta['integrated']=after
+                    if merge_strategy=='squash': meta['squash']=after
+                    save_meta('merged')
                     self._restore_saved(tx,meta)
                     save_meta('restored')
-                return {'completed':work_id,'branch':branch,'base_branch':base,'worktree':str(path),'squash_commit':after,'transaction_id':tx,'commit_subject':subject,'commit_body':body}
+                result={'completed':work_id,'branch':branch,'base_branch':base,'worktree':str(path),
+                        'integrated_commit':after,'merge_strategy':merge_strategy,
+                        'transaction_id':tx,'commit_subject':subject,'commit_body':body}
+                if merge_strategy=='squash': result['squash_commit']=after
+                return result
             finally: locks.release()
 
     def _restore_saved(self,tx,meta):