worktree-for-agents 0.0.0-stage → 1.0.0

package/scripts/python.mjs

@@ -0,0 +1,69 @@
+import { spawnSync } from "node:child_process";
+
+/**
+ * Resolve the Python interpreter used by the packaged launchers.
+ * Order: WORKTREE_MANAGER_PYTHON override, then platform defaults
+ * (POSIX python3; win32 python then python3). Returns the binary name
+ * or absolute path, or null when no candidate exists.
+ */
+export function candidates() {
+  const override = process.env.WORKTREE_MANAGER_PYTHON;
+  if (override && override.trim() !== "") {
+    return [override];
+  }
+  if (process.platform === "win32") {
+    return ["python", "python3"];
+  }
+  return ["python3"];
+}
+
+/**
+ * Probe a candidate interpreter with `import sys` version output.
+ * Returns { bin, version } on Python >= 3.9, or { bin, version, cause }
+ * when the interpreter is missing or too old.
+ */
+export function probeCandidate(bin) {
+  const result = spawnSync(bin, ["-c", "import sys; print('%d.%d' % sys.version_info[:2])"], {
+    encoding: "utf8",
+  });
+  if (result.error || result.status !== 0) {
+    return { bin, version: null, cause: "not_found" };
+  }
+  const version = String(result.stdout || "").trim();
+  const match = /^(\d+)\.(\d+)$/.exec(version);
+  if (!match) {
+    return { bin, version: null, cause: "unparseable_version" };
+  }
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  if (major < 3 || (major === 3 && minor < 9)) {
+    return { bin, version, cause: "too_old" };
+  }
+  return { bin, version };
+}
+
+/**
+ * Resolve and probe in order. Returns the first usable interpreter
+ * as { bin, version }, or { bin: null, version: null, cause } when
+ * none is usable. Never throws for a missing interpreter.
+ */
+export function probePython() {
+  let last = { bin: null, version: null, cause: "not_found" };
+  for (const bin of candidates()) {
+    const probed = probeCandidate(bin);
+    if (probed.version && !probed.cause) {
+      return { bin: probed.bin, version: probed.version };
+    }
+    last = { bin: probed.bin, version: probed.version, cause: probed.cause || "not_found" };
+  }
+  return last;
+}
+
+/**
+ * Resolve the interpreter binary name without probing.
+ * Returns the first candidate, or null when none exists.
+ */
+export function resolvePython() {
+  const list = candidates();
+  return list.length > 0 ? list[0] : null;
+}

package/setup.mjs

