constraintloop 0.5.0__tar.gz → 0.5.1__tar.gz

{constraintloop-0.5.0 → constraintloop-0.5.1}/CHANGELOG.md

@@ -5,6 +5,17 @@ Versioning, with the usual initial-development flexibility for `0.y.z`.
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-09-08
+
+- Isolate local evidence, sessions, waivers, acknowledgments, journals, and leases
+  by resolved project/worktree and branch (commit for detached HEAD). Bind input
+  digests to checkout identity and HEAD, keeping branch retry budgets across commits.
+- Reject checkout changes during gate evaluation and supervision. Report project,
+  worktree, branch, HEAD, and state directory in `doctor` and `explain`.
+- Migration: Git projects start fresh state under `.constraintloop/state/checkouts/`;
+  prior unscoped state is retained but never imported into a branch. All prior input
+  digests become stale. Run checks again and start a fresh challenge cycle if used.
+
 ## [0.5.0] - 2026-09-06
 
 - Add optional session challenge gates for Claude Code, Codex, and Gemini CLI:

{constraintloop-0.5.0 → constraintloop-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: constraintloop
-Version: 0.5.0
+Version: 0.5.1
 Summary: Evidence-based completion gates for AI coding agents
 Project-URL: Homepage, https://github.com/mauhpr/constraintloop
 Project-URL: Documentation, https://github.com/mauhpr/constraintloop/tree/main/docs
@@ -314,10 +314,13 @@ Commands run from their configured project-contained `cwd`, with the selected
 project root prepended to `PYTHONPATH`.
 
 Evidence is keyed by the constraint definition and the bytes of every file
-matched by `watch`. A source change therefore makes old evidence and waivers
-stale without a mutable invalidation list. Local state lives under the
+matched by `watch`, plus the resolved project/worktree, branch, and HEAD. A source
+change or new HEAD therefore makes old evidence and waivers stale without a
+mutable invalidation list. Local state lives under the
 gitignored `.constraintloop/state` directory; set `CONSTRAINTLOOP_CACHE_DIR` to
-override it.
+override it. Git projects use a separate state subdirectory per branch in each
+worktree. Use one worktree per concurrent line of work; `doctor` and `explain`
+show the active scope. See [worktrees and concurrent sessions](docs/worktrees.md).
 
 For stronger machine-local gates, create a gitignored
 `constraintloop.local.yml`. ConstraintLoop recursively merges mappings over the

{constraintloop-0.5.0 → constraintloop-0.5.1}/README.md

@@ -271,10 +271,13 @@ Commands run from their configured project-contained `cwd`, with the selected
 project root prepended to `PYTHONPATH`.
 
 Evidence is keyed by the constraint definition and the bytes of every file
-matched by `watch`. A source change therefore makes old evidence and waivers
-stale without a mutable invalidation list. Local state lives under the
+matched by `watch`, plus the resolved project/worktree, branch, and HEAD. A source
+change or new HEAD therefore makes old evidence and waivers stale without a
+mutable invalidation list. Local state lives under the
 gitignored `.constraintloop/state` directory; set `CONSTRAINTLOOP_CACHE_DIR` to
-override it.
+override it. Git projects use a separate state subdirectory per branch in each
+worktree. Use one worktree per concurrent line of work; `doctor` and `explain`
+show the active scope. See [worktrees and concurrent sessions](docs/worktrees.md).
 
 For stronger machine-local gates, create a gitignored
 `constraintloop.local.yml`. ConstraintLoop recursively merges mappings over the

{constraintloop-0.5.0 → constraintloop-0.5.1}/docs/convergence-loops.md

@@ -144,7 +144,8 @@ single-shot, tool-disabled reviews and cannot perform a repair transition.
 
 The supervisor:
 
-- use a single-writer lease under `.constraintloop/state/loops/`;
+- use a single-writer lease in the active state directory's `loops/` subdirectory
+  (`doctor` reports the directory; Git checkouts separate state by worktree and branch);
 - recover leases after a bounded TTL;
 - handle cancellation signals;
 - never count polling observations as repair attempts;
@@ -153,6 +154,9 @@ The supervisor:
 - redact secrets and cap retained output;
 - stop at every attempt and duration budget.
 
+Supervision stops if the Git checkout changes while it is running. Start a new
+supervisor in the intended worktree so it reloads that checkout's contract.
+
 ## Native integration
 
 `constraintloop loop-prompt NAME --adapter claude|codex|gemini` prints a durable

{constraintloop-0.5.0 → constraintloop-0.5.1}/docs/faq.md

@@ -79,10 +79,23 @@ call.
 
 ### Why does a result say `cached`?
 
-The contract definition and every matched `watch` input have the same digest as
-the prior evidence. Use `--no-cache` for a deliberate local rerun. CI always
+The contract definition, checkout identity (project, worktree, branch, HEAD), and
+every matched `watch` input have the same digest as the prior evidence.
+Use `--no-cache` for a deliberate local rerun. CI always
 reruns without local evidence.
 
+### Can concurrent sessions use separate worktrees?
+
+Yes, including detached worktrees and nested monorepo projects. Each worktree
+and branch has its own evidence, goals, waivers, acknowledgments, loop journals,
+and budgets. A shared `CONSTRAINTLOOP_CACHE_DIR` still separates resolved project
+paths. `constraintloop doctor` and `constraintloop explain --json` report the
+active worktree, branch, HEAD, and state directory.
+
+Use a dedicated worktree for each concurrent line of work. Multiple sessions
+in one directory still share its checked-out files and external services.
+See [worktree setup and container isolation](worktrees.md).
+
 ### Why did an unrelated edit invalidate a result?
 
 The constraint probably has a broad `watch`, such as `"**/*"`. Narrow it to the

{constraintloop-0.5.0 → constraintloop-0.5.1}/docs/release-readiness.md

@@ -1,6 +1,6 @@
 # Release readiness
 
-This is the current release checklist, updated September 6, 2026 for v0.5.0.
+This is the current release checklist, updated September 8, 2026 for v0.5.1.
 The authoritative publication procedure is [RELEASE.md](../RELEASE.md).
 Historical v0.1 milestones are complete; they are not current release gates.
 
@@ -22,6 +22,16 @@ Historical v0.1 milestones are complete; they are not current release gates.
 - Verify publication and a fresh public-index install afterward. Never replace
   an existing version, publish locally, or add long-lived registry tokens.
 
+## v0.5.1 worktree isolation
+
+Worktree regressions cover linked and detached checkouts, shared cache directories,
+branch switches at the same commit, HEAD changes with unchanged watched files,
+session goals and retry budgets, local exceptions, loop journals and leases,
+checkout changes during evaluation and supervision, nested-project hooks,
+legacy-state isolation, and challenge-only loops. See [worktrees](worktrees.md)
+for setup and migration instructions. Container resource isolation remains the
+consuming project's responsibility.
+
 ## v0.5 review closure
 
 The [pre-release review](pre-release-review-2026-09-06.md) records ten reproduced

constraintloop-0.5.1/docs/worktrees.md

@@ -0,0 +1,73 @@
+# Worktrees and concurrent sessions
+
+Use one Git worktree per concurrent line of work. Each directory has its own
+checkout of the contract, source files, and local ConstraintLoop state. Linked
+and detached worktrees are supported, including contracts below the Git root.
+
+## What is isolated
+
+For Git projects, state lives under
+`.constraintloop/state/checkouts/<scope>/` in the selected project. The scope
+includes the resolved project path, worktree Git directory, and full branch
+reference. Detached checkouts use the HEAD commit instead of a branch.
+
+Evidence, session goals and retries, waivers, advisory acknowledgments, loop
+journals, challenge work, and supervisor leases all use this directory. Setting
+`CONSTRAINTLOOP_CACHE_DIR` relocates storage while preserving project and checkout
+separation. Symlink aliases of the same project resolve to the same scope.
+Projects outside Git continue using `.constraintloop/state/` directly.
+
+Evidence digests also include HEAD, the contract, and watched file bytes. An
+empty commit therefore makes earlier evidence stale even when watched files
+are identical. Retry budgets persist across commits on the same branch. Switching
+branches selects that branch's state; switching back resumes its budgets and
+reuses evidence only if its inputs still match. A checkout change detected during
+evaluation or supervision prevents completion and requires another run.
+
+This does not make concurrent branch switching in one directory safe. Sessions
+there still share files and commands; use separate worktrees for independent tasks.
+
+## Set up a line of work
+
+Create a worktree from the desired starting branch or commit:
+
+```bash
+git worktree add -b task/worktree-fix ../project-worktree-fix HEAD
+```
+
+Bootstrap dependencies and local environment files in the new directory using
+the project's normal setup process. Git does not copy ignored virtual environments,
+secrets, or local hook settings. Then install hooks with the ConstraintLoop
+executable intended for that worktree:
+
+```bash
+constraintloop setup --adapter all --project ../project-worktree-fix
+constraintloop doctor --deep --project ../project-worktree-fix
+constraintloop explain --json --project ../project-worktree-fix
+```
+
+If the contract is in a subproject, pass that directory, for example
+`--project ../project-worktree-fix/packages/atool`, to each command. Generated hooks
+retain this subproject path relative to the active worktree root. Start the coding
+session in that worktree. Inspect `state_directory` in `explain --json` to verify
+that sessions intended to be independent have different scopes.
+
+## Containers and integration tests
+
+Git worktrees isolate files; they do not isolate the Docker daemon, host ports,
+databases, or test cleanup. ConstraintLoop does not allocate these resources.
+
+Configure the consuming project's container setup with distinct Compose project
+names, host ports, and named resources where required. TestContainers suites need
+their own resource and cleanup isolation; a Compose project name alone does not
+provide it. Until the project's integration runner supports concurrent execution,
+serialize those test runs across worktrees. `doctor --deep` checks declared local
+prerequisites and Docker availability, but cannot certify arbitrary test code's
+container isolation.
+
+## Existing state after upgrading
+
+Earlier unscoped Git state remains on disk but is not imported into any checkout
+scope, because its originating branch is unknown. Run the gates again. Start a
+fresh challenge cycle if the contract uses challenges. `doctor` shows the active
+state directory; no manual cache deletion or contract weakening is needed.

{constraintloop-0.5.0 → constraintloop-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "constraintloop"
-version = "0.5.0"
+version = "0.5.1"
 description = "Evidence-based completion gates for AI coding agents"
 readme = "README.md"
 license = "MIT"

{constraintloop-0.5.0 → constraintloop-0.5.1}/src/constraintloop/__init__.py

@@ -4,4 +4,4 @@ The v0.5 supported interfaces are the CLI and documented versioned protocols.
 Python submodules are internal and may change during initial development.
 """
 
-__version__ = "0.5.0"
+__version__ = "0.5.1"

constraintloop-0.5.1/src/constraintloop/checkout.py

@@ -0,0 +1,88 @@
+"""Git checkout identity without following a shared repository's main worktree."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Checkout:
+    project_root: str
+    worktree_root: str | None = None
+    git_dir: str | None = None
+    branch: str | None = None
+    head: str | None = None
+
+    def snapshot(self) -> str:
+        return json.dumps(asdict(self), sort_keys=True, separators=(",", ":"))
+
+    def state_key(self) -> str | None:
+        """Keep budgets across commits on a branch, separate detached checkouts."""
+        if self.git_dir is None:
+            return None
+        identity = (self.project_root, self.git_dir, self.branch or self.head)
+        return hashlib.sha256(json.dumps(identity).encode()).hexdigest()[:20]
+
+
+def ensure_checkout_unchanged(project_root: Path, expected: Checkout) -> None:
+    if checkout_context(project_root) != expected:
+        raise ValueError(
+            "Git checkout changed during evaluation; evidence cannot authorize completion. "
+            "Run gates again in a dedicated worktree for this task."
+        )
+
+
+def checkout_context(project_root: Path) -> Checkout:
+    root = project_root.expanduser().resolve()
+    # A .git file marks linked worktrees and submodules just as a directory marks
+    # a regular checkout. Projects outside Git keep their existing local scope.
+    if not any((candidate / ".git").exists() for candidate in (root, *root.parents)):
+        return Checkout(project_root=str(root))
+
+    # Git hooks can export the originating checkout's repository paths. The
+    # explicit project directory must remain authoritative for our inspection.
+    environment = {
+        key: value
+        for key, value in os.environ.items()
+        if key
+        not in {
+            "GIT_DIR",
+            "GIT_WORK_TREE",
+            "GIT_COMMON_DIR",
+            "GIT_INDEX_FILE",
+            "GIT_OBJECT_DIRECTORY",
+            "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+            "GIT_NAMESPACE",
+        }
+    }
+
+    def git(*args: str, optional: bool = False) -> str | None:
+        try:
+            result = subprocess.run(
+                ["git", *args],
+                cwd=root,
+                env=environment,
+                capture_output=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=5,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            raise ValueError(f"Could not inspect Git checkout in {root}") from exc
+        if result.returncode != 0:
+            if optional and result.returncode == 1:
+                return None
+            raise ValueError(f"Could not inspect Git checkout in {root}")
+        return result.stdout.strip()
+
+    worktree = git("rev-parse", "--show-toplevel")
+    git_dir = git("rev-parse", "--absolute-git-dir")
+    branch = git("symbolic-ref", "--quiet", "HEAD", optional=True)
+    head = git("rev-parse", "--verify", "--quiet", "HEAD", optional=True)
+    return Checkout(str(root), worktree, git_dir, branch, head)

{constraintloop-0.5.0 → constraintloop-0.5.1}/src/constraintloop/cli.py

@@ -13,6 +13,7 @@ from typing import Any, cast
 import click
 
 from constraintloop import __version__
+from constraintloop.checkout import checkout_context
 from constraintloop.config import (
     ContractError,
     contract_digest,
@@ -58,6 +59,7 @@ from constraintloop.setup_hooks import (
     uninstall_pre_push_hook,
 )
 from constraintloop.state import (
+    cache_root,
     create_advisory_acknowledgment,
     create_waiver,
     load_cached_result,
@@ -164,13 +166,16 @@ def _run_phase(project: Path, phase: Phase, json_output: bool, no_cache: bool) -
         contract, _ = load_contract(root, include_local=phase != Phase.CI)
     except ContractError as exc:
         raise click.ClickException(str(exc)) from exc
-    record = ConstraintEngine(
-        root,
-        contract,
-        use_cache=not no_cache and phase != Phase.CI,
-        allow_waivers=phase.allows_local_waivers,
-        progress=None if json_output else lambda message: click.echo(message, err=True),
-    ).run(phase)
+    try:
+        record = ConstraintEngine(
+            root,
+            contract,
+            use_cache=not no_cache and phase != Phase.CI,
+            allow_waivers=phase.allows_local_waivers,
+            progress=None if json_output else lambda message: click.echo(message, err=True),
+        ).run(phase)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
     click.echo(
         record.model_dump_json(indent=2)
         if json_output
@@ -208,7 +213,7 @@ def cycle_command(loop_name: str, project: Path, json_output: bool) -> None:
     try:
         contract, _ = load_loop_contract(root, loop_name)
         result = run_cycle(root, contract, loop_name)
-    except (ContractError, LoopError) as exc:
+    except (ValueError, LoopError) as exc:
         if json_output:
             click.echo(
                 json.dumps(
@@ -243,7 +248,7 @@ def supervise_command(loop_name: str, project: Path) -> None:
         for result in supervise(root, contract, loop_name):
             final = result
             click.echo(result.model_dump_json())
-    except (ContractError, LoopError) as exc:
+    except (ValueError, LoopError) as exc:
         click.echo(
             json.dumps(
                 {
@@ -408,10 +413,18 @@ def explain_command(phase: str, project: Path, json_output: bool) -> None:
         )
     if json_output:
         click.echo(
-            json.dumps({"phase": selected_phase.value, "constraints": explanations}, indent=2)
+            json.dumps(
+                {
+                    "phase": selected_phase.value,
+                    "scope": _checkout_scope(root),
+                    "constraints": explanations,
+                },
+                indent=2,
+            )
         )
         return
     click.echo(f"ConstraintLoop explain: phase={selected_phase.value}")
+    _print_checkout_scope(root)
     for item in explanations:
         click.echo(
             f"- {str(item['decision']).upper()} {item['constraint_id']} ({item['kind']}): "
@@ -439,6 +452,28 @@ def _dependency_chains(contract: Any, constraint_id: str) -> list[str]:
     return [" -> ".join(chain) for chain in paths(constraint_id) if len(chain) > 1]
 
 
+def _checkout_scope(root: Path) -> dict[str, str | None]:
+    checkout = checkout_context(root)
+    return {
+        "project_root": checkout.project_root,
+        "worktree_root": checkout.worktree_root,
+        "git_dir": checkout.git_dir,
+        "branch": checkout.branch,
+        "head": checkout.head,
+        "state_directory": str(cache_root(root)),
+    }
+
+
+def _print_checkout_scope(root: Path) -> None:
+    scope = _checkout_scope(root)
+    click.echo(f"project: {scope['project_root']}")
+    click.echo(f"worktree: {scope['worktree_root'] or 'not a Git checkout'}")
+    if scope["git_dir"] is not None:
+        click.echo(f"branch: {scope['branch'] or '(detached HEAD)'}")
+        click.echo(f"HEAD: {scope['head'] or '(unborn)'}")
+    click.echo(f"state directory: {scope['state_directory']}")
+
+
 @main.group("baseline")
 def baseline_group() -> None:
     """Manage committed ratchet baselines."""
@@ -527,6 +562,7 @@ def doctor_command(project: Path, deep: bool) -> None:
         raise click.ClickException(str(exc)) from exc
     click.echo(f"OK {path}")
     click.echo(f"contract digest: {contract_digest(contract)}")
+    _print_checkout_scope(root)
     click.echo(f"constraints: {len(contract.constraints)}; evaluators: {len(contract.evaluators)}")
     try:
         project_environment = load_project_environment(root)

{constraintloop-0.5.0 → constraintloop-0.5.1}/src/constraintloop/digest.py

@@ -8,6 +8,7 @@ import subprocess
 from collections.abc import Iterable
 from pathlib import Path, PurePosixPath
 
+from constraintloop.checkout import Checkout, checkout_context
 from constraintloop.models import ConstraintSpec, RatchetConstraint
 from constraintloop.redaction import redact_text as redact_text
 
@@ -58,8 +59,9 @@ def constraint_input_digest(
     spec: ConstraintSpec,
     *,
     contract_digest: str | None = None,
+    checkout: Checkout | None = None,
 ) -> str:
-    digest = hashlib.sha256(b"constraintloop-input-v2\0")
+    digest = hashlib.sha256(b"constraintloop-input-v3\0")
 
     def add(value: bytes) -> None:
         digest.update(len(value).to_bytes(8, "big"))
@@ -67,6 +69,7 @@ def constraint_input_digest(
 
     add(constraint_id.encode())
     add((contract_digest or "").encode())
+    add((checkout or checkout_context(project_root)).snapshot().encode())
     add(json.dumps(spec.model_dump(mode="json"), sort_keys=True, separators=(",", ":")).encode())
     if isinstance(spec, RatchetConstraint):
         baseline_path = (project_root / spec.baseline_file).resolve()

{constraintloop-0.5.0 → constraintloop-0.5.1}/src/constraintloop/engine.py

@@ -14,6 +14,7 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import Any, cast
 
+from constraintloop.checkout import checkout_context, ensure_checkout_unchanged
 from constraintloop.config import contract_digest
 from constraintloop.digest import (
     changed_files,
@@ -79,6 +80,7 @@ class ConstraintEngine:
     def run(self, phase: Phase) -> EvidenceRecord:
         """Run applicable constraints in dependency order."""
         started_at = time.time()
+        self.checkout = checkout_context(self.project_root)
         results: dict[str, ConstraintResult] = {}
         pending = {
             constraint_id
@@ -130,6 +132,7 @@ class ConstraintEngine:
                     constraint_id,
                     spec,
                     contract_digest=self.contract_digest,
+                    checkout=self.checkout,
                 )
                 if pending_dependencies:
                     result = ConstraintResult(
@@ -203,6 +206,7 @@ class ConstraintEngine:
                     )
             pending.difference_update(ready)
 
+        ensure_checkout_unchanged(self.project_root, self.checkout)
         record = EvidenceRecord(
             run_id=str(uuid.uuid4()),
             project_root=str(self.project_root),
@@ -296,6 +300,7 @@ class ConstraintEngine:
         )
 
         result = ConstraintResult.model_validate(result.model_dump())
+        ensure_checkout_unchanged(self.project_root, self.checkout)
         if self.use_cache and phase != Phase.CI:
             save_cached_result(self.project_root, result, cache_digest=cache_digest)
         return result

{constraintloop-0.5.0 → constraintloop-0.5.1}/src/constraintloop/loops.py

@@ -21,6 +21,7 @@ from constraintloop.challenges import (
     challenge_input_digest,
     challenge_request,
 )
+from constraintloop.checkout import checkout_context, ensure_checkout_unchanged
 from constraintloop.config import contract_digest
 from constraintloop.digest import constraint_input_digest
 from constraintloop.engine import ConstraintEngine, blocking_causes
@@ -97,6 +98,7 @@ def _input_snapshot(
     project_root: Path, contract: Contract, config: LoopConfig, goal: str | None = None
 ) -> str:
     identity = contract_digest(contract)
+    checkout = checkout_context(project_root)
     inputs = [
         (
             constraint_id,
@@ -105,12 +107,14 @@ def _input_snapshot(
                 constraint_id,
                 spec,
                 contract_digest=identity,
+                checkout=checkout,
             ),
         )
         for constraint_id, spec in contract.constraints.items()
         if spec.enabled and config.phase in spec.phases
     ]
     inputs.append(("goal", goal or ""))
+    inputs.append(("checkout", checkout.snapshot()))
     if config.challenge is not None:
         inputs.extend(
             [
@@ -139,6 +143,7 @@ def run_cycle(
     config = contract.loops[loop_name]
     current_time = time.time() if now is None else now
     identity = contract_digest(contract)
+    checkout = checkout_context(project_root)
     path = journal_path(project_root, loop_name)
     with _write_lock(path):
         try:
@@ -193,6 +198,7 @@ def run_cycle(
             )
             journal.observation = result.observation
             journal.last_result = result.model_dump(mode="json")
+            ensure_checkout_unchanged(project_root, checkout)
             journal.input_snapshot = input_snapshot
             _write_json(path, journal.model_dump(mode="json"))
             if on_record is not None and journal.last_evidence is not None:
@@ -210,6 +216,7 @@ def run_cycle(
                 refresh_pending=True,
             ).run(config.phase)
 
+        ensure_checkout_unchanged(project_root, checkout)
         if on_record is not None:
             on_record(record)
 
@@ -329,6 +336,7 @@ def run_cycle(
         journal.input_snapshot = input_snapshot
         journal.last_result = result.model_dump(mode="json")
         journal.last_evidence = record
+        ensure_checkout_unchanged(project_root, checkout)
         _write_json(path, journal.model_dump(mode="json"))
         return result
 
@@ -475,6 +483,7 @@ def supervise(
         raise LoopError(f"Unknown loop {loop_name!r}")
     config = contract.loops[loop_name]
     ttl = max(60.0, config.interval_seconds * 3)
+    checkout = checkout_context(project_root)
     cancelled = False
 
     def cancel(_signum: int, _frame: Any) -> None:
@@ -488,6 +497,7 @@ def supervise(
         with loop_lease(project_root, loop_name, ttl_seconds=ttl) as renew:
             previous_state: LoopState | None = None
             while not cancelled:
+                ensure_checkout_unchanged(project_root, checkout)
                 renew()
                 result = run_cycle(project_root, contract, loop_name)
                 renew()

{constraintloop-0.5.0 → constraintloop-0.5.1}/src/constraintloop/state.py

@@ -14,6 +14,7 @@ from pathlib import Path
 from typing import Any
 
 from constraintloop._numbers import finite_number
+from constraintloop.checkout import checkout_context
 from constraintloop.digest import project_key
 from constraintloop.models import ConstraintResult
 
@@ -21,8 +22,11 @@ from constraintloop.models import ConstraintResult
 def cache_root(project_root: Path) -> Path:
     override = os.environ.get("CONSTRAINTLOOP_CACHE_DIR")
     if override:
-        return Path(override).expanduser() / project_key(project_root)
-    return project_root.resolve() / ".constraintloop" / "state"
+        base = Path(override).expanduser().resolve() / project_key(project_root)
+    else:
+        base = project_root.resolve() / ".constraintloop" / "state"
+    key = checkout_context(project_root).state_key()
+    return base / "checkouts" / key if key is not None else base
 
 
 def _project_dir(project_root: Path) -> Path:

{constraintloop-0.5.0 → constraintloop-0.5.1}/tests/test_review_regressions.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 import sys
+import threading
 import time
 
 import pytest
@@ -18,7 +19,13 @@ from constraintloop.hooks import handle_hook
 from constraintloop.loops import LoopError, journal_path, lease_path, loop_lease, run_cycle
 from constraintloop.models import Contract, LoopState, MetricThreshold, Phase, Verdict
 from constraintloop.redaction import redact_value
-from constraintloop.state import create_waiver, load_ratchet_baseline, save_ratchet_baseline
+from constraintloop.state import (
+    _write_json,
+    _write_lock,
+    create_waiver,
+    load_ratchet_baseline,
+    save_ratchet_baseline,
+)
 
 
 @pytest.fixture(autouse=True)
@@ -430,7 +437,19 @@ def test_supervisor_lease_renews_without_another_cycle(tmp_path):
 
 
 @pytest.mark.parametrize("renew_after_loss", [False, True])
-def test_lost_supervisor_heartbeat_fails_closed_and_preserves_new_owner(tmp_path, renew_after_loss):
+def test_lost_supervisor_heartbeat_fails_closed_and_preserves_new_owner(
+    tmp_path, renew_after_loss, monkeypatch
+):
+    heartbeat_exited = threading.Event()
+
+    class ObservedHeartbeat(threading.Thread):
+        def run(self):
+            try:
+                super().run()
+            finally:
+                heartbeat_exited.set()
+
+    monkeypatch.setattr("constraintloop.loops.threading.Thread", ObservedHeartbeat)
     with (
         pytest.raises(LoopError, match="renewal failed"),
         loop_lease(
@@ -440,8 +459,9 @@ def test_lost_supervisor_heartbeat_fails_closed_and_preserves_new_owner(tmp_path
         ) as renew,
     ):
         path = lease_path(tmp_path, "review")
-        path.write_text(json.dumps({"token": "new-owner", "expires_at": time.time() + 10}))
-        time.sleep(0.15)
+        with _write_lock(path):
+            _write_json(path, {"token": "new-owner", "expires_at": time.time() + 10})
+        assert heartbeat_exited.wait(timeout=5), "heartbeat did not observe the lost lease"
         if renew_after_loss:
             renew()
     assert json.loads(path.read_text())["token"] == "new-owner"

constraintloop-0.5.1/tests/test_worktrees.py

@@ -0,0 +1,346 @@
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+import yaml
+from click.testing import CliRunner
+
+from constraintloop.checkout import checkout_context
+from constraintloop.cli import main
+from constraintloop.config import contract_digest
+from constraintloop.digest import constraint_input_digest
+from constraintloop.engine import ConstraintEngine
+from constraintloop.hooks import handle_hook
+from constraintloop.loops import journal_path, loop_lease, run_cycle, show_challenge, supervise
+from constraintloop.models import ChallengeConfig, Contract, LoopState, Phase, Verdict
+from constraintloop.setup_hooks import install_hooks
+from constraintloop.state import (
+    advisory_acknowledgment_reason,
+    cache_root,
+    create_advisory_acknowledgment,
+    create_waiver,
+    load_latest_result,
+    load_session,
+    save_session,
+)
+
+
+def git(root: Path, *args: str) -> str:
+    return subprocess.run(
+        ["git", *args], cwd=root, check=True, capture_output=True, text=True
+    ).stdout.strip()
+
+
+@pytest.fixture
+def repository(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    monkeypatch.delenv("CONSTRAINTLOOP_CACHE_DIR", raising=False)
+    root = tmp_path / "repo"
+    root.mkdir()
+    git(root, "init", "-q", "-b", "main")
+    git(root, "config", "user.name", "Test")
+    git(root, "config", "user.email", "test@example.invalid")
+    git(root, "config", "commit.gpgsign", "false")
+    git(root, "config", "core.hooksPath", str(tmp_path / "no-hooks"))
+    (root / "source").write_text("same\n")
+    git(root, "add", "source")
+    git(root, "commit", "-qm", "initial")
+    return root
+
+
+def contract(*, failure: bool = False) -> Contract:
+    return Contract.model_validate(
+        {
+            "settings": {"max_auto_retries": 1},
+            "constraints": {
+                "check": {
+                    "kind": "command",
+                    "command": [sys.executable, "-c", f"raise SystemExit({int(failure)})"],
+                    "watch": ["source"],
+                    "phases": ["stop", "ci"],
+                }
+            },
+            "loops": {
+                "completion": {
+                    "phase": "stop",
+                    "interval_seconds": 10,
+                    "max_repair_attempts": 3,
+                    "max_unchanged_repairs": 2,
+                    "max_duration_seconds": 100,
+                }
+            },
+        }
+    )
+
+
+@pytest.mark.parametrize("shared_cache", [False, True])
+@pytest.mark.parametrize("detached", [False, True])
+def test_worktrees_isolate_all_state(
+    repository: Path, monkeypatch: pytest.MonkeyPatch, shared_cache: bool, detached: bool
+) -> None:
+    if shared_cache:
+        monkeypatch.setenv("CONSTRAINTLOOP_CACHE_DIR", str(repository.parent / "cache"))
+    linked = repository.parent / "linked"
+    options = ["--detach"] if detached else ["-b", "feature"]
+    git(repository, "worktree", "add", *options, str(linked), "HEAD")
+    policy = contract(failure=True)
+    first = ConstraintEngine(repository, policy).run(Phase.STOP).results[0]
+    save_session(repository, "same-session", {"goal": "main task", "attempts": 4})
+    create_waiver(repository, first, contract_digest(policy), "local exception")
+    create_advisory_acknowledgment(repository, first, "main disposition")
+    run_cycle(repository, policy, "completion")
+
+    assert cache_root(repository) != cache_root(linked)
+    assert load_latest_result(linked, "check") is None
+    assert load_session(linked, "same-session") == {}
+    assert advisory_acknowledgment_reason(linked, first) is None
+    assert not journal_path(linked, "completion").exists()
+    with (
+        loop_lease(repository, "completion", ttl_seconds=60),
+        loop_lease(linked, "completion", ttl_seconds=60),
+    ):
+        other = ConstraintEngine(linked, policy).run(Phase.STOP).results[0]
+    assert other.verdict == Verdict.FAIL
+    assert not other.cached
+    assert other.input_digest != first.input_digest
+    assert ConstraintEngine(repository, policy).run(Phase.STOP).results[0].verdict == Verdict.WAIVED
+    assert ConstraintEngine(linked, policy).run(Phase.STOP).results[0].cached
+
+
+def test_branch_switch_isolates_evidence_goals_and_budgets(repository: Path) -> None:
+    policy = contract(failure=True)
+    # Exercise ordinary Stop retries separately from the loop's repair budget.
+    hook_policy = policy.model_dump(mode="json", exclude={"loops"})
+    (repository / "constraintloop.yml").write_text(yaml.safe_dump(hook_policy))
+    payload = {"session_id": "session"}
+    handle_hook(repository, "claude", "user-prompt", {**payload, "prompt": "main task"})
+    assert handle_hook(repository, "claude", "stop", payload)["decision"] == "block"
+    assert handle_hook(repository, "claude", "stop", payload)["continue"] is False
+    first = run_cycle(repository, policy, "completion", now=100)
+    second = run_cycle(repository, policy, "completion", now=101)
+    assert second.repair_attempt > first.repair_attempt
+    original_state = cache_root(repository)
+    original_head = checkout_context(repository).head
+
+    git(repository, "checkout", "-qb", "other")
+    assert checkout_context(repository).head == original_head
+    assert cache_root(repository) != original_state
+    assert load_latest_result(repository, "check") is None
+    assert load_session(repository, "session") == {}
+    assert handle_hook(repository, "claude", "stop", payload)["decision"] == "block"
+    other = run_cycle(repository, policy, "completion", now=102)
+    assert other.observation == 1
+    assert other.repair_attempt == 0
+
+    git(repository, "checkout", "-q", "main")
+    assert cache_root(repository) == original_state
+    assert load_session(repository, "session")["goal"] == "main task"
+    assert handle_hook(repository, "claude", "stop", payload)["continue"] is False
+    assert run_cycle(repository, policy, "completion", now=103).repair_attempt > 0
+
+
+@pytest.mark.parametrize("failure", [False, True])
+def test_commit_invalidates_evidence_without_resetting_budgets(
+    repository: Path, failure: bool
+) -> None:
+    policy = contract(failure=failure)
+    first = ConstraintEngine(repository, policy).run(Phase.STOP).results[0]
+    if failure:
+        create_waiver(repository, first, contract_digest(policy), "old HEAD only")
+    save_session(repository, "session", {"attempts": 2})
+    original_state = cache_root(repository)
+    git(repository, "commit", "--allow-empty", "-qm", "new HEAD, same watched bytes")
+
+    assert cache_root(repository) == original_state
+    assert load_session(repository, "session")["attempts"] == 2
+    # Write the same policy for the CLI's freshness diagnostics.
+    (repository / "constraintloop.yml").write_text(yaml.safe_dump(policy.model_dump(mode="json")))
+    status = CliRunner().invoke(main, ["status", "--project", str(repository)])
+    assert status.exit_code == 0, status.output
+    assert "STALE check" in status.output
+    second = ConstraintEngine(repository, policy).run(Phase.STOP).results[0]
+    assert not second.cached
+    assert second.input_digest != first.input_digest
+    assert second.verdict == first.verdict
+    assert ConstraintEngine(repository, policy).run(Phase.STOP).results[0].cached
+
+
+def test_detached_and_unborn_checkout_identity(repository: Path) -> None:
+    policy = contract()
+    branch = checkout_context(repository)
+    initial = constraint_input_digest(repository, "check", policy.constraints["check"])
+    git(repository, "checkout", "--detach", "-q")
+    detached = checkout_context(repository)
+    assert detached.branch is None
+    assert detached.head == branch.head
+    assert detached.state_key() != branch.state_key()
+    assert constraint_input_digest(repository, "check", policy.constraints["check"]) != initial
+    git(repository, "commit", "--allow-empty", "-qm", "detached commit")
+    assert checkout_context(repository).state_key() != detached.state_key()
+
+    unborn = repository.parent / "unborn"
+    unborn.mkdir()
+    git(unborn, "init", "-q", "-b", "main")
+    context = checkout_context(unborn)
+    assert context.head is None
+    assert context.branch == "refs/heads/main"
+    assert context.state_key() is not None
+
+
+def test_git_environment_cannot_redirect_worktree_scope(
+    repository: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    linked = repository.parent / "linked"
+    git(repository, "worktree", "add", "--detach", str(linked), "HEAD")
+    expected = checkout_context(linked)
+    monkeypatch.setenv("GIT_DIR", str(repository / ".git"))
+    monkeypatch.setenv("GIT_WORK_TREE", str(repository))
+    assert checkout_context(linked) == expected
+    alias = repository.parent / "alias"
+    alias.symlink_to(linked, target_is_directory=True)
+    assert cache_root(alias) == cache_root(linked)
+
+
+def test_checkout_change_during_execution_fails_closed(repository: Path) -> None:
+    policy = Contract.model_validate(
+        {
+            "constraints": {
+                "switch": {
+                    "kind": "command",
+                    "command": ["git", "checkout", "-qb", "switched"],
+                    "watch": ["source"],
+                }
+            }
+        }
+    )
+    (repository / "constraintloop.yml").write_text(yaml.safe_dump(policy.model_dump(mode="json")))
+    response = handle_hook(repository, "claude", "stop", {"session_id": "switch"})
+    assert response["continue"] is False
+    assert "checkout changed" in response["stopReason"]
+    assert load_latest_result(repository, "switch") is None
+    git(repository, "checkout", "-q", "main")
+    assert load_latest_result(repository, "switch") is None
+    git(repository, "branch", "-D", "switched")
+    result = CliRunner().invoke(main, ["run", "--project", str(repository)])
+    assert result.exit_code == 1
+    assert "checkout changed" in result.output
+
+
+def test_doctor_explain_and_copied_hooks_target_nested_linked_project(repository: Path) -> None:
+    project = repository / "packages" / "atool"
+    project.mkdir(parents=True)
+    policy = contract()
+    (project / "constraintloop.yml").write_text(yaml.safe_dump(policy.model_dump(mode="json")))
+    git(repository, "add", "packages")
+    git(repository, "commit", "-qm", "nested contract")
+    hook_path = install_hooks(
+        project, "claude", hook_executable=shlex.join([sys.executable, "-m", "constraintloop"])
+    )
+    command = json.loads(hook_path.read_text())["hooks"]["Stop"][0]["hooks"][0]["command"]
+    linked = repository.parent / "linked"
+    git(repository, "worktree", "add", "--detach", str(linked), "HEAD")
+    linked_project = linked / "packages" / "atool"
+    environment = {**os.environ, "PYTHONPATH": str(Path(__file__).resolve().parents[1] / "src")}
+    hook = subprocess.run(
+        command,
+        shell=True,
+        cwd=linked_project,
+        env=environment,
+        input=json.dumps({"session_id": "linked"}),
+        text=True,
+        capture_output=True,
+        check=True,
+    )
+    assert json.loads(hook.stdout).get("continue") is not False
+    assert load_latest_result(linked_project, "check") is not None
+    assert load_latest_result(project, "check") is None
+
+    runner = CliRunner()
+    doctor = runner.invoke(main, ["doctor", "--project", str(linked_project)])
+    assert doctor.exit_code == 0, doctor.output
+    assert f"worktree: {linked}" in doctor.output
+    assert "branch: (detached HEAD)" in doctor.output
+    assert str(cache_root(linked_project)) in doctor.output
+    explain = runner.invoke(main, ["explain", "--json", "--project", str(linked_project)])
+    assert explain.exit_code == 0, explain.output
+    scope = json.loads(explain.output)["scope"]
+    assert scope["project_root"] == str(linked_project)
+    assert scope["worktree_root"] == str(linked)
+    assert scope["branch"] is None
+    assert scope["state_directory"] == str(cache_root(linked_project))
+
+
+@pytest.mark.parametrize("error", [OSError("missing git"), subprocess.TimeoutExpired("git", 5)])
+def test_unreadable_checkout_is_not_treated_as_non_git(
+    repository: Path, monkeypatch: pytest.MonkeyPatch, error: Exception
+) -> None:
+    def fail(*args, **kwargs):
+        raise error
+
+    monkeypatch.setattr("constraintloop.checkout.subprocess.run", fail)
+    with pytest.raises(ValueError, match="Could not inspect Git checkout"):
+        checkout_context(repository)
+
+
+def test_broken_git_marker_fails_closed(tmp_path: Path) -> None:
+    (tmp_path / ".git").write_text("gitdir: missing\n")
+    with pytest.raises(ValueError, match="Could not inspect Git checkout"):
+        checkout_context(tmp_path)
+
+
+def test_non_git_projects_keep_local_state(tmp_path: Path) -> None:
+    assert checkout_context(tmp_path).git_dir is None
+    assert cache_root(tmp_path) == tmp_path / ".constraintloop" / "state"
+
+
+def test_unscoped_legacy_evidence_is_not_imported(repository: Path) -> None:
+    policy = contract()
+    result = ConstraintEngine(repository, policy, use_cache=False).run(Phase.STOP).results[0]
+    legacy = repository / ".constraintloop" / "state"
+    legacy.mkdir(parents=True)
+    evidence = legacy / "evidence.json"
+    evidence.write_text(json.dumps({"check": result.model_dump(mode="json")}))
+
+    assert load_latest_result(repository, "check") is None
+    assert not ConstraintEngine(repository, policy).run(Phase.STOP).results[0].cached
+    assert evidence.is_file()
+
+
+def test_supervisor_does_not_follow_branch_switch_and_releases_original_lease(
+    repository: Path,
+) -> None:
+    policy = contract()
+    policy.constraints["check"] = policy.constraints["check"].model_copy(
+        update={"command": [sys.executable, "-c", "raise SystemExit(75)"]}
+    )
+    policy.loops["completion"].interval_seconds = 0.001
+    runner = supervise(repository, policy, "completion")
+    try:
+        assert next(runner).state == LoopState.WAITING
+        git(repository, "checkout", "-qb", "other")
+        with pytest.raises(ValueError, match="checkout changed"):
+            next(runner)
+        assert not journal_path(repository, "completion").exists()
+        git(repository, "checkout", "-q", "main")
+        with loop_lease(repository, "completion", ttl_seconds=60):
+            pass
+    finally:
+        runner.close()
+
+
+def test_challenge_only_loop_refreshes_request_on_new_head(repository: Path) -> None:
+    policy = contract()
+    policy.constraints = {}
+    policy.loops["completion"].challenge = ChallengeConfig(count=1, watch=["source"])
+    assert run_cycle(repository, policy, "completion").state == LoopState.CHALLENGE
+    first = show_challenge(repository, policy, "completion")["request"]
+    git(repository, "commit", "--allow-empty", "-qm", "new HEAD")
+    assert run_cycle(repository, policy, "completion").state == LoopState.CHALLENGE
+    second = show_challenge(repository, policy, "completion")["request"]
+    assert second["request_id"] != first["request_id"]
+    assert second["input_snapshot"] != first["input_snapshot"]