coprogrammer 0.2.0a1__tar.gz → 0.3.0a1__tar.gz

{coprogrammer-0.2.0a1/src/coprogrammer.egg-info → coprogrammer-0.3.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coprogrammer
-Version: 0.2.0a1
+Version: 0.3.0a1
 Summary: Open protocol and toolkit for semantic integration in multi-agent software development.
 Author: Qiu Guanzong
 License: MIT License
@@ -57,22 +57,26 @@ specific set of commits. Maintainers decide what reaches `main`.
 [Ecosystem comparison](docs/research/ecosystem-2026-09-30.md) ·
 [Contributing](CONTRIBUTING.md) · [MIT](LICENSE)
 
-> **0.2.0a1 source preview.** The multi-platform upgrade is available in
-> [PR #1](https://github.com/QIU-Guanzong/CoProgrammer/pull/1).
-> Client configuration generators and provider adapters are implemented;
-> live client/provider verification is still pending. Use the source setup below.
+> **v0.3 preview (`0.3.0a1`).** Check [PyPI](https://pypi.org/project/coprogrammer/)
+> for published versions, or use the source installation below. Client configuration
+> generators and provider adapters are implemented; live client/provider
+> verification is still pending.
 
-## New in this source update
+## New in v0.3
 
-- **One-command offline demo:** two real Git worktrees exercise claims,
-  dependency and path guards, message receipt and task completion. No model key.
-- **One collaboration briefing:** ready work, blockers, stale windows, open
-  decisions and next actions, available through both CLI and MCP.
-- **Less repeated state replay:** status views reuse validation within a
-  snapshot, while transactions and standalone history checks stay intact.
-  See the [reproducible benchmark](docs/upgrade-2026-09-30/performance.md).
-- **A complete Chinese entrypoint** and a [six-project research update](docs/research/ecosystem-2026-09-30.md)
-  explaining the choices behind this increment.
+- **Session-aware dispatch:** preview tasks compatible with this client,
+  session and worktree, then claim atomically.
+- **Content-bound checks:** record explicit local commands and detect stale
+  results after file edits, command/runtime changes or expiry.
+- **Portable handoffs:** compare versions, exact revisions, task scope and
+  content when moving work to another clone or computer. Local ownership remains
+  separate and receiving-machine checks are required.
+
+See [dispatch and handoff](docs/WORKSPACE_HANDOFF.md),
+[check receipts](docs/VALIDATION_EVIDENCE.md) and the
+[source-backed choices](docs/upgrade-2026-10-04/research.md).
+The offline demo, local messages, review adapters and preview-first setup remain
+available through CLI, MCP and packaged workflows.
 
 ## When it helps
 
@@ -111,19 +115,23 @@ Requires **Python 3.10+** and **Git 2.36+**. Start with the offline demo; no mod
 is needed.
 
 ```sh
-git clone --branch codex/multi-platform-upgrade https://github.com/QIU-Guanzong/CoProgrammer.git
-cd CoProgrammer
 python3 -m venv .venv
 source .venv/bin/activate
-python -m pip install -e .
-
+python -m pip install --pre coprogrammer
 coprogrammer demo
 ```
 
+To work from source instead, clone the default branch and replace the package
+install with `python -m pip install -e .`:
+
+```sh
+git clone https://github.com/QIU-Guanzong/CoProgrammer.git
+cd CoProgrammer
+```
+
 On Windows, create the environment with `python -m venv .venv` and activate it
-in PowerShell with `.venv/Scripts/Activate.ps1`. The clone command above selects
-the upgrade branch explicitly. For your own project, keep this environment
-active, change to that project's checkout, and use its base branch.
+in PowerShell with `.venv/Scripts/Activate.ps1`. For your own project, keep this
+environment active, change to that project's checkout, and use its base branch.
 
 The demo creates and cleans up a temporary repository and two worktrees. It
 exercises the actual coordination code; the Codex/Claude names are local

{coprogrammer-0.2.0a1 → coprogrammer-0.3.0a1}/README.md

@@ -16,22 +16,26 @@ specific set of commits. Maintainers decide what reaches `main`.
 [Ecosystem comparison](docs/research/ecosystem-2026-09-30.md) ·
 [Contributing](CONTRIBUTING.md) · [MIT](LICENSE)
 
-> **0.2.0a1 source preview.** The multi-platform upgrade is available in
-> [PR #1](https://github.com/QIU-Guanzong/CoProgrammer/pull/1).
-> Client configuration generators and provider adapters are implemented;
-> live client/provider verification is still pending. Use the source setup below.
-
-## New in this source update
-
-- **One-command offline demo:** two real Git worktrees exercise claims,
-  dependency and path guards, message receipt and task completion. No model key.
-- **One collaboration briefing:** ready work, blockers, stale windows, open
-  decisions and next actions, available through both CLI and MCP.
-- **Less repeated state replay:** status views reuse validation within a
-  snapshot, while transactions and standalone history checks stay intact.
-  See the [reproducible benchmark](docs/upgrade-2026-09-30/performance.md).
-- **A complete Chinese entrypoint** and a [six-project research update](docs/research/ecosystem-2026-09-30.md)
-  explaining the choices behind this increment.
+> **v0.3 preview (`0.3.0a1`).** Check [PyPI](https://pypi.org/project/coprogrammer/)
+> for published versions, or use the source installation below. Client configuration
+> generators and provider adapters are implemented; live client/provider
+> verification is still pending.
+
+## New in v0.3
+
+- **Session-aware dispatch:** preview tasks compatible with this client,
+  session and worktree, then claim atomically.
+- **Content-bound checks:** record explicit local commands and detect stale
+  results after file edits, command/runtime changes or expiry.
+- **Portable handoffs:** compare versions, exact revisions, task scope and
+  content when moving work to another clone or computer. Local ownership remains
+  separate and receiving-machine checks are required.
+
+See [dispatch and handoff](docs/WORKSPACE_HANDOFF.md),
+[check receipts](docs/VALIDATION_EVIDENCE.md) and the
+[source-backed choices](docs/upgrade-2026-10-04/research.md).
+The offline demo, local messages, review adapters and preview-first setup remain
+available through CLI, MCP and packaged workflows.
 
 ## When it helps
 
@@ -70,19 +74,23 @@ Requires **Python 3.10+** and **Git 2.36+**. Start with the offline demo; no mod
 is needed.
 
 ```sh
-git clone --branch codex/multi-platform-upgrade https://github.com/QIU-Guanzong/CoProgrammer.git
-cd CoProgrammer
 python3 -m venv .venv
 source .venv/bin/activate
-python -m pip install -e .
-
+python -m pip install --pre coprogrammer
 coprogrammer demo
 ```
 
+To work from source instead, clone the default branch and replace the package
+install with `python -m pip install -e .`:
+
+```sh
+git clone https://github.com/QIU-Guanzong/CoProgrammer.git
+cd CoProgrammer
+```
+
 On Windows, create the environment with `python -m venv .venv` and activate it
-in PowerShell with `.venv/Scripts/Activate.ps1`. The clone command above selects
-the upgrade branch explicitly. For your own project, keep this environment
-active, change to that project's checkout, and use its base branch.
+in PowerShell with `.venv/Scripts/Activate.ps1`. For your own project, keep this
+environment active, change to that project's checkout, and use its base branch.
 
 The demo creates and cleans up a temporary repository and two worktrees. It
 exercises the actual coordination code; the Codex/Claude names are local

{coprogrammer-0.2.0a1 → coprogrammer-0.3.0a1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "coprogrammer"
-version = "0.2.0a1"
+version = "0.3.0a1"
 description = "Open protocol and toolkit for semantic integration in multi-agent software development."
 readme = "README.md"
 requires-python = ">=3.10"

{coprogrammer-0.2.0a1 → coprogrammer-0.3.0a1}/src/coprogrammer/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0a1"
+__version__ = "0.3.0a1"

{coprogrammer-0.2.0a1 → coprogrammer-0.3.0a1}/src/coprogrammer/assets/skills/coprogrammer-active-sync/SKILL.md

@@ -16,8 +16,9 @@ touch overlapping code or shared contracts.
 
 ## Workflow
 
-For cross-window work, use a matching source-preview CLI with `manager session`
-and `manager sync` available. Keep one session ID per window, even when several
+For cross-window work, check `coprogrammer --version` in each environment.
+Use CoProgrammer 0.3+ for dispatch previews, content-bound checks and portable
+handoffs; existing session/claim/message commands remain available. Keep one session ID per window, even when several
 windows use the same client. Register once in that window's working tree; resume
 with `pulse`, not another registration:
 
@@ -33,6 +34,8 @@ The inbox snapshot still includes unacknowledged messages after cursor advanceme
 `freshness` measures explicit pulses, not process liveness; reads do not keep a
 session alive. Git worktrees share Manager state; independent clones do not.
 
+Preview eligible work with `coprogrammer manager dispatch --session <window-id>`.
+This read does not claim or pulse; claim always rechecks constraints atomically.
 For queued work, create scoped tasks with `manager task create`, optional
 `--depends-on` and `--client` eligibility. Use `manager task claim` to atomically
 claim a task and its path lease; preserve the returned `claim_id`. Do not request
@@ -53,6 +56,27 @@ they do not intercept writes or replace code review. Use a named Git branch,
 not detached HEAD. Pulse before the session becomes stale and renew claims
 before expiry; sync does neither.
 
+Record explicit noninteractive checks with content-bound receipts before reporting
+validation. Use an ignored directory or output outside the checkout:
+
+```bash
+coprogrammer check run --label tests --output .coprogrammer/checks/tests.json \
+  -- python -m unittest discover -s tests
+coprogrammer check verify --artifact .coprogrammer/checks/tests.json \
+  -- python -m unittest discover -s tests
+```
+
+A failed, changed, expired or missing record cannot establish a current pass.
+Ignored files and external inputs are outside the fingerprint; receipts do not
+authenticate the worker. MCP `check_verify` never runs a command.
+
+For another computer, reconcile and stop the source worker, commit intended
+changes, and export `manager handoff --session <window-id> --task <task-id>
+--base origin/main --check <receipt>` as JSON to an ignored/external path. The
+receiver uses `workspace compare <bundle>` after an explicit Git fetch/checkout.
+Context alignment transfers no ownership: rerun local checks and acquire a local
+claim. Independent clones keep independent Managers; never copy tokens or logs.
+
 Report completed work and actual validation with `manager task finish --summary
 <result>`; use `task release` with a summary to requeue unfinished work. Both
 require `--session`, `--id` and `--claim`. Completion is self-reported and does

{coprogrammer-0.2.0a1 → coprogrammer-0.3.0a1}/src/coprogrammer/assets/templates/handoff.md

@@ -23,3 +23,11 @@ action. Include any files that need reconciliation before another worker edits.
 State whether the task was finished, released or still claimed, and whether
 message receipt is pending. A handoff does not transfer a lease; the recipient
 must sync and acquire their own task claim before editing.
+
+## Portable context (CoProgrammer 0.3+)
+
+Record `coprogrammer --version`, source HEAD/base, dirty state and content-bound
+check statuses. Export `manager handoff` as JSON to an ignored/external path;
+inspect it with `workspace compare` on the receiving machine. Confirm the source
+worker stopped, run receiving-machine checks and acquire a local claim.
+Context alignment does not transfer ownership between independent Managers.

{coprogrammer-0.2.0a1 → coprogrammer-0.3.0a1}/src/coprogrammer/cli.py

@@ -401,12 +401,17 @@ def utc_now() -> str:
 
 
 def run_git(args: list[str], cwd: Path) -> str:
+    # A caller's Git redirection must never move a requested project operation
+    # into another window's repository or index.
+    env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
+    env.update(GIT_OPTIONAL_LOCKS="0", GIT_TERMINAL_PROMPT="0")
     result = subprocess.run(
         ["git", *args],
         cwd=cwd,
         check=False,
         text=True,
         capture_output=True,
+        env=env,
     )
     if result.returncode != 0:
         raise RuntimeError(result.stderr.strip() or "git command failed")
@@ -1785,6 +1790,8 @@ def build_parser() -> argparse.ArgumentParser:
         description="Protocol tooling for semantic branch integration.",
     )
     subparsers = parser.add_subparsers(dest="command", required=True)
+    from . import __version__
+    parser.add_argument("--version", action="version", version=__version__)
 
     demo = subparsers.add_parser("demo", help="Run a real offline coordination demo in temporary Git worktrees.")
     demo.add_argument("--json", action="store_true")
@@ -1961,6 +1968,8 @@ def build_parser() -> argparse.ArgumentParser:
     add_parsers(manager_subparsers)
     from .scheduler_cli import add_parsers as add_task_parsers
     add_task_parsers(manager_subparsers)
+    from .workflow_cli import add_parsers as add_workflow_parsers
+    add_workflow_parsers(subparsers, manager_subparsers)
 
     briefing = manager_subparsers.add_parser("briefing", help="Summarize ready work, blockers and next actions.")
     briefing.add_argument("--cwd", default=".")

coprogrammer-0.3.0a1/src/coprogrammer/evidence.py

@@ -0,0 +1,161 @@
+"""Explicit local check receipts bound to working content and command hashes.
+
+Receipts are unauthenticated local evidence. Ignored files, external inputs and
+transient edits restored between observations are outside this boundary.
+"""
+from __future__ import annotations
+
+import json
+import os
+import platform
+import subprocess
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import __version__, collaboration as co, workspace as ws
+
+
+def environment() -> dict:
+    return {"tool_version": __version__, "python": platform.python_version(), "platform": sys.platform}
+
+
+def command_digest(command: list[str]) -> str:
+    if not isinstance(command, list) or not 1 <= len(command) <= 128:
+        raise RuntimeError("check requires an explicit command argument vector")
+    for arg in command:
+        co.text(arg, "command argument", 4096, empty=True)
+        if "\0" in arg:
+            raise RuntimeError("invalid command argument")
+    if not command[0].strip():
+        raise RuntimeError("command executable is required")
+    return ws.digest(command)
+
+
+def _destination(cwd: Path, path: Path, label: str) -> Path:
+    path = path.absolute()
+    if path.is_symlink():
+        raise RuntimeError("check output must not be a symlink")
+    if path.resolve().is_relative_to(cwd):
+        relative = path.resolve().relative_to(cwd).as_posix()
+        if (ws.git(cwd, "ls-files", "--", relative).strip()
+                or not ws.git(cwd, "check-ignore", "--no-index", "--", relative, optional=True).strip()):
+            raise RuntimeError("check output must be ignored by Git or outside the repository")
+    if path.exists():
+        previous = ws.read_artifact(path)
+        if previous.get("format") != "coprogrammer.check.v1" or previous.get("label") != label:
+            raise RuntimeError("refusing to overwrite a different artifact")
+    return path
+
+
+def run(cwd: Path, command: list[str], label: str, output: Path, timeout_seconds: int = 300) -> dict:
+    co.identity(label, "check label")
+    co.bounded(timeout_seconds, "timeout_seconds", 3600)
+    command_hash = command_digest(command)
+    cwd = ws.root(cwd)
+    output = _destination(cwd, output, label)
+    subject = ws.snapshot(cwd)
+    started_at = datetime.now(timezone.utc).isoformat()
+    exit_code, timed_out, error = None, False, None
+    try:
+        # No shell interpretation, interactive input, output/argv persistence,
+        # or provider invocation implicit in the recording operation.
+        exit_code = subprocess.run(command, cwd=cwd, stdin=subprocess.DEVNULL,
+                                   stdout=sys.stderr, stderr=sys.stderr, timeout=timeout_seconds,
+                                   check=False).returncode
+    except subprocess.TimeoutExpired:
+        timed_out = True
+        error = "command timed out; inspect any surviving child processes"
+    except OSError:
+        error = "command could not start"
+    after = None
+    try:
+        after = ws.snapshot(cwd)["content"]["sha256"]
+    except (RuntimeError, OSError):
+        error = error or "workspace unavailable after command"
+    record = {"format": "coprogrammer.check.v1", "label": label,
+              "command_sha256": command_hash, "started_at": started_at,
+              "finished_at": datetime.now(timezone.utc).isoformat(),
+              "exit_code": exit_code, "timed_out": timed_out, "error": error,
+              "subject": subject, "after_sha256": after,
+              "stable": after == subject["content"]["sha256"], "environment": environment()}
+    record["integrity_sha256"] = ws.digest(record)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    temporary = None
+    try:
+        with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=output.parent,
+                                         prefix=".coprogrammer-check-", delete=False) as handle:
+            temporary = Path(handle.name)
+            handle.write(json.dumps(record, ensure_ascii=False, indent=2, allow_nan=False) + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, output)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+    return record
+
+
+def validate(record: object) -> dict:
+    try:
+        fields = {"format", "label", "command_sha256", "started_at", "finished_at", "exit_code", "timed_out", "error", "subject", "after_sha256", "stable", "environment", "integrity_sha256"}
+        if not isinstance(record, dict) or set(record) != fields or record["format"] != "coprogrammer.check.v1":
+            raise ValueError
+        co.identity(record["label"], "check label")
+        ws.validate_snapshot(record["subject"])
+        if not ws.HASH.fullmatch(record["command_sha256"]) or not ws.HASH.fullmatch(record["integrity_sha256"]):
+            raise ValueError
+        if record["after_sha256"] is not None and not ws.HASH.fullmatch(record["after_sha256"]):
+            raise ValueError
+        if type(record["timed_out"]) is not bool or type(record["stable"]) is not bool:
+            raise ValueError
+        if record["exit_code"] is not None and (type(record["exit_code"]) is not int or not -2**31 <= record["exit_code"] < 2**31):
+            raise ValueError
+        if record["error"] is not None:
+            co.text(record["error"], "check error", 256)
+        if co.timestamp(record["finished_at"]) < co.timestamp(record["started_at"]):
+            raise ValueError
+        env = record["environment"]
+        if set(env) != {"tool_version", "python", "platform"}:
+            raise ValueError
+        for value in env.values():
+            co.text(value, "check environment", 64)
+        if record["stable"] != (record["after_sha256"] == record["subject"]["content"]["sha256"]):
+            raise ValueError
+        if record["integrity_sha256"] != ws.digest({k: v for k, v in record.items() if k != "integrity_sha256"}):
+            raise ValueError
+    except (ValueError, TypeError, KeyError, AttributeError, RuntimeError) as exc:
+        raise RuntimeError("invalid local check record or integrity mismatch") from exc
+    return record
+
+
+def verify(cwd: Path, path: Path, command: list[str] | None = None, *, current: dict | None = None,
+           max_age_seconds: int = 86400) -> dict:
+    co.bounded(max_age_seconds, "max_age_seconds", 604800)
+    record = validate(ws.read_artifact(path))
+    current = ws.snapshot(cwd) if current is None else current
+    reasons = []
+    age = (datetime.now(timezone.utc) - co.timestamp(record["finished_at"])).total_seconds()
+    if age < 0:
+        reasons.append("record_from_future")
+    elif age > max_age_seconds:
+        reasons.append("record_expired")
+    if record["exit_code"] != 0 or record["timed_out"] or record["error"]:
+        reasons.append("check_failed")
+    if not record["stable"]:
+        reasons.append("content_changed_during_check")
+    if record["subject"]["content"]["sha256"] != current["content"]["sha256"]:
+        reasons.append("content_changed")
+    if not ws.same_repository(record["subject"], current):
+        reasons.append("repository_changed")
+    if record["environment"] != environment():
+        reasons.append("environment_changed")
+    if command is not None and command_digest(command) != record["command_sha256"]:
+        reasons.append("command_changed")
+    return {"format": "coprogrammer.check-status.v1", "label": record["label"],
+            "fresh": not reasons, "reasons": reasons, "exit_code": record["exit_code"],
+            "finished_at": record["finished_at"], "command_sha256": record["command_sha256"],
+            "expected_command_checked": command is not None,
+            "content_sha256": record["subject"]["content"]["sha256"],
+            "note": "Unauthenticated local record; ignored files, dependencies and external inputs are not covered."}

{coprogrammer-0.2.0a1 → coprogrammer-0.3.0a1}/src/coprogrammer/manager_store.py

@@ -206,9 +206,9 @@ def transaction(path: Path, timeout: float = DEFAULT_LOCK_TIMEOUT) -> Iterator[E
     try:
         path.parent.mkdir(parents=True, exist_ok=True)
         with path.with_name(path.name + ".lock").open("a+b") as handle:
-            if os.name == "nt" and handle.tell() == 0:
-                handle.write(b"\0")
-                handle.flush()
+            # Windows permits locking beyond EOF. Bootstrap writes before the
+            # byte lock can conflict with another owner; keep even a new lock
+            # file empty and acquire ownership before accessing Manager state.
             _lock(handle, deadline)
             try:
                 current = EventTransaction(path)

{coprogrammer-0.2.0a1 → coprogrammer-0.3.0a1}/src/coprogrammer/mcp_server.py

@@ -30,6 +30,7 @@ from . import __version__
 from . import collaboration_mcp
 from . import scheduler_mcp
 from . import knowledge_mcp
+from . import workflow_mcp
 
 SUPPORTED_PROTOCOL_VERSIONS = (
     "2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25",
@@ -227,8 +228,10 @@ TOOLS: list[dict[str, Any]] = [
 
 TOOLS.extend(collaboration_mcp.declarations(string_schema))
 TOOLS.extend(scheduler_mcp.declarations(string_schema))
+TOOLS.extend(workflow_mcp.declarations(string_schema))
 READ_ONLY_TOOLS = {"digest_branch", "manager_status", "manager_briefing", "manager_forecast", "review_summary",
                    "manager_sync", "message_inbox", "manager_wait", "message_thread", "task_board", "task_guard"}
+READ_ONLY_TOOLS.update({"workspace_snapshot", "task_dispatch", "manager_handoff", "handoff_check", "check_verify"})
 for _tool in TOOLS:
     _tool["inputSchema"]["additionalProperties"] = False
     _tool["annotations"] = {
@@ -421,6 +424,10 @@ for _name in ("task_create", "task_claim", "task_renew", "task_finish", "task_re
     TOOL_HANDLERS[_name] = lambda ctx, args, name=_name: json.dumps(
         scheduler_mcp.dispatch(name, ctx, args), indent=2, ensure_ascii=False)
 
+for _name in ("workspace_snapshot", "task_dispatch", "manager_handoff", "handoff_check", "check_verify"):
+    TOOL_HANDLERS[_name] = lambda ctx, args, name=_name: json.dumps(
+        workflow_mcp.dispatch(name, ctx, args), indent=2, ensure_ascii=False)
+
 
 def validate_value(value: Any, schema: dict[str, Any], field: str = "arguments") -> None:
     """Validate the JSON Schema keywords used by this server's own tool schemas.

{coprogrammer-0.2.0a1 → coprogrammer-0.3.0a1}/src/coprogrammer/setup.py

@@ -28,14 +28,22 @@ def _target(root: Path, relative: str) -> Path:
     current = root
     for part in Path(relative).parts:
         current = current / part
-        if current.is_symlink() or current.resolve() != current:
+        try:
+            metadata = current.lstat()
+        except FileNotFoundError:
+            continue
+        # Resolving an existing Windows lock file may fail to open it and
+        # retain different path casing. Inspect non-following metadata instead;
+        # junctions and other reparse points remain blocked along with symlinks.
+        if (stat.S_ISLNK(metadata.st_mode)
+                or getattr(metadata, "st_file_attributes", 0)
+                & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)):
             raise RuntimeError(f"unsafe linked setup path: {relative}")
-        if current.exists():
-            mode = current.stat().st_mode
-            if current == target and not stat.S_ISREG(mode):
-                raise RuntimeError(f"setup target is not a regular file: {relative}")
-            if current != target and not stat.S_ISDIR(mode):
-                raise RuntimeError(f"setup parent is not a directory: {relative}")
+        mode = metadata.st_mode
+        if current == target and not stat.S_ISREG(mode):
+            raise RuntimeError(f"setup target is not a regular file: {relative}")
+        if current != target and not stat.S_ISDIR(mode):
+            raise RuntimeError(f"setup parent is not a directory: {relative}")
     return target