@@ -0,0 +1,208 @@
+import { existsSync, readFileSync, writeFileSync, copyFileSync, renameSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir, homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdtempSync } from "node:fs";
+import { probePython } from "./scripts/python.mjs";
+
+const packageDir = dirname(fileURLToPath(import.meta.url));
+
+function readPackage() {
+  const raw = readFileSync(join(packageDir, "package.json"), "utf8");
+  return JSON.parse(raw);
+}
+
+function globalFlowtaskDir() {
+  if (process.platform === "win32") {
+    const base = process.env.APPDATA || join(homedir(), "AppData", "Roaming");
+    return join(base, "FlowTask", "worktree-manager");
+  }
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg ? join(xdg, "flowtask") : join(homedir(), ".config", "flowtask");
+  return join(base, "worktree-manager");
+}
+
+function opencodeConfigCandidates() {
+  if (process.platform === "win32") {
+    const base = process.env.APPDATA || join(homedir(), "AppData", "Roaming");
+    return [join(base, "opencode", "opencode.json")];
+  }
+  const xdg = process.env.XDG_CONFIG_HOME;
+  if (xdg) {
+    return [join(xdg, "opencode", "opencode.json")];
+  }
+  return [join(homedir(), ".config", "opencode", "opencode.json")];
+}
+
+function checkoutStatus(dir) {
+  if (!dir || !existsSync(join(dir, "worktree_manager", "__main__.py"))) {
+    return { present: false };
+  }
+  const transport = join(dir, "worktree_manager", "mcp_transport.py");
+  return { present: true, mcpTransport: existsSync(transport) };
+}
+
+function collectStatus() {
+  const pkg = readPackage();
+  const probed = probePython();
+  const npmPackage = {
+    kind: "npm package",
+    path: packageDir,
+    version: pkg.version,
+    active: true,
+  };
+  const globalDir = globalFlowtaskDir();
+  const globalStatus = checkoutStatus(globalDir);
+  const globalCopy = {
+    kind: "FlowTask global copy",
+    path: globalDir,
+    present: globalStatus.present || false,
+  };
+  const submoduleDir = resolve(join(process.cwd(), ".flowtask", "scripts", "worktree-manager"));
+  const submoduleStatus = checkoutStatus(submoduleDir);
+  const submodule = {
+    kind: "local submodule",
+    path: submoduleDir,
+    present: submoduleStatus.present || false,
+  };
+  const configPaths = opencodeConfigCandidates();
+  const configPath = configPaths[0];
+  let opencode = { path: configPath, present: existsSync(configPath), entries: {} };
+  if (opencode.present) {
+    try {
+      const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+      const mcp = (parsed && parsed.mcp) || {};
+      opencode.entries = mcp;
+    } catch {
+      opencode.parseError = true;
+    }
+  }
+  const expectedCommand = ["node", join(packageDir, "mcp-server.mjs")];
+  let activeEntry = "npm package";
+  const refsThisPackage = [];
+  for (const [name, value] of Object.entries(opencode.entries || {})) {
+    const cmd = value && value.command;
+    if (Array.isArray(cmd) && cmd.length === 2 && cmd[0] === "node" && typeof cmd[1] === "string") {
+      if (resolve(cmd[1]) === resolve(expectedCommand[1])) {
+        refsThisPackage.push(name);
+      }
+    }
+  }
+  return {
+    version: pkg.version,
+    packagePath: packageDir,
+    interpreter: probed,
+    installations: [npmPackage, globalCopy, submodule],
+    active: activeEntry,
+    opencode,
+    expectedCommand,
+    refsThisPackage,
+  };
+}
+
+function printHuman(status) {
+  const lines = [];
+  lines.push(`worktree-for-agents ${status.version}`);
+  lines.push(`package: ${status.packagePath}`);
+  if (status.interpreter.version) {
+    lines.push(`python: ${status.interpreter.bin} ${status.interpreter.version}`);
+  } else {
+    lines.push(`python: not found (requires 3.9+)`);
+  }
+  lines.push("installations:");
+  for (const inst of status.installations) {
+    if (inst.kind === "npm package") {
+      lines.push(`  - npm package: ${inst.path} (version ${inst.version}, active)`);
+    } else {
+      lines.push(`  - ${inst.kind}: ${inst.path} (${inst.present ? "present" : "absent"})`);
+    }
+  }
+  lines.push(`active: ${status.active}`);
+  lines.push(`opencode config: ${status.opencode.path} (${status.opencode.present ? "present" : "absent"})`);
+  const names = Object.keys(status.opencode.entries || {});
+  if (names.length === 0) {
+    lines.push("mcp entries: (none)");
+  } else {
+    lines.push("mcp entries:");
+    for (const name of names) {
+      const marker = status.refsThisPackage.includes(name) ? " (references this package)" : "";
+      lines.push(`  - ${name}${marker}`);
+    }
+  }
+  process.stdout.write(lines.join("\n") + "\n");
+}
+
+function deepEqual(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function runWriteOpencode() {
+  const status = collectStatus();
+  const candidates = opencodeConfigCandidates();
+  const configPath = candidates[0];
+  const configDir = dirname(configPath);
+  if (!existsSync(configDir)) {
+    process.stderr.write(
+      `OpenCode config directory does not exist: ${configDir}. Create it manually or run OpenCode once, then rerun with --write-opencode.\n`
+    );
+    process.exit(1);
+  }
+  let parsed = {};
+  let raw = null;
+  if (existsSync(configPath)) {
+    raw = readFileSync(configPath, "utf8");
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      process.stderr.write(`OpenCode config is not valid JSON: ${configPath}. Fix it manually and rerun.\n`);
+      process.exit(1);
+    }
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    parsed = {};
+  }
+  if (!parsed.mcp || typeof parsed.mcp !== "object" || Array.isArray(parsed.mcp)) {
+    parsed.mcp = {};
+  }
+  const expected = { type: "local", command: ["node", join(packageDir, "mcp-server.mjs")], enabled: true };
+  const existing = parsed.mcp["worktree-for-agents"];
+  if (existing !== undefined) {
+    if (deepEqual(existing, expected)) {
+      process.stdout.write("opencode.json already configured for worktree-for-agents.\n");
+      process.exit(0);
+    }
+    process.stderr.write(
+      `Refusing to overwrite mcp.worktree-for-agents: existing value differs from expected.\nExisting: ${JSON.stringify(existing)}\nExpected: ${JSON.stringify(expected)}\n`
+    );
+    process.exit(1);
+  }
+  parsed.mcp["worktree-for-agents"] = expected;
+  const next = JSON.stringify(parsed, null, 2) + "\n";
+  if (existsSync(configPath)) {
+    copyFileSync(configPath, `${configPath}.bak`);
+  }
+  const stagingDir = mkdtempSync(join(tmpdir(), "worktree-for-agents-"));
+  try {
+    const staging = join(stagingDir, "opencode.json");
+    writeFileSync(staging, next, "utf8");
+    JSON.parse(readFileSync(staging, "utf8"));
+    mkdirSync(dirname(configPath), { recursive: true });
+    renameSync(staging, configPath);
+    JSON.parse(readFileSync(configPath, "utf8"));
+  } finally {
+    try {
+      rmSync(stagingDir, { recursive: true, force: true });
+    } catch {}
+  }
+  process.stdout.write(`Registered mcp.worktree-for-agents in ${configPath}.\n`);
+}
+
+const args = new Set(process.argv.slice(2));
+if (args.has("--write-opencode")) {
+  runWriteOpencode();
+} else if (args.has("--json")) {
+  const status = collectStatus();
+  process.stdout.write(JSON.stringify(status, null, 2) + "\n");
+} else {
+  printHuman(collectStatus());
+}

