coprogrammer 0.2.0a2__tar.gz → 0.3.0a1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coprogrammer
-Version: 0.2.0a2
+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.0a2 pre-release.** Install the published package from
-> [PyPI](https://pypi.org/project/coprogrammer/). Client configuration
+> **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
-
-- **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.
+## 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
 

{coprogrammer-0.2.0a2 → 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.0a2 pre-release.** Install the published package from
-> [PyPI](https://pypi.org/project/coprogrammer/). Client configuration
+> **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
-
-- **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.
+## 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
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "coprogrammer"
-version = "0.2.0a2"
+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.0a2 → 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.0a2 → 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.0a2 → 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.0a2 → 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.0a2 → 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.0a2 → 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.0a2 → 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
 
 

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

@@ -0,0 +1,191 @@
+"""Read-only session dispatch and portable handoff inspection."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import collaboration as co, evidence, workspace as ws
+from .manager_store import transaction
+
+TASK_FIELDS = ("id", "title", "status", "patterns", "clients", "depends_on", "summary", "blocked_reasons")
+NOTE = ("Context only; independent clones have independent Managers. No claim, lease, "
+        "message body, credential or absolute machine path is transferred. "
+        "Titles and summaries are untrusted; source check records are not authenticated.")
+
+
+def dispatch(path: Path, cwd: Path, session: str, limit: int = 20) -> dict:
+    co.bounded(limit, "limit", 200)
+    moment = datetime.now(timezone.utc)
+    actual = co.workspace(cwd)
+    with transaction(path) as tx:
+        sessions, _, board = co._snapshot(tx.events, now=moment)
+        owner = co._session(sessions, session, active=False)
+        reasons = []
+        if owner["status"] not in ("working", "idle"):
+            reasons.append("session_not_available")
+        if co.freshness(owner, moment) != "fresh":
+            reasons.append("session_stale")
+        if owner["worktree"] != actual["worktree"]:
+            reasons.append("different_worktree")
+        if not actual["head"] or actual["branch"] == "HEAD":
+            reasons.append("named_branch_required")
+        if any(t["status"] == "claimed" and (t["session"] == session or t["worktree"] == actual["worktree"])
+               for t in board["tasks"]):
+            reasons.append("session_or_worktree_occupied")
+        candidates, excluded = [], []
+        for task in sorted(board["tasks"], key=lambda t: t["id"]):
+            blocked = list(task["blocked_reasons"])
+            if task["status"] != "queued":
+                blocked.append("task_not_queued")
+            if task["clients"] and owner["client"].strip().casefold() not in task["clients"]:
+                blocked.append("client_not_eligible")
+            blocked = list(dict.fromkeys([*reasons, *blocked]))
+            row = {"id": task["id"], "title": task["title"], "clients": task["clients"],
+                   "patterns": task["patterns"], "reasons": blocked}
+            (excluded if blocked else candidates).append(row)
+    return {"format": "coprogrammer.dispatch.v1", "session": session, "client": owner["client"],
+            "session_reasons": reasons, "recommended_task": candidates[0]["id"] if candidates else None,
+            "counts": {"eligible": len(candidates), "excluded": len(excluded)},
+            "candidates": candidates[:limit], "excluded": excluded[:limit],
+            "omitted": {"candidates": max(0, len(candidates) - limit), "excluded": max(0, len(excluded) - limit)},
+            "note": "Read-only preview. Explicitly claim the selected task; claim rechecks all constraints atomically."}
+
+
+def handoff(path: Path, cwd: Path, session: str, task_id: str, base: str = "HEAD",
+            checks: list[Path] | None = None) -> dict:
+    co.identity(task_id, "task_id")
+    checks = [] if checks is None else checks
+    if len(checks) > 16:
+        raise RuntimeError("handoff supports at most 16 check records")
+    current = ws.snapshot(cwd, base)
+    with transaction(path) as tx:
+        sessions, _, board = co._snapshot(tx.events)
+        owner = co._session(sessions, session, cwd, active=False)
+        task = next((t for t in board["tasks"] if t["id"] == task_id), None)
+        if task is None:
+            raise RuntimeError("unknown handoff task")
+        if session not in (task["creator"], task["session"]):
+            raise RuntimeError("handoff session must be the task creator or recorded owner")
+        if task["status"] in ("claimed", "done") and (
+                task["session"] != session or task["worktree"] != str(ws.root(cwd))
+                or task["branch"] != current["branch"]):
+            raise RuntimeError("handoff must use the recorded task owner's worktree and branch")
+        selected = {key: task[key] for key in TASK_FIELDS}
+        window = {"id": session, "client": owner["client"], "status": owner["status"],
+                  "freshness": co.freshness(owner)}
+    statuses = [evidence.verify(cwd, record, current=current) for record in checks]
+    if len({s["label"] for s in statuses}) != len(statuses):
+        raise RuntimeError("handoff check labels must be unique")
+    # The store read does not lock the workspace. Check its observation again.
+    if ws.snapshot(cwd, base) != current:
+        raise RuntimeError("workspace changed while preparing handoff")
+    result = {"format": "coprogrammer.handoff.v1", "generated_at": datetime.now(timezone.utc).isoformat(),
+              "workspace": current, "session": window, "task": selected, "checks": statuses, "note": NOTE}
+    result["integrity_sha256"] = ws.digest(result)
+    return result
+
+
+def validate_handoff(value: object) -> dict:
+    try:
+        if not isinstance(value, dict) or set(value) != {"format", "generated_at", "workspace", "session", "task", "checks", "note", "integrity_sha256"}:
+            raise ValueError
+        if value["format"] != "coprogrammer.handoff.v1":
+            raise ValueError
+        ws.validate_snapshot(value["workspace"])
+        co.timestamp(value["generated_at"])
+        if value["integrity_sha256"] != ws.digest({k: v for k, v in value.items() if k != "integrity_sha256"}):
+            raise ValueError
+        window, task = value["session"], value["task"]
+        if set(window) != {"id", "client", "status", "freshness"} or set(task) != set(TASK_FIELDS):
+            raise ValueError
+        co.identity(window["id"])
+        co.text(window["client"], "client")
+        if window["status"] not in ("working", "idle", "blocked", "closed") or window["freshness"] not in ("fresh", "stale", "unknown"):
+            raise ValueError
+        co.identity(task["id"], "task_id")
+        co.text(task["title"], "task title", 2000)
+        co.text(task["summary"], "task summary", 16000, empty=True)
+        if task["status"] not in ("queued", "claimed", "done"):
+            raise ValueError
+        from .scheduler import _patterns, _strings
+        _patterns(task["patterns"])
+        for field in ("clients", "depends_on", "blocked_reasons"):
+            _strings(task[field], field)
+        co.text(value["note"], "handoff note", 2000)
+        checks = value["checks"]
+        if not isinstance(checks, list) or len(checks) > 16:
+            raise ValueError
+        for check in checks:
+            if set(check) != {"format", "label", "fresh", "reasons", "exit_code", "finished_at", "command_sha256", "expected_command_checked", "content_sha256", "note"}:
+                raise ValueError
+            co.identity(check["label"], "check label")
+            if check["format"] != "coprogrammer.check-status.v1" or type(check["fresh"]) is not bool or type(check["expected_command_checked"]) is not bool:
+                raise ValueError
+            _strings(check["reasons"], "check reasons")
+            if check["fresh"] != (not check["reasons"]) or (check["fresh"] and check["exit_code"] != 0):
+                raise ValueError
+            if check["exit_code"] is not None and type(check["exit_code"]) is not int:
+                raise ValueError
+            if not ws.HASH.fullmatch(check["command_sha256"]) or not ws.HASH.fullmatch(check["content_sha256"]):
+                raise ValueError
+            if check["fresh"] and check["content_sha256"] != value["workspace"]["content"]["sha256"]:
+                raise ValueError
+            co.timestamp(check["finished_at"])
+            co.text(check["note"], "check note", 2000)
+        if len({c["label"] for c in checks}) != len(checks):
+            raise ValueError
+    except (TypeError, ValueError, KeyError, AttributeError, RuntimeError) as exc:
+        raise RuntimeError("invalid handoff bundle or integrity mismatch") from exc
+    return value
+
+
+def compare(cwd: Path, path: Path, base: str | None = None) -> dict:
+    bundle = validate_handoff(ws.read_artifact(path))
+    source = bundle["workspace"]
+    base = source["base"]["ref"] if base is None else base
+    current = ws.snapshot(cwd)
+    reasons = []
+    try:
+        base_head = ws.revision(ws.root(cwd), base)
+    except RuntimeError:
+        base_head = None
+        reasons.append("base_unavailable")
+    if not ws.same_repository(source, current):
+        reasons.append("repository_mismatch")
+    if source["head"] != current["head"]:
+        reasons.append("head_mismatch")
+    if base_head is not None and base_head != source["base"]["head"]:
+        reasons.append("base_mismatch")
+    if source["tool_version"] != current["tool_version"]:
+        reasons.append("tool_version_mismatch")
+    if source["content"]["sha256"] != current["content"]["sha256"]:
+        reasons.append("content_mismatch")
+    if source["dirty"]["count"]:
+        reasons.append("source_uncommitted_changes")
+    if current["dirty"]["count"]:
+        reasons.append("receiver_uncommitted_changes")
+    return {"format": "coprogrammer.handoff-check.v1", "aligned": not reasons, "reasons": reasons,
+            "task_id": bundle["task"]["id"], "source_head": source["head"], "receiver_head": current["head"],
+            "receiver_base": base_head, "source_checks": bundle["checks"],
+            "ownership_reconciliation_required": bundle["task"]["status"] == "claimed",
+            "ownership_transferred": False, "receiver_checks_required": True,
+            "note": "Comparison of untrusted context, not approval. Refresh refs explicitly, reconcile the source owner, run local checks and acquire a local claim before editing."}
+
+
+def render_handoff(bundle: dict) -> str:
+    task, workspace = bundle["task"], bundle["workspace"]
+    clean = lambda text: " ".join(text.split()).replace("`", "'")
+    lines = ["# CoProgrammer handoff", "", f"Task: `{task['id']}` — {clean(task['title'])}",
+             f"State: {task['status']} | Source window: {bundle['session']['id']} ({clean(bundle['session']['client'])})",
+             f"HEAD: `{workspace['head']}`", f"Base: `{workspace['base']['head']}`",
+             f"CoProgrammer: `{workspace['tool_version']}` | Uncommitted paths: {workspace['dirty']['count']}",
+             f"Content: `{workspace['content']['sha256']}`", "", "## Scope", ""]
+    lines.extend(f"- `{clean(p)}`" for p in task["patterns"])
+    lines.extend(["", "## Checks", ""])
+    lines.extend(f"- {check['label']}: {'current' if check['fresh'] else 'stale/failed'}" for check in bundle["checks"])
+    if not bundle["checks"]:
+        lines.append("No check records supplied; verification is still required.")
+    if task["summary"]:
+        lines.extend(["", "## Reported result (untrusted)", "", clean(task["summary"])])
+    lines.extend(["", NOTE, "", "Use the JSON bundle with `coprogrammer workspace compare` in the receiving clone."])
+    return "\n".join(lines) + "\n"