worktree-runtime 0.1.0a3__tar.gz → 0.1.1__tar.gz

{worktree_runtime-0.1.0a3 → worktree_runtime-0.1.1}/Cargo.lock

@@ -1,6 +1,6 @@
 # This file is automatically @generated by Cargo.
 # It is not intended for manual editing.
-version = 3
+version = 4
 
 [[package]]
 name = "android_system_properties"
@@ -743,7 +743,7 @@ dependencies = [
 
 [[package]]
 name = "worktree_runtime_core"
-version = "0.1.0-alpha.3"
+version = "0.1.1"
 dependencies = [
  "chrono",
  "fs2",
@@ -760,7 +760,7 @@ dependencies = [
 
 [[package]]
 name = "worktree_runtime_pyo3"
-version = "0.1.0-alpha.3"
+version = "0.1.1"
 dependencies = [
  "chrono",
  "pyo3",

{worktree_runtime-0.1.0a3 → worktree_runtime-0.1.1}/Cargo.toml

@@ -3,9 +3,9 @@ resolver = "2"
 members = ["crates/worktree_runtime_core", "crates/worktree_runtime_pyo3"]
 
 [workspace.package]
-version = "0.1.0-alpha.3"
+version = "0.1.1"
 edition = "2021"
-rust-version = "1.75"
+rust-version = "1.85"
 license = "LicenseRef-Proprietary"
 publish = false
 
@@ -18,7 +18,7 @@ sha1 = "0.10"
 fs2 = "0.4"
 tempfile = "3.10"
 wait-timeout = "0.2"
-pyo3 = { version = "0.29", features = ["extension-module"] }
+pyo3 = { version = "0.29", features = ["abi3-py310"] }
 chrono = "0.4"
 
 [profile.release]

{worktree_runtime-0.1.0a3 → worktree_runtime-0.1.1}/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2026 adaptive-task contributors
+Copyright (c) 2026 bamboocity
 All rights reserved.
 
 This software and associated documentation files (the "Software") are
@@ -6,6 +6,12 @@ proprietary. Unauthorized copying, modification, distribution, or use of
 the Software, via any medium, is strictly prohibited except as expressly
 authorized in writing by the copyright holder.
 
+The Software is distributed on the Python Package Index as binary wheels
+and as a source distribution (sdist) that contains this source code. That
+distribution is provided solely so the package can be installed and built;
+it does not grant any right to copy, modify, or redistribute the source
+beyond what is necessary to install the Software.
+
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

worktree_runtime-0.1.1/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: worktree-runtime
+Version: 0.1.1
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Rust
+Classifier: Typing :: Typed
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pyyaml>=6.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.14 ; extra == 'dev'
+Provides-Extra: dev
+License-File: LICENSE
+Summary: Worktree identity, binding persistence, and checkout substrate
+Author: bamboocity
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/bamboocity/worktree-runtime/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/bamboocity/worktree-runtime
+
+# worktree-runtime
+
+Library for worktree **identity**, **binding persistence**, **checkout
+validation**, and **path resolution**.
+
+Consumers (adaptive-task / Noveler) call this so they do not each invent
+project id, session↔worktree binding, main-vs-linked checks, or
+state / shared paths. The public symbol list is
+[`src/worktree_runtime/SURFACE.yaml`](src/worktree_runtime/SURFACE.yaml).
+
+Binding store API: `register_binding`, `load_binding`, `recover_binding`,
+`list_bindings`, and `remove_binding`. `git worktree remove` and vanish stay
+in the consumer.
+
+Rust is the implementation SSOT. Python is a shim, typing stubs, contract tests,
+and a thin audit CLI. Missing native support is an install error; there is no
+silent Python fallback in this project.
+
+## Scope
+
+This crate answers four questions and records consumer mutations:
+
+| Responsibility | What the library does |
+| --- | --- |
+| Identity | Resolve project id, main branches, GitHub policy, and the `NOVELER_*` / location env catalog from cwd, env, git, and project config. |
+| Binding | Persist, load, recover, and validate a session↔worktree record (`WorktreeBinding`). Reject before treating a cwd as bound. |
+| Checkout | Resolve a `GitWorktree` (`rev-parse`), classify main vs linked, list porcelain entries, emit reason codes. |
+| Path | Resolve worktree base / dir / state dir / known bases with fixed precedence. `NOVELER_WORKTREE_BASE` and `config/worktree.yaml` overrides apply only when `CI` / `GITHUB_ACTIONS` is set; elsewhere the base is `~/.adaptive-task/worktrees/<project_id>`. Normalize and fingerprint paths. |
+
+Audit (`record_event` / `read_records` / rotation, plus
+`presentation/audit_cli.py`) is append-only logging of consumer git
+mutations (`worktree_remove`, `branch_delete`). It is not a session log.
+
+### Out of scope
+
+- **Agent isolation.** Codex Desktop, Cursor, and Claude Code create a
+  worktree (or checkout) so one chat does not dirty the user's main tree.
+  That sandbox is a different layer. This package does not replace it.
+- **Session orchestration.** `adaptive-task init` / `next` / `report` stay
+  in the consumer.
+- **Prep / vanish / cleanup hooks.** Detecting a disappeared worktree,
+  refusing cleanup, and running merge-cleanup tooling stay in adaptive-task.
+- **`git worktree add` / `remove` as a product operation.** This crate
+  resolves locations and validates state. The consumer mutates git.
+
+Using Codex Desktop only as an editor does not require importing this
+package. Running adaptive-task identity, binding, or path policy still does.
+Agent isolation worktrees and session worktrees can nest. Config may move
+the session base when `CODEX_CLI` or `CLAUDE_CODE` is set. That override
+exists because the two layers meet; it does not make this library redundant.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    callers["consumers"] -->|"worktree_runtime.api"| shim["Python shim and stubs"]
+    shim --> pyo3["PyO3 binding"]
+    pyo3 --> core["Rust core"]
+    contract["contract pytest"] -->|"black-box"| shim
+    cargo["cargo test"] --> core
+    release["maturin wheels"] --> callers
+```
+
+## Layout
+
+Layout rationale is in [DESIGN.md](DESIGN.md).
+
+- `crates/worktree_runtime_core/` — behavior SSOT
+- `crates/worktree_runtime_pyo3/` — Python C-API translation only
+- `src/worktree_runtime/` — `api` re-export, `.pyi`, `SURFACE.yaml`, `presentation/audit_cli.py`
+- `src/_worktree_runtime_rust/` — placeholder package that hosts the cdylib built by maturin (`python-source = "src"`)
+- `tests/contract/` — `from worktree_runtime.api import ...` only; `tests/cli/` — audit CLI exit codes
+
+Distribution name is `worktree-runtime`. Import name is `worktree_runtime`.
+`pyproject.toml` version and `Cargo.toml` `workspace.package.version` must match.
+The crate is proprietary (`LICENSE`; all rights reserved). CI uses the `stable` toolchain with rustfmt and clippy.
+
+## Change protocol
+
+Multi-file, refactor, behavior, or core+pyo3+facade+contract work: run
+`adaptive-gate` first ([AGENTS.md](AGENTS.md) Routing). Testing policy:
+`.cursor/rules/testing.mdc`.
+
+1. Behavior: add a failing cargo execution test, then implement in
+   `worktree_runtime_core` and run `cargo test`.
+2. Public-surface shape only: update `SURFACE.yaml` and `.pyi`, plus a thin
+   contract assertion under `tests/contract/`. Do not put behavior suites in
+   pytest.
+3. Export through PyO3; keep the shim as a re-export.
+4. When the public surface changed, build a wheel and run the contract and
+   CLI pytest. `cargo fmt --check` and `clippy -D warnings` are required.
+
+The verify loop (commands, hook setup, release steps) is defined once in
+[BUILD.md](BUILD.md).
+
+## Build
+
+See [BUILD.md](BUILD.md). CI always runs fmt, clippy, cargo test, maturin,
+contract+CLI pytest, `mypy.stubtest`, and an MSRV check, through
+`.github/actions/rust-checks`.
+Wheels are `abi3-py310` (CPython 3.10+) for Windows amd64, macOS x86_64 and
+arm64, and manylinux x86_64 / aarch64. Pure-Python wheels are not published.
+

worktree_runtime-0.1.1/README.md

@@ -0,0 +1,102 @@
+# worktree-runtime
+
+Library for worktree **identity**, **binding persistence**, **checkout
+validation**, and **path resolution**.
+
+Consumers (adaptive-task / Noveler) call this so they do not each invent
+project id, session↔worktree binding, main-vs-linked checks, or
+state / shared paths. The public symbol list is
+[`src/worktree_runtime/SURFACE.yaml`](src/worktree_runtime/SURFACE.yaml).
+
+Binding store API: `register_binding`, `load_binding`, `recover_binding`,
+`list_bindings`, and `remove_binding`. `git worktree remove` and vanish stay
+in the consumer.
+
+Rust is the implementation SSOT. Python is a shim, typing stubs, contract tests,
+and a thin audit CLI. Missing native support is an install error; there is no
+silent Python fallback in this project.
+
+## Scope
+
+This crate answers four questions and records consumer mutations:
+
+| Responsibility | What the library does |
+| --- | --- |
+| Identity | Resolve project id, main branches, GitHub policy, and the `NOVELER_*` / location env catalog from cwd, env, git, and project config. |
+| Binding | Persist, load, recover, and validate a session↔worktree record (`WorktreeBinding`). Reject before treating a cwd as bound. |
+| Checkout | Resolve a `GitWorktree` (`rev-parse`), classify main vs linked, list porcelain entries, emit reason codes. |
+| Path | Resolve worktree base / dir / state dir / known bases with fixed precedence. `NOVELER_WORKTREE_BASE` and `config/worktree.yaml` overrides apply only when `CI` / `GITHUB_ACTIONS` is set; elsewhere the base is `~/.adaptive-task/worktrees/<project_id>`. Normalize and fingerprint paths. |
+
+Audit (`record_event` / `read_records` / rotation, plus
+`presentation/audit_cli.py`) is append-only logging of consumer git
+mutations (`worktree_remove`, `branch_delete`). It is not a session log.
+
+### Out of scope
+
+- **Agent isolation.** Codex Desktop, Cursor, and Claude Code create a
+  worktree (or checkout) so one chat does not dirty the user's main tree.
+  That sandbox is a different layer. This package does not replace it.
+- **Session orchestration.** `adaptive-task init` / `next` / `report` stay
+  in the consumer.
+- **Prep / vanish / cleanup hooks.** Detecting a disappeared worktree,
+  refusing cleanup, and running merge-cleanup tooling stay in adaptive-task.
+- **`git worktree add` / `remove` as a product operation.** This crate
+  resolves locations and validates state. The consumer mutates git.
+
+Using Codex Desktop only as an editor does not require importing this
+package. Running adaptive-task identity, binding, or path policy still does.
+Agent isolation worktrees and session worktrees can nest. Config may move
+the session base when `CODEX_CLI` or `CLAUDE_CODE` is set. That override
+exists because the two layers meet; it does not make this library redundant.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    callers["consumers"] -->|"worktree_runtime.api"| shim["Python shim and stubs"]
+    shim --> pyo3["PyO3 binding"]
+    pyo3 --> core["Rust core"]
+    contract["contract pytest"] -->|"black-box"| shim
+    cargo["cargo test"] --> core
+    release["maturin wheels"] --> callers
+```
+
+## Layout
+
+Layout rationale is in [DESIGN.md](DESIGN.md).
+
+- `crates/worktree_runtime_core/` — behavior SSOT
+- `crates/worktree_runtime_pyo3/` — Python C-API translation only
+- `src/worktree_runtime/` — `api` re-export, `.pyi`, `SURFACE.yaml`, `presentation/audit_cli.py`
+- `src/_worktree_runtime_rust/` — placeholder package that hosts the cdylib built by maturin (`python-source = "src"`)
+- `tests/contract/` — `from worktree_runtime.api import ...` only; `tests/cli/` — audit CLI exit codes
+
+Distribution name is `worktree-runtime`. Import name is `worktree_runtime`.
+`pyproject.toml` version and `Cargo.toml` `workspace.package.version` must match.
+The crate is proprietary (`LICENSE`; all rights reserved). CI uses the `stable` toolchain with rustfmt and clippy.
+
+## Change protocol
+
+Multi-file, refactor, behavior, or core+pyo3+facade+contract work: run
+`adaptive-gate` first ([AGENTS.md](AGENTS.md) Routing). Testing policy:
+`.cursor/rules/testing.mdc`.
+
+1. Behavior: add a failing cargo execution test, then implement in
+   `worktree_runtime_core` and run `cargo test`.
+2. Public-surface shape only: update `SURFACE.yaml` and `.pyi`, plus a thin
+   contract assertion under `tests/contract/`. Do not put behavior suites in
+   pytest.
+3. Export through PyO3; keep the shim as a re-export.
+4. When the public surface changed, build a wheel and run the contract and
+   CLI pytest. `cargo fmt --check` and `clippy -D warnings` are required.
+
+The verify loop (commands, hook setup, release steps) is defined once in
+[BUILD.md](BUILD.md).
+
+## Build
+
+See [BUILD.md](BUILD.md). CI always runs fmt, clippy, cargo test, maturin,
+contract+CLI pytest, `mypy.stubtest`, and an MSRV check, through
+`.github/actions/rust-checks`.
+Wheels are `abi3-py310` (CPython 3.10+) for Windows amd64, macOS x86_64 and
+arm64, and manylinux x86_64 / aarch64. Pure-Python wheels are not published.

worktree_runtime-0.1.1/crates/worktree_runtime_core/AGENTS.md

@@ -0,0 +1,55 @@
+# worktree_runtime_core
+
+This crate is the behavior SSOT. Do not add PyO3 or Python dependencies.
+Behavior changes belong here with `cargo test` (`.cursor/rules/testing.mdc`);
+do not treat pytest as the SSOT.
+
+## Layers
+
+- `domain/` — value objects and pure rules (`binding`, `audit`, `paths`,
+  `porcelain`, `git_worktree`, `github_policy`). Today `paths::normalize_path`
+  still canonicalizes through the filesystem and `WorktreeBinding::new` calls
+  it; treat that as a known exception, do not add more I/O to `domain/`.
+- `application/` — services that compose domain + infrastructure
+  (`binding_lifecycle`, `validation`, `git_worktree_service`). They own the
+  reason codes callers branch on.
+- `infrastructure/` — filesystem, env, git subprocess, config readers.
+
+## Conventions that are not obvious from the code
+
+- **git**: every subprocess goes through `infrastructure::git_adapter`.
+  `git_output` returns `Result<String, GitInvokeError>`; `Exit` means the
+  repository state is unusable (not a repo, detached HEAD), every other
+  variant means git itself could not run and callers report
+  `WORKTREE_GIT_UNAVAILABLE`. Do not collapse errors to `""`. Tests
+  simulate a missing binary with `common::MissingGit` (thread-local
+  `override_git_program`), never by clearing `PATH`.
+- **Reason codes** are a public contract (adaptive-task branches on them).
+  Adding one needs a CHANGELOG entry; renaming one is a breaking change.
+- **Binding store** (`infrastructure::binding_store`) is locked
+  (`bindings.json.lock`) and fail-closed: a corrupt file is an error, never
+  an empty store.
+- **Audit** (`infrastructure::audit_*`) is fail-open by design: a failed
+  write prints `[WORKTREE-AUDIT-FAILOPEN] ...` to stderr and returns
+  `Err(AuditWriteError)`; the PyO3 layer decides whether to raise
+  (`strict`). Rotation runs under the append lock; `read_records` reads
+  archives too. The only `unsafe` in the crate is `libc::gethostname` in
+  `audit_writer.rs` (unix).
+- **Config precedence**: `NOVELER_WORKTREE_BASE` and
+  `config/worktree.yaml` overrides are honored only when `CI` or
+  `GITHUB_ACTIONS` is set (`worktree_base_resolver.rs`). Outside CI the
+  base is `~/.adaptive-task/worktrees/<project_id>`. A missing
+  `config/worktree.yaml` is the default path. A file that exists but cannot
+  be read or parsed raises `WORKTREE_CONFIG_UNREADABLE` from the resolvers
+  that load it (`resolve_worktree_base`, `resolve_worktree_dir`,
+  `resolve_known_worktree_bases`) when CI consults it.
+- **project_id**: a missing `pyproject.toml` or a missing
+  `tool.adaptive-task.project_id` is `noveler`. An existing file that is not
+  valid TOML raises `WORKTREE_PROJECT_CONFIG_UNREADABLE`. A declared id that
+  fails `^[a-z][a-z0-9_-]{0,63}$` raises `ProjectIdInvalidError`
+  (`PROJECT_ID_INVALID`) from `resolve_project_id` and
+  `resolve_state_dir_name`; it is not used as a directory name. An empty id
+  stays `noveler`.
+- **Logging**: `log::debug!` / `log::warn!` for diagnostics; the two
+  `eprintln!` breadcrumbs (`failopen_message`, `suspicious_extra_message`)
+  are frozen by tests and stay on stderr.

worktree_runtime-0.1.1/crates/worktree_runtime_core/src/application/binding_lifecycle.rs

@@ -0,0 +1,337 @@
+//! Worktree binding lifecycle and current-binding validation.
+use crate::application::validation::validate_binding;
+use crate::domain::binding::{
+    BindingValidationOptions, BindingValidationResult, WorktreeBinding, WorktreeBindingFields,
+};
+use crate::domain::paths::normalize_path;
+use crate::infrastructure::binding_store::{
+    resolve_store_root, BindingStoreError, WorktreeBindingStore,
+};
+use crate::infrastructure::env_keys::{NOVELER_BRANCH_ENV, NOVELER_WORKTREE_ENV};
+use crate::infrastructure::git_adapter::{git_output, GitInvokeError};
+use crate::infrastructure::project_id_resolver::{resolve_project_id, resolve_state_dir_name};
+use serde_json::Value;
+use std::collections::HashMap;
+use std::fmt;
+use std::path::{Path, PathBuf};
+
+/// Why [`register_binding`] refused or failed. `Display` renders
+/// `<REASON_CODE>: <message>` for both variants.
+#[derive(Debug)]
+pub enum RegisterBindingError {
+    /// The worktree / git state did not validate; nothing was written.
+    Validation {
+        reason_code: String,
+        message: String,
+    },
+    /// Validation passed but the binding could not be persisted.
+    Store(BindingStoreError),
+}
+
+impl RegisterBindingError {
+    pub fn reason_code(&self) -> &str {
+        match self {
+            RegisterBindingError::Validation { reason_code, .. } => reason_code,
+            RegisterBindingError::Store(err) => err.reason_code(),
+        }
+    }
+}
+
+impl fmt::Display for RegisterBindingError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            RegisterBindingError::Validation {
+                reason_code,
+                message,
+            } => write!(f, "{reason_code}: {message}"),
+            RegisterBindingError::Store(err) => write!(f, "{err}"),
+        }
+    }
+}
+
+impl std::error::Error for RegisterBindingError {}
+
+impl From<BindingStoreError> for RegisterBindingError {
+    fn from(err: BindingStoreError) -> Self {
+        RegisterBindingError::Store(err)
+    }
+}
+
+fn session_state_subpath(
+    repo_root: &Path,
+) -> Result<PathBuf, crate::infrastructure::project_id_resolver::ProjectResolveError> {
+    let pid = resolve_project_id(Some(&repo_root.to_string_lossy()))?;
+    Ok(PathBuf::from(resolve_state_dir_name(Some(&pid))?)
+        .join("state")
+        .join("adaptive-task"))
+}
+
+pub fn register_binding(
+    session_id: &str,
+    worktree_path: &str,
+    branch: &str,
+    repo_root: &str,
+    state_path: Option<&str>,
+    source_ref: &str,
+) -> Result<WorktreeBinding, RegisterBindingError> {
+    let worktree = normalize_path(worktree_path);
+    let repo = resolve_store_root(Path::new(&normalize_path(repo_root)));
+    let git_common_dir = match git_output(
+        Path::new(&worktree),
+        &["rev-parse", "--path-format=absolute", "--git-common-dir"],
+    ) {
+        Ok(dir) if !dir.is_empty() => dir,
+        Ok(_) | Err(GitInvokeError::Exit { .. }) => {
+            return Err(RegisterBindingError::Validation {
+                reason_code: "WORKTREE_GIT_COMMON_DIR_MISSING".to_string(),
+                message: "worktree git common dir is required".to_string(),
+            });
+        }
+        Err(err) => {
+            return Err(RegisterBindingError::Validation {
+                reason_code: crate::application::validation::REASON_GIT_UNAVAILABLE.to_string(),
+                message: format!("git could not be run: {err}"),
+            });
+        }
+    };
+    let state_path = if let Some(sp) = state_path {
+        normalize_path(sp)
+    } else {
+        let subpath = session_state_subpath(&repo).map_err(|err| match err {
+            crate::infrastructure::project_id_resolver::ProjectResolveError::Invalid {
+                message,
+                reason_code,
+            } => RegisterBindingError::Validation {
+                reason_code,
+                message,
+            },
+            other => RegisterBindingError::Store(other.into()),
+        })?;
+        normalize_path(&PathBuf::from(&worktree).join(&subpath).to_string_lossy())
+    };
+    let binding = WorktreeBinding::new(WorktreeBindingFields {
+        session_id: session_id.to_string(),
+        worktree: worktree.clone(),
+        branch: branch.to_string(),
+        state_path,
+        git_common_dir: normalize_path(&git_common_dir),
+        main_worktree: repo.to_string_lossy().to_string(),
+        commit_ish: source_ref.to_string(),
+        schema_version: None,
+    });
+    let mut env = HashMap::new();
+    env.insert(NOVELER_WORKTREE_ENV.to_string(), worktree.clone());
+    let validation = validate_binding(&binding, Some(&worktree), Some(&env), true, None);
+    if !validation.ok {
+        return Err(RegisterBindingError::Validation {
+            reason_code: validation.reason_code,
+            message: validation.message,
+        });
+    }
+    let store = WorktreeBindingStore::new(&repo)?;
+    store.upsert(&binding)?;
+    Ok(binding)
+}
+
+pub fn load_binding(
+    session_id: &str,
+    repo_root: &str,
+) -> Result<Option<WorktreeBinding>, BindingStoreError> {
+    WorktreeBindingStore::new(repo_root)?.load(session_id)
+}
+
+pub fn list_bindings(repo_root: &str) -> Result<Vec<WorktreeBinding>, BindingStoreError> {
+    WorktreeBindingStore::new(repo_root)?.list()
+}
+
+pub fn remove_binding(
+    session_id: &str,
+    repo_root: &str,
+) -> Result<Option<WorktreeBinding>, BindingStoreError> {
+    WorktreeBindingStore::new(repo_root)?.remove(session_id)
+}
+
+/// Rebuild a binding from legacy `metadata.json` and persist it. `Ok(None)`
+/// means there was nothing usable to recover; `Err` means the store itself is
+/// unavailable.
+pub fn recover_binding(
+    session_id: &str,
+    repo_root: &str,
+) -> Result<Option<WorktreeBinding>, BindingStoreError> {
+    let candidate = normalize_path(repo_root);
+    let repo = resolve_store_root(Path::new(&candidate));
+    if let Some(binding) = recover_binding_from_metadata(session_id, Path::new(&candidate), &repo)?
+    {
+        return Ok(Some(binding));
+    }
+    if candidate != repo.to_string_lossy() {
+        return recover_binding_from_metadata(session_id, &repo, &repo);
+    }
+    Ok(None)
+}
+
+fn recover_binding_from_metadata(
+    session_id: &str,
+    metadata_root: &Path,
+    repo_root: &Path,
+) -> Result<Option<WorktreeBinding>, BindingStoreError> {
+    let state_subpath = session_state_subpath(repo_root)?;
+    let metadata = metadata_root
+        .join(state_subpath)
+        .join("sessions")
+        .join(session_id)
+        .join("metadata.json");
+    if !metadata.is_file() {
+        return Ok(None);
+    }
+    let Ok(content) = std::fs::read_to_string(&metadata) else {
+        return Ok(None);
+    };
+    let Ok(payload) = serde_json::from_str::<Value>(&content) else {
+        return Ok(None);
+    };
+    let Some(obj) = payload.as_object() else {
+        return Ok(None);
+    };
+    let Some(worktree_path) = obj.get("worktree_path").and_then(|v| v.as_str()) else {
+        return Ok(None);
+    };
+    let Some(branch) = obj
+        .get("branch")
+        .and_then(|v| v.as_str())
+        .or_else(|| obj.get("branch_name").and_then(|v| v.as_str()))
+    else {
+        return Ok(None);
+    };
+    if worktree_path.trim().is_empty() {
+        return Ok(None);
+    }
+    let source_ref = obj.get("source_ref").and_then(|v| v.as_str()).unwrap_or("");
+    match register_binding(
+        session_id,
+        worktree_path,
+        branch,
+        &repo_root.to_string_lossy(),
+        None,
+        source_ref,
+    ) {
+        Ok(binding) => Ok(Some(binding)),
+        Err(RegisterBindingError::Store(err)) => Err(err),
+        Err(RegisterBindingError::Validation {
+            reason_code,
+            message,
+        }) => {
+            log::debug!(
+                "recover_binding({session_id}): metadata {} rejected: {reason_code}: {message}",
+                metadata.display()
+            );
+            Ok(None)
+        }
+    }
+}
+
+/// Arguments for [`validate_current_binding`], grouped to avoid a
+/// too-many-arguments positional signature.
+pub struct BindingValidationRequest<'a> {
+    pub repo_root: &'a str,
+    pub session_id: Option<&'a str>,
+    pub cwd: &'a str,
+    pub env: Option<&'a HashMap<String, String>>,
+    pub check_git: bool,
+    pub require_registered_binding: bool,
+    pub require_env_worktree: bool,
+    pub require_git_state: bool,
+}
+
+fn store_unavailable(err: BindingStoreError) -> BindingValidationResult {
+    BindingValidationResult {
+        ok: false,
+        reason_code: err.reason_code().to_string(),
+        message: err.to_string(),
+        binding: None,
+    }
+}
+
+fn env_missing() -> BindingValidationResult {
+    BindingValidationResult {
+        ok: false,
+        reason_code: "WORKTREE_ENV_MISSING".to_string(),
+        message: format!("{} is required for this validation", NOVELER_WORKTREE_ENV),
+        binding: None,
+    }
+}
+
+pub fn validate_current_binding(request: BindingValidationRequest) -> BindingValidationResult {
+    let options = BindingValidationOptions {
+        require_env_worktree: request.require_env_worktree,
+        require_git_state: request.require_git_state,
+    };
+    let binding = match request.session_id {
+        Some(sid) => match load_binding(sid, request.repo_root) {
+            Ok(Some(b)) => b,
+            Ok(None) => match recover_binding(sid, request.repo_root) {
+                Ok(Some(b)) => b,
+                Ok(None) if request.require_registered_binding => {
+                    return BindingValidationResult {
+                        ok: false,
+                        reason_code: "WORKTREE_BINDING_MISSING".to_string(),
+                        message: "no worktree binding found for session".to_string(),
+                        binding: None,
+                    };
+                }
+                Ok(None) => match build_env_fallback_binding(sid, request.env, request.repo_root) {
+                    Some(b) => b,
+                    None => return env_missing(),
+                },
+                Err(err) => return store_unavailable(err),
+            },
+            Err(err) => return store_unavailable(err),
+        },
+        None => match build_env_fallback_binding("", request.env, request.repo_root) {
+            Some(b) => b,
+            None => return env_missing(),
+        },
+    };
+    validate_binding(
+        &binding,
+        Some(request.cwd),
+        request.env,
+        request.check_git,
+        Some(&options),
+    )
+}
+
+fn build_env_fallback_binding(
+    session_id: &str,
+    env: Option<&HashMap<String, String>>,
+    repo_root: &str,
+) -> Option<WorktreeBinding> {
+    let env = env?;
+    let env_worktree = env
+        .get(NOVELER_WORKTREE_ENV)
+        .map(|s| s.trim().to_string())
+        .unwrap_or_default();
+    if env_worktree.is_empty() {
+        return None;
+    }
+    let normalized_worktree = normalize_path(&env_worktree);
+    let repo = resolve_store_root(Path::new(&normalized_worktree));
+    let branch = env
+        .get(NOVELER_BRANCH_ENV)
+        .map(|s| s.to_string())
+        .unwrap_or_default();
+    let state_path = PathBuf::from(&normalized_worktree)
+        .join(session_state_subpath(&repo).ok()?)
+        .to_string_lossy()
+        .to_string();
+    Some(WorktreeBinding::new(WorktreeBindingFields {
+        session_id: session_id.to_string(),
+        worktree: normalized_worktree,
+        branch,
+        state_path,
+        git_common_dir: String::new(),
+        main_worktree: normalize_path(repo_root),
+        commit_ish: "env-fallback".to_string(),
+        schema_version: None,
+    }))
+}