package/worktree.mjs

@@ -0,0 +1,47 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { probePython } from "./scripts/python.mjs";
+
+const packageDir = dirname(fileURLToPath(import.meta.url));
+const entry = join(packageDir, "worktree_manager", "__main__.py");
+
+if (!existsSync(entry)) {
+  process.stderr.write(
+    "worktree-for-agents is incomplete: missing worktree_manager/__main__.py. Reinstall the package.\n"
+  );
+  process.exit(126);
+}
+
+const probed = probePython();
+if (!probed.version) {
+  process.stderr.write(
+    "worktree-for-agents requires Python 3.9 or later. Install Python 3.9+ and rerun the installation.\n"
+  );
+  process.exit(127);
+}
+
+const env = {
+  ...process.env,
+  PYTHONPATH: packageDir + (process.env.PYTHONPATH ? `:${process.env.PYTHONPATH}` : ""),
+};
+const child = spawn(probed.bin, ["-m", "worktree_manager", ...process.argv.slice(2)], {
+  cwd: packageDir,
+  env,
+  stdio: "inherit",
+});
+const forward = (signal) => {
+  if (child.exitCode === null && child.signalCode === null) {
+    child.kill(signal);
+  }
+};
+process.on("SIGINT", () => forward("SIGINT"));
+process.on("SIGTERM", () => forward("SIGTERM"));
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code === null ? 1 : code);
+});

package/worktree.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+
+set -eu
+
+script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+if ! command -v python3 >/dev/null 2>&1; then
+    printf '%s\n' 'worktree manager requires Python 3 (python3) on PATH; install Python 3 and retry.' >&2
+    exit 127
+fi
+
+if [ ! -f "$script_dir/worktree_manager/__main__.py" ]; then
+    printf '%s\n' "worktree manager Python entry point is missing: $script_dir/worktree_manager/__main__.py" >&2
+    exit 126
+fi
+
+PYTHONPATH="$script_dir${PYTHONPATH+:$PYTHONPATH}"
+export PYTHONPATH
+exec python3 -m worktree_manager "$@"

package/worktree_manager/__init__.py

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

package/worktree_manager/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

package/worktree_manager/backup_store.py

@@ -0,0 +1,16 @@
+"""Retained Git refs; pending backups are never automatically pruned."""
+from __future__ import annotations
+from .git_repository import GitRepository
+from .models import ManagerError
+class BackupStore:
+    def __init__(self,repository: GitRepository,backup_ref_prefix: str):
+        self.repository,self.prefix=repository,backup_ref_prefix.strip('/')
+        if not self.prefix or '..' in self.prefix.split('/'): raise ManagerError('invalid_configuration','Unsafe backup ref prefix',3)
+    def ref(self,tx: str,suffix: str='')->str:
+        if not tx or '/' in tx: raise ManagerError('invalid_identity','Invalid transaction identifier',3)
+        return f'refs/{self.prefix}/{tx}{suffix}'
+    def retain(self,tx: str,oid: str,suffix: str='')->None: self.repository.run(('update-ref',self.ref(tx,suffix),oid))
+    def resolve(self,tx: str,suffix: str='')->str|None:
+        result=self.repository.run(('rev-parse','--verify','--quiet',self.ref(tx,suffix)),check=False)
+        return result.stdout.strip() if result.returncode==0 else None
+    def delete(self,tx: str,suffix: str='')->None: self.repository.run(('update-ref','-d',self.ref(tx,suffix)),check=False)

package/worktree_manager/cli.py

@@ -0,0 +1,137 @@
+"""Standalone Python command dispatcher."""
+from __future__ import annotations
+import argparse,sys,subprocess,json
+from pathlib import Path
+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 .recovery_manager import RecoveryManager
+from .target_direct_adapter import TargetDirectAdapter
+from . import __version__ as VERSION
+class _Parser(argparse.ArgumentParser):
+    def error(self, message):
+        raise ManagerError('usage_error',message,2)
+def _parser():
+    parser=_Parser(prog='python3 -m worktree_manager'); parser.add_argument('--json',action='store_true'); parser.add_argument('--version',action='version',version=VERSION); parser.add_argument('--repo'); parser.add_argument('--config'); sub=parser.add_subparsers(dest='command',required=True,parser_class=_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=='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='?')
+    sub.add_parser('list'); sub.add_parser('prune')
+    td=sub.add_parser('target-direct'); td.add_argument('action',choices=('create','link-parent','abort','complete','recover')); td.add_argument('work_id'); td.add_argument('--parent-repo',required=True); td.add_argument('--target',choices=('submodule',),default='submodule'); td.add_argument('--submodule-path'); td.add_argument('--base',default='main'); td.add_argument('--link-parent',choices=('staged-only',),default='staged-only'); td.add_argument('--descriptor')
+    return parser
+
+def _request_json_mode(raw_argv):
+    """Serve the canonical protocol envelope for `--request-json` invocations.
+
+    Success and failure publish the same nine-key envelope used by the MCP
+    transport, with or without `--json`, so a client never has to parse two
+    different document shapes.
+    """
+    from .mcp_operations import call
+    from .mcp_contract import TOOL_NAMES,absolute_repository,error_envelope
+    pos=raw_argv.index('--request-json')
+    request=None; tool=None
+    def fail(code,message,exit_code):
+        operation=tool
+        if not operation and isinstance(request,dict) and isinstance(request.get('operation'),str):
+            operation=request['operation']
+        operation=operation or 'request-json'
+        repository=absolute_repository(request.get('repo')) if isinstance(request,dict) else ''
+        document=error_envelope(operation,repository,code,message,exit_code)
+        sys.stdout.write(json.dumps(document,sort_keys=True,separators=(',',':'))+'\n')
+        return exit_code
+    extra=[arg for index,arg in enumerate(raw_argv) if index not in (pos,pos+1) and arg!='--json']
+    if pos+1>=len(raw_argv) or extra:
+        return fail('usage_error','--request-json must be used alone (optionally with --json)',2)
+    source=raw_argv[pos+1]
+    try:
+        text=sys.stdin.read() if source=='-' else Path(source).read_text(encoding='utf-8')
+        request=json.loads(text)
+        if not isinstance(request,dict) or not isinstance(request.get('operation'),str): raise ValueError('operation_required')
+        # The protocol request is passed unchanged to the same strict
+        # validator and lifecycle façade used by MCP.
+        raw=request['operation']
+        tool=raw if raw in TOOL_NAMES else ('worktree_'+raw if 'worktree_'+raw in TOOL_NAMES else None)
+        if tool is None: raise ValueError('unknown_tool')
+        payload=dict(request); payload.pop('operation')
+        result=call(tool,payload)
+        sys.stdout.write(json.dumps(result,sort_keys=True,separators=(',',':'))+'\n')
+        error=result.get('error')
+        return 0 if not error else error.get('exit_code',5)
+    except ManagerError as exc:
+        return fail(exc.code,str(exc),exc.exit_code)
+    except (ValueError,OSError) as exc:
+        return fail('invalid_request',str(exc),3)
+def main(argv=None)->int:
+    operation='usage'; json_mode='--json' in (argv if argv is not None else sys.argv[1:])
+    try:
+        raw_argv = list(argv if argv is not None else sys.argv[1:])
+        if '--request-json' in raw_argv:
+            return _request_json_mode(raw_argv)
+        if '--version' in raw_argv and any(arg not in {'--version', '--json'} for arg in raw_argv):
+            raise ManagerError('usage_error', "unrecognized arguments: extra arguments with --version", 2)
+        args=_parser().parse_args(argv); operation=args.command
+        if operation=='target-direct':
+            target=Path(args.repo).expanduser().resolve() if args.repo else Path.cwd().resolve()
+            if not args.descriptor:
+                common=Path(subprocess.run(['git','-C',str(target),'rev-parse','--git-common-dir'],check=True,text=True,stdout=subprocess.PIPE).stdout.strip())
+                if not common.is_absolute(): common=(target/common).resolve()
+                import hashlib
+                descriptor_id=args.work_id[3:] if args.action=='recover' and args.work_id.startswith('wt-') else args.work_id
+                args.descriptor=str(common/'worktree-manager'/'target-direct'/hashlib.sha256(descriptor_id.encode()).hexdigest()/'descriptor')
+            if args.action=='create':
+                if not args.submodule_path: raise ManagerError('invalid_identity','--submodule-path is required',2)
+                adapter=TargetDirectAdapter.create(args.descriptor,target,args.parent_repo,args.submodule_path,args.work_id,args.base)
+                data={'created':True,'worktree':adapter.values['worktree_path'],'branch':adapter.values['branch'],'descriptor':str(adapter.path)}
+            else:
+                adapter=TargetDirectAdapter(args.descriptor)
+                if adapter.values['target_repo']!=str(target) or adapter.values['parent_repo']!=str(Path(args.parent_repo).resolve()) or adapter.values['tx_id'] not in {args.work_id,'wt-'+args.work_id}:
+                    raise ManagerError('invalid_descriptor','Target descriptor identity does not match command arguments',3)
+                data={'link-parent':adapter.link_parent,'abort':adapter.abort,'complete':adapter.complete,'recover':adapter.recover}[args.action]()
+            result=OperationResult('target-direct',data=data); emit(result,args.json)
+            # The established target-direct command reports abort through its
+            # dedicated public status (6), including a successfully restored
+            # index; the result envelope remains success in that case.
+            return 6 if args.action=='abort' and result.exit_code==0 else result.exit_code
+        root=Path(args.repo).expanduser() if args.repo else Path.cwd()
+        if not root.is_absolute(): raise ManagerError('invalid_repository','Repository path must be absolute',3)
+        repository=GitRepository(root)
+        if operation=='recover':
+            config=Configuration.load(repository.root,args.config)
+            git_dir=Path(repository.run(('rev-parse','--git-dir')).stdout.strip())
+            if not git_dir.is_absolute(): git_dir=(repository.root/git_dir).resolve()
+            kind,data=RecoveryManager(git_dir/config.state_dir,repository.root).recover(args.transaction_id)
+            result=OperationResult(operation,kind,data or {})
+        else:
+            config=Configuration.load(repository.root,args.config); lifecycle=WorktreeLifecycle(config)
+            if operation=='list': result=OperationResult(operation,data={'worktrees':lifecycle.list()})
+            elif operation=='prune':
+                data=lifecycle.prune()
+                result=OperationResult(operation,ResultKind.NO_PENDING_WORK if data.get('pruned',0)==0 else ResultKind.SUCCESS,data=data)
+            elif operation=='create':
+                base=args.base or next((b for b in ('development','main','trunk') if repository.run(('show-ref','--verify','--quiet',f'refs/heads/{b}'),check=False).returncode==0),'main')
+                data=lifecycle.create(args.work_id,base,init_submodules=args.init_submodules,prepare=args.prepare,verify=args.verify)
+                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['merge']='success'
+                result=OperationResult(operation,data=data)
+        if operation=='list' and not args.json:
+            sys.stdout.write(repository.run(('worktree','list','--porcelain')).stdout)
+            return result.exit_code
+        emit(result,args.json); return result.exit_code
+    except ManagerError as exc:
+        if exc.code == 'resource_locked':
+            exc = ManagerError('operation_failed', exc.message, 5)
+        emit(OperationResult(operation,ResultKind.PENDING_INTERVENTION if exc.code=='intervention_required' else ResultKind.FAILURE,error=exc),getattr(locals().get('args',None),'json',json_mode)); return exc.exit_code
+
+def usage(argv=None)->int:
+    try: return main(argv)
+    except SystemExit as exc: return int(exc.code)

package/worktree_manager/commit_message.py

@@ -0,0 +1,63 @@
+"""Composition of worktree closure commit messages.
+
+This module owns the deterministic transformation from an optional title and
+body supplied by the caller into the subject and body written to the destination
+repository. The neutral (English) fallback used when no title is supplied is
+defined here so that a standalone closure never produces an empty commit message.
+"""
+from __future__ import annotations
+
+import re
+
+
+# Neutral fallback used by the standalone manager. The consuming project may
+# override the wording by supplying commit_title/commit_body.
+GENERIC_SUBJECT = "Complete {work_id} (generic closure)"
+GENERIC_BODY = "No delivery description was available at closure time."
+
+
+def _normalize_title(value):
+    if value is None:
+        return ""
+    text = str(value)
+    # Replace line breaks and null bytes with spaces, then collapse whitespace.
+    text = text.replace("\r", " ").replace("\n", " ").replace("\x00", " ")
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+def _normalize_body(value):
+    if value is None:
+        return ""
+    text = str(value)
+    # Normalize line endings and trim trailing whitespace per line.
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    lines = [line.rstrip(" \t") for line in text.split("\n")]
+    # Drop trailing blank lines.
+    while len(lines) > 1 and lines[-1] == "":
+        lines.pop()
+    return "\n".join(lines)
+
+
+def compose_commit_message(work_id, title=None, body=None):
+    """Return (subject, body) for the closure commit.
+
+    The subject always contains the work_id: when the supplied title does not
+    include it, it is appended as ' [work_id]'. An empty or whitespace-only
+    title is treated as absent and replaced by the neutral fallback subject.
+    """
+    normalized_title = _normalize_title(title)
+    normalized_body = _normalize_body(body)
+
+    if not normalized_title:
+        subject = GENERIC_SUBJECT.format(work_id=work_id)
+        # No title means no delivery description: use the neutral body.
+        final_body = GENERIC_BODY
+    elif work_id in normalized_title:
+        subject = normalized_title
+        final_body = normalized_body
+    else:
+        subject = f"{normalized_title} [{work_id}]"
+        final_body = normalized_body
+
+    return subject, final_body

package/worktree_manager/configuration.py

@@ -0,0 +1,61 @@
+"""Validated configuration matching the standalone key=value configuration."""
+from __future__ import annotations
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from .models import ManagerError
+
+@dataclass(frozen=True)
+class Configuration:
+    repo_root: Path
+    worktrees_dir: str = '.worktrees'
+    branch_prefix: str = 'worktree/'
+    state_dir: str = 'worktree-manager'
+    backup_dir: str = 'backups'
+    backup_ref_prefix: str = 'worktree-manager/backups'
+    lock_dir: str = 'locks'
+    prepare_command: str = ''
+    verify_command: str = ''
+    prepare_enabled: bool = False
+    verify_enabled: bool = False
+    preserve_dirty: bool = False
+
+    @classmethod
+    def load(cls, repo_root: str|Path, config_path: str|Path|None=None, environ: dict[str,str]|None=None)->'Configuration':
+        root=Path(repo_root).expanduser()
+        if not root.is_absolute() or not root.is_dir(): raise ManagerError('invalid_repository','Repository root must be an existing absolute directory',3)
+        path=Path(config_path).expanduser() if config_path is not None else root/'.worktree-manager.conf'
+        values={}
+        if config_path is not None and (not path.is_absolute() or not path.is_file()): raise ManagerError('invalid_configuration','Configuration must be an existing absolute file',3)
+        if path.is_file():
+            try: lines=path.read_text(encoding='utf-8').splitlines()
+            except OSError as exc: raise ManagerError('invalid_configuration','Cannot read configuration',3) from exc
+            for line in lines:
+                if not line or line.startswith('#'): continue
+                if '=' not in line: raise ManagerError('invalid_configuration','Configuration lines must use key=value',3)
+                key,value=line.split('=',1)
+                if key in values: raise ManagerError('invalid_configuration',f'Duplicate configuration key: {key}',3)
+                values[key]=value
+        allowed={'worktrees_dir','branch_prefix','state_dir','backup_dir','backup_ref_prefix','lock_dir','prepare_command','verify_command','prepare_enabled','verify_enabled','preserve_dirty'}
+        if set(values)-allowed: raise ManagerError('invalid_configuration','Configuration contains unknown keys',3)
+        env=os.environ if environ is None else environ
+        for key in allowed:
+            name='WORKTREE_MANAGER_'+key.upper()
+            if name in env: values[key]=env[name]
+        for key,value in values.items():
+            if '\x00' in value or '\n' in value or '\r' in value: raise ManagerError('invalid_configuration',f'Invalid value for {key}',3)
+        for key in ('state_dir','lock_dir'):
+            value=values.get(key,'')
+            if value and (Path(value).is_absolute() or '..' in Path(value).parts or value in ('.','')): raise ManagerError('invalid_configuration',f'Unsafe relative path for {key}',3)
+        for key in ('worktrees_dir','backup_dir'):
+            value=values.get(key,'')
+            if value and (value.startswith('-') or (key=='backup_dir' and (Path(value).is_absolute() or '..' in Path(value).parts))): raise ManagerError('invalid_configuration',f'Invalid path for {key}',3)
+        if values.get('backup_ref_prefix','').find('..')>=0: raise ManagerError('invalid_configuration','Invalid backup ref prefix',3)
+        bools={'prepare_enabled','verify_enabled','preserve_dirty'}
+        for key in bools:
+            if key in values:
+                if values[key] not in ('true','false'): raise ManagerError('invalid_configuration',f'{key} must be true or false',3)
+                values[key]=values[key]=='true'
+        if values.get('prepare_enabled') and not values.get('prepare_command'): raise ManagerError('invalid_configuration','prepare_enabled requires prepare_command',3)
+        if values.get('verify_enabled') and not values.get('verify_command'): raise ManagerError('invalid_configuration','verify_enabled requires verify_command',3)
+        return cls(repo_root=root.resolve(),**values)