@hunter-harness/workflow-harness 0.2.42 → 0.2.44

package/harness/bundles/java/claude-code/scripts/harness_runtime.py

@@ -4,7 +4,9 @@
 from __future__ import annotations
 
 import argparse
+import contextlib
 import datetime as dt
+import hashlib
 import json
 import os
 import re
@@ -12,16 +14,31 @@ import shutil
 import subprocess
 import sys
 import tempfile
+import threading
+import time
+import uuid
 from pathlib import Path
 from typing import Any, Callable
 
+SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
 if hasattr(sys.stdout, "reconfigure"):
     sys.stdout.reconfigure(encoding="utf-8")
 if hasattr(sys.stderr, "reconfigure"):
     sys.stderr.reconfigure(encoding="utf-8")
 
 SCHEMA_VERSION = 1
+RUN_SESSION_SCHEMA_VERSION = 1
+RUN_TERMINAL_STATUSES = {"OK", "FAIL", "INCOMPLETE", "CANCELLED"}
 _CHANGE_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+SECRET_SCAN_RULES_VERSION = "secret-scan-v1"
+SECRET_SCAN_RECEIPT_REL = Path("meta") / "secret-scan-receipt.json"
+_SENSITIVE_ASSIGNMENT = re.compile(
+    rb"(?i)[\"']?(?:password|passwd|token|secret|cookie|authorization|database[_-]?url)"
+    rb"[\"']?\s*[:=]\s*[\"']?[^\s\"']{4,}"
+)
 _ADAPTERS = {
     "claude-code": (".worktrees", "harness/"),
     "codex": (".worktrees", "harness/"),
@@ -34,6 +51,40 @@ def now_iso() -> str:
     return dt.datetime.now().astimezone().isoformat(timespec="milliseconds")
 
 
+def _stage_transition(receipt: dict[str, Any], next_stage: str) -> None:
+    ended_at = now_iso()
+    started_at = str(receipt.get("stageStartedAt") or ended_at)
+    try:
+        started = dt.datetime.fromisoformat(started_at.replace("Z", "+00:00"))
+        ended = dt.datetime.fromisoformat(ended_at.replace("Z", "+00:00"))
+        wall_ms = max(0, int((ended - started).total_seconds() * 1000))
+    except ValueError:
+        wall_ms = 0
+    stage = str(receipt.get("stage") or "unknown")
+    timings = receipt.setdefault("stageTimings", [])
+    if isinstance(timings, list):
+        timings.append(
+            {
+                "stage": stage,
+                "createdAt": started_at,
+                "endedAt": ended_at,
+                "wallClockMs": wall_ms,
+                "activeTimeMs": 0 if stage == "resource-wait" else wall_ms,
+                "resourceWaitMs": wall_ms if stage == "resource-wait" else 0,
+            }
+        )
+    receipt["stage"] = next_stage
+    receipt["stageStartedAt"] = ended_at
+
+
+def _close_current_stage(receipt: dict[str, Any]) -> None:
+    current = str(receipt.get("stage") or "record")
+    _stage_transition(receipt, current)
+    timings = receipt.get("stageTimings")
+    if isinstance(timings, list) and timings:
+        receipt["stageStartedAt"] = timings[-1].get("endedAt")
+
+
 def atomic_write_json(path: Path, payload: dict[str, Any]) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     text = json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
@@ -46,11 +97,1472 @@ def atomic_write_json(path: Path, payload: dict[str, Any]) -> None:
             handle.write(text)
             handle.flush()
             os.fsync(handle.fileno())
-        os.replace(tmp, path)
+        # Windows can transiently deny replacement while another process has
+        # just finished reading the receipt.  Keep the atomic replace contract,
+        # but retry the sharing violation within a small bounded window.
+        for attempt in range(20):
+            try:
+                os.replace(tmp, path)
+                break
+            except PermissionError:
+                if attempt == 19:
+                    raise
+                time.sleep(0.01 * (attempt + 1))
     finally:
         tmp.unlink(missing_ok=True)
 
 
+def _sha256_json(value: Any) -> str:
+    encoded = json.dumps(
+        value,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return "sha256:" + hashlib.sha256(encoded).hexdigest()
+
+
+def _publishable_tree_digest(root: Path) -> str:
+    """Hash publishable bytes while excluding the self-referential scan receipt."""
+    root = root.expanduser().resolve()
+    digest = hashlib.sha256()
+    receipt = (root / SECRET_SCAN_RECEIPT_REL).resolve()
+    if not root.is_dir():
+        raise OSError(f"publishable evidence root not found: {root}")
+    for path in sorted(root.rglob("*")):
+        if not path.is_file() or path.resolve() == receipt:
+            continue
+        relative = path.relative_to(root).as_posix()
+        data = path.read_bytes()
+        digest.update(relative.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(str(len(data)).encode("ascii"))
+        digest.update(b"\0")
+        digest.update(hashlib.sha256(data).digest())
+        digest.update(b"\0")
+    return "sha256:" + digest.hexdigest()
+
+
+def _sensitive_evidence_receipt_path(change_root: Path) -> Path:
+    return change_root.expanduser().resolve() / SECRET_SCAN_RECEIPT_REL
+
+
+def _private_evidence_root(explicit: Path | None = None) -> Path:
+    configured = os.environ.get("HARNESS_PRIVATE_EVIDENCE_ROOT")
+    return (explicit if explicit is not None else Path(configured) if configured else
+            Path.home() / ".harness" / "private-evidence").expanduser().resolve()
+
+
+def _secure_private_path(path: Path, *, directory: bool) -> str:
+    """Best-effort owner-only permissions, with an explicit ACL result on Windows."""
+    mode = 0o700 if directory else 0o600
+    try:
+        path.chmod(mode)
+    except OSError:
+        pass
+    if os.name != "nt":
+        return "POSIX_OWNER_ONLY"
+    try:
+        account = os.environ.get("USERNAME") or os.environ.get("USER")
+        if not account:
+            account = subprocess.check_output(
+                ["whoami"], stderr=subprocess.DEVNULL, text=True, encoding="utf-8"
+            ).strip()
+        result = subprocess.run(
+            ["icacls", str(path), "/inheritance:r", "/grant:r", f"{account}:F"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+            timeout=10,
+        )
+        return "WINDOWS_CURRENT_USER_ONLY" if result.returncode == 0 else "WINDOWS_ACL_UNVERIFIED"
+    except (OSError, subprocess.SubprocessError):
+        return "WINDOWS_ACL_UNVERIFIED"
+
+
+def _sensitive_candidates(root: Path) -> list[dict[str, Any]]:
+    """Find high-confidence plaintext assignments without treating prose as a secret."""
+    receipt = _sensitive_evidence_receipt_path(root)
+    candidates: list[dict[str, Any]] = []
+    for path in sorted(root.rglob("*")):
+        if not path.is_file() or path.resolve() == receipt.resolve():
+            continue
+        try:
+            raw = path.read_bytes()
+        except OSError:
+            continue
+        match = _SENSITIVE_ASSIGNMENT.search(raw)
+        if match is None:
+            continue
+        candidates.append({
+            "path": path.relative_to(root).as_posix(),
+            "reasonCode": "PLAINTEXT_SENSITIVE_ASSIGNMENT",
+            "digest": "sha256:" + hashlib.sha256(raw).hexdigest(),
+        })
+    return candidates
+
+
+def publishable_tree_digest(root: Path) -> str:
+    """Public digest helper shared by the archive publication gate."""
+    return _publishable_tree_digest(root)
+
+
+def sensitive_evidence_receipt_path(change_root: Path) -> Path:
+    return _sensitive_evidence_receipt_path(change_root)
+
+
+def sensitive_evidence_candidates(root: Path) -> list[dict[str, Any]]:
+    return _sensitive_candidates(root)
+
+
+def _write_sensitive_scan_receipt(
+    change_root: Path,
+    *,
+    entries: list[dict[str, Any]],
+    unresolved: list[dict[str, Any]],
+    status: str,
+) -> dict[str, Any]:
+    change_root = change_root.expanduser().resolve()
+    receipt = {
+        "schemaVersion": 1,
+        "rulesVersion": SECRET_SCAN_RULES_VERSION,
+        "changeId": change_root.name,
+        "status": status,
+        "unresolvedFailures": unresolved,
+        "entries": entries,
+        "publishableTreeDigest": _publishable_tree_digest(change_root),
+        "publicationExcluded": True,
+        "recordedAt": now_iso(),
+    }
+    atomic_write_json(_sensitive_evidence_receipt_path(change_root), receipt)
+    return receipt
+
+
+def quarantine_sensitive_evidence(
+    source: Path,
+    *,
+    change_root: Path,
+    reason: str = "sensitive evidence",
+    private_root: Path | None = None,
+) -> dict[str, Any]:
+    """Atomically move legacy plaintext evidence outside any publishable tree."""
+    source = source.expanduser().resolve()
+    change_root = change_root.expanduser().resolve()
+    private = _private_evidence_root(private_root)
+    if not source.is_file():
+        return {"ok": False, "reasonCode": "SENSITIVE_EVIDENCE_SOURCE_MISSING", "sourcePath": str(source)}
+    if private == change_root or private.is_relative_to(change_root):
+        return {
+            "ok": False,
+            "reasonCode": "SENSITIVE_EVIDENCE_QUARANTINE_FAILED",
+            "error": "private quarantine root must be outside the publishable change root",
+        }
+    try:
+        raw_digest = "sha256:" + hashlib.sha256(source.read_bytes()).hexdigest()
+        quarantine_dir = private / uuid.uuid4().hex
+        quarantine_dir.mkdir(parents=True, exist_ok=False)
+        acl_dir = _secure_private_path(quarantine_dir, directory=True)
+        target = quarantine_dir / "payload.bin"
+        os.replace(source, target)
+        acl_file = _secure_private_path(target, directory=False)
+        if os.name == "nt" and (
+            acl_dir != "WINDOWS_CURRENT_USER_ONLY"
+            or acl_file != "WINDOWS_CURRENT_USER_ONLY"
+        ):
+            os.replace(target, source)
+            shutil.rmtree(quarantine_dir, ignore_errors=True)
+            return {
+                "ok": False,
+                "reasonCode": "SENSITIVE_EVIDENCE_QUARANTINE_FAILED",
+                "error": "private quarantine ACL could not be restricted to the current user",
+            }
+        moved_digest = "sha256:" + hashlib.sha256(target.read_bytes()).hexdigest()
+        if moved_digest != raw_digest:
+            os.replace(target, source)
+            shutil.rmtree(quarantine_dir, ignore_errors=True)
+            return {
+                "ok": False,
+                "reasonCode": "SENSITIVE_EVIDENCE_QUARANTINE_FAILED",
+                "error": "quarantine digest verification failed",
+            }
+        try:
+            prior = json.loads(
+                _sensitive_evidence_receipt_path(change_root).read_text(
+                    encoding="utf-8-sig"
+                )
+            )
+        except (OSError, json.JSONDecodeError):
+            prior = {}
+        entries = list(prior.get("entries") or []) if isinstance(prior, dict) else []
+        entries.append({
+            "sourcePath": (
+                source.relative_to(change_root).as_posix()
+                if source.is_relative_to(change_root)
+                else source.name
+            ),
+            "sourceDigest": raw_digest,
+            "privatePath": str(target),
+            "reason": reason[:160],
+            "status": "QUARANTINED",
+            "acl": {"directory": acl_dir, "file": acl_file},
+            "movedAt": now_iso(),
+        })
+        try:
+            receipt = _write_sensitive_scan_receipt(
+                change_root,
+                entries=entries,
+                unresolved=[],
+                status="QUARANTINED",
+            )
+        except BaseException as exc:
+            try:
+                os.replace(target, source)
+            except OSError:
+                pass
+            shutil.rmtree(quarantine_dir, ignore_errors=True)
+            return {
+                "ok": False,
+                "reasonCode": "SENSITIVE_EVIDENCE_QUARANTINE_FAILED",
+                "error": str(exc),
+            }
+        return {
+            "ok": True,
+            "reasonCode": "SENSITIVE_EVIDENCE_QUARANTINED",
+            "sourceDigest": raw_digest,
+            "privatePath": str(target),
+            "receiptPath": str(_sensitive_evidence_receipt_path(change_root)),
+            "receipt": receipt,
+        }
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        # No copy is retained on failure.  If os.replace crossed filesystems it
+        # fails before removing the source, which is the required fail-closed path.
+        return {
+            "ok": False,
+            "reasonCode": "SENSITIVE_EVIDENCE_QUARANTINE_FAILED",
+            "error": str(exc),
+        }
+
+
+def ensure_sensitive_evidence_scan_receipt(change_root: Path) -> dict[str, Any]:
+    """Create a digest-bound scan receipt for a tree with no plaintext findings."""
+    change_root = change_root.expanduser().resolve()
+    unresolved = _sensitive_candidates(change_root)
+    if unresolved:
+        return _write_sensitive_scan_receipt(
+            change_root,
+            entries=[],
+            unresolved=unresolved,
+            status="FAIL",
+        )
+    return _write_sensitive_scan_receipt(
+        change_root,
+        entries=[],
+        unresolved=[],
+        status="OK",
+    )
+
+
+def _run_sessions_root(state_root: Path) -> Path:
+    return state_root.expanduser().resolve() / "runtime" / "run-sessions"
+
+
+def _run_session_root(state_root: Path, session_id: str) -> Path:
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}", session_id):
+        raise ValueError(f"RUN_SESSION_ID_INVALID: {session_id}")
+    return _run_sessions_root(state_root) / session_id
+
+
+def _run_receipt_path(state_root: Path, session_id: str) -> Path:
+    return _run_session_root(state_root, session_id) / "session.json"
+
+
+def _resource_lock_secrets_path(state_root: Path, session_id: str) -> Path:
+    return _run_session_root(state_root, session_id) / "resource-lock-secrets.json"
+
+
+def _load_run_receipt(state_root: Path, session_id: str) -> dict[str, Any]:
+    path = _run_receipt_path(state_root, session_id)
+    last_error: OSError | None = None
+    for attempt in range(20):
+        try:
+            value = json.loads(path.read_text(encoding="utf-8-sig"))
+            break
+        except FileNotFoundError as exc:
+            raise ValueError(f"RUN_SESSION_NOT_FOUND: {session_id}") from exc
+        except PermissionError as exc:
+            last_error = exc
+            if attempt == 19:
+                raise ValueError(
+                    f"RUN_SESSION_RECEIPT_BUSY: {session_id}"
+                ) from exc
+            time.sleep(0.01 * (attempt + 1))
+    else:
+        raise ValueError(f"RUN_SESSION_RECEIPT_BUSY: {session_id}") from last_error
+    if not isinstance(value, dict):
+        raise ValueError(f"RUN_SESSION_CORRUPT: {session_id}")
+    return value
+
+
+def _load_resource_lock_tokens(
+    state_root: Path,
+    session_id: str,
+    receipt: dict[str, Any],
+) -> dict[str, str]:
+    """Load lock tokens from a private sidecar; legacy receipts may inline them."""
+    path = _resource_lock_secrets_path(state_root, session_id)
+    try:
+        value = json.loads(path.read_text(encoding="utf-8-sig"))
+        if isinstance(value, dict) and isinstance(value.get("tokens"), dict):
+            return {
+                str(name): str(token)
+                for name, token in value["tokens"].items()
+                if isinstance(name, str) and isinstance(token, str)
+            }
+    except (OSError, json.JSONDecodeError, TypeError):
+        pass
+    legacy = receipt.get("resourceLockTokens")
+    if isinstance(legacy, dict):
+        return {
+            str(name): str(token)
+            for name, token in legacy.items()
+            if isinstance(name, str) and isinstance(token, str)
+        }
+    return {}
+
+
+def _receipt_identity_state(
+    receipt: dict[str, Any],
+    *,
+    field: str = "workerIdentity",
+) -> bool | None:
+    """Verify a canonical provider attestation, with legacy facade fallback."""
+    identity = receipt.get(field)
+    pid = identity.get("pid") if isinstance(identity, dict) else receipt.get("workerPid")
+    if isinstance(identity, dict) and {
+        "schemaVersion",
+        "createdAt",
+        "fieldProvenance",
+        "capabilities",
+    } <= set(identity):
+        from harness_process import observe_process_identity, verify_process_identity
+
+        observed = observe_process_identity(pid)
+        decision = verify_process_identity(identity, observed)
+        if decision.get("ok") is True:
+            return True
+        if decision.get("reasonCode") == "IDENTITY_UNVERIFIABLE":
+            return None
+        return False
+    from harness_service import verify_process_identity
+
+    legacy = {
+        "pid": pid,
+        "startedAt": (
+            identity.get("startedAt")
+            if isinstance(identity, dict)
+            else None
+        ),
+        "processIdentity": {
+            "executable": (
+                identity.get("executable")
+                if isinstance(identity, dict)
+                else None
+            )
+        },
+    }
+    return verify_process_identity(legacy)
+
+
+def _capture_provider_members(spawned: Any) -> None:
+    """Persist current provider-owned members before a later cleanup."""
+    proof = getattr(spawned, "ownershipProof", None)
+    leader = getattr(spawned, "attestation", None)
+    if not isinstance(proof, dict) or not isinstance(leader, dict):
+        return
+    from harness_process import capture_owned_members
+
+    capture_owned_members(spawned)
+
+
+def _resource_lock_root() -> Path:
+    return Path(
+        os.environ.get(
+            "HARNESS_RESOURCE_LOCK_ROOT",
+            str(Path(tempfile.gettempdir()) / "hunter-harness-resource-locks"),
+        )
+    ).expanduser().resolve()
+
+
+def _resource_lock_path(_state_root: Path, lock_name: str) -> Path:
+    digest = hashlib.sha256(lock_name.encode("utf-8")).hexdigest()
+    return _resource_lock_root() / f"{digest}.json"
+
+
+def _lock_owner_identity(owner: Any) -> bool | None:
+    if not isinstance(owner, dict):
+        return None
+    pid = owner.get("pid")
+    started_at = owner.get("startedAt")
+    executable = owner.get("executable")
+    if (
+        not isinstance(pid, int)
+        or pid <= 0
+        or not isinstance(started_at, str)
+        or not started_at
+        or not isinstance(executable, str)
+        or not executable
+    ):
+        return None
+    from harness_service import verify_process_identity
+
+    return verify_process_identity(
+        {
+            "pid": pid,
+            "startedAt": started_at,
+            "processIdentity": {"executable": executable},
+        }
+    )
+
+
+def _valid_resource_lock_record(
+    record: Any,
+    *,
+    lock_name: str,
+) -> bool:
+    return bool(
+        isinstance(record, dict)
+        and record.get("schemaVersion") == 2
+        and record.get("lockName") == lock_name
+        and isinstance(record.get("sessionId"), str)
+        and record.get("sessionId")
+        and isinstance(record.get("token"), str)
+        and record.get("token")
+        and isinstance(record.get("heartbeatAtUnix"), (int, float))
+        and isinstance(record.get("expiresAtUnix"), (int, float))
+        and _lock_owner_identity(record.get("owner")) is not None
+    )
+
+
+def _write_resource_lock(
+    path: Path,
+    *,
+    lock_name: str,
+    session_id: str,
+    token: str,
+    owner: dict[str, Any],
+    acquired_at: str,
+) -> None:
+    now = time.time()
+    atomic_write_json(
+        path,
+        {
+            "schemaVersion": 2,
+            "lockName": lock_name,
+            "sessionId": session_id,
+            "token": token,
+            "acquiredAt": acquired_at,
+            "heartbeatAtUnix": now,
+            "expiresAtUnix": now + 300.0,
+            "owner": owner,
+        },
+    )
+
+
+def _refresh_resource_locks(
+    state_root: Path,
+    session_id: str,
+    tokens: dict[str, str],
+    owner: dict[str, Any],
+) -> bool:
+    refreshed = True
+    for lock_name, token in sorted(tokens.items()):
+        path = _resource_lock_path(state_root, lock_name)
+        try:
+            record = json.loads(path.read_text(encoding="utf-8-sig"))
+        except (OSError, json.JSONDecodeError):
+            refreshed = False
+            continue
+        if (
+            not _valid_resource_lock_record(record, lock_name=lock_name)
+            or record.get("sessionId") != session_id
+            or record.get("token") != token
+        ):
+            refreshed = False
+            continue
+        _write_resource_lock(
+            path,
+            lock_name=lock_name,
+            session_id=session_id,
+            token=token,
+            owner=owner,
+            acquired_at=str(record["acquiredAt"]),
+        )
+    return refreshed
+
+
+def _release_resource_locks(
+    state_root: Path,
+    session_id: str,
+    tokens: dict[str, str],
+) -> bool:
+    released = True
+    for lock_name, token in sorted(tokens.items()):
+        path = _resource_lock_path(state_root, lock_name)
+        try:
+            record = json.loads(path.read_text(encoding="utf-8-sig"))
+        except FileNotFoundError:
+            continue
+        except (OSError, json.JSONDecodeError):
+            released = False
+            continue
+        if (
+            not isinstance(record, dict)
+            or record.get("sessionId") != session_id
+            or record.get("token") != token
+        ):
+            released = False
+            continue
+        try:
+            path.unlink()
+        except OSError:
+            released = False
+    return released
+
+
+def _acquire_resource_locks(
+    state_root: Path,
+    session_id: str,
+    lock_names: list[str],
+) -> tuple[dict[str, str], dict[str, Any] | None]:
+    tokens: dict[str, str] = {}
+    for lock_name in lock_names:
+        path = _resource_lock_path(state_root, lock_name)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        token = uuid.uuid4().hex
+        owner_identity = _process_identity(os.getpid(), sys.executable)
+        now = time.time()
+        record = {
+            "schemaVersion": 2,
+            "lockName": lock_name,
+            "sessionId": session_id,
+            "token": token,
+            "acquiredAt": now_iso(),
+            "heartbeatAtUnix": now,
+            "expiresAtUnix": now + 300.0,
+            "owner": owner_identity,
+        }
+        encoded = (
+            json.dumps(record, ensure_ascii=False, indent=2) + "\n"
+        ).encode("utf-8")
+        for attempt in range(2):
+            try:
+                fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            except FileExistsError:
+                owner: dict[str, Any] | None = None
+                try:
+                    loaded = json.loads(path.read_text(encoding="utf-8-sig"))
+                    owner = loaded if isinstance(loaded, dict) else None
+                except (OSError, json.JSONDecodeError):
+                    owner = None
+                reclaimable = bool(
+                    _valid_resource_lock_record(owner, lock_name=lock_name)
+                    and _lock_owner_identity(owner.get("owner")) is False
+                )
+                if reclaimable and attempt == 0:
+                    try:
+                        current = json.loads(path.read_text(encoding="utf-8-sig"))
+                        if current.get("token") == owner.get("token"):
+                            path.unlink()
+                            continue
+                    except (OSError, json.JSONDecodeError):
+                        pass
+                _release_resource_locks(state_root, session_id, tokens)
+                return {}, {
+                    "lockName": lock_name,
+                    "ownerSessionId": (
+                        owner.get("sessionId") if owner is not None else None
+                    ),
+                    "lockRecordValid": bool(
+                        _valid_resource_lock_record(owner, lock_name=lock_name)
+                    ),
+                    "ownerIdentity": (
+                        _lock_owner_identity(owner.get("owner"))
+                        if owner is not None
+                        else None
+                    ),
+                }
+            else:
+                break
+        else:
+            raise RuntimeError("RESOURCE_LOCK_ACQUIRE_RETRY_EXHAUSTED")
+        try:
+            with os.fdopen(fd, "wb") as handle:
+                handle.write(encoded)
+                handle.flush()
+                os.fsync(handle.fileno())
+        except BaseException:
+            path.unlink(missing_ok=True)
+            _release_resource_locks(state_root, session_id, tokens)
+            raise
+        tokens[lock_name] = token
+    return tokens, None
+
+
+def _write_run_receipt(state_root: Path, receipt: dict[str, Any]) -> None:
+    _update_receipt_contract(receipt)
+    publishable = json.loads(json.dumps(receipt, ensure_ascii=False))
+    raw_tokens = publishable.pop("resourceLockTokens", {})
+    if isinstance(raw_tokens, dict):
+        publishable["resourceLockTokenHashes"] = {
+            str(name): _sha256_json(str(token))
+            for name, token in raw_tokens.items()
+            if isinstance(name, str) and isinstance(token, str)
+        }
+    atomic_write_json(
+        _run_receipt_path(state_root, str(receipt["sessionId"])),
+        publishable,
+    )
+
+
+def _process_identity(pid: int, executable_hint: str) -> dict[str, Any]:
+    from harness_process import observe_process_identity
+
+    observed = observe_process_identity(pid)
+    if not observed.get("executable"):
+        observed["executable"] = _absolute_executable(executable_hint)
+        observed["fieldProvenance"]["executable"] = "ATTESTED"
+    if not observed.get("createdAt"):
+        observed["createdAt"] = now_iso()
+        observed["fieldProvenance"]["createdAt"] = "ATTESTED"
+    # ``startedAt`` is a compatibility alias used by legacy session readers;
+    # canonical identity comparisons use ``createdAt`` and provenance.
+    observed["startedAt"] = observed.get("createdAt")
+    return observed
+
+
+def _log_contract(path: Path) -> dict[str, Any]:
+    raw = b""
+    if path.is_file():
+        try:
+            raw = path.read_bytes()
+        except OSError:
+            raw = b""
+    try:
+        raw.decode("utf-8")
+        decode_status = "OK"
+    except UnicodeDecodeError:
+        decode_status = "LOG_DECODE_DEGRADED"
+    return {
+        "cursor": len(raw),
+        "rawDigest": "sha256:" + hashlib.sha256(raw).hexdigest(),
+        "decodeStatus": decode_status,
+    }
+
+
+def _update_receipt_contract(receipt: dict[str, Any]) -> None:
+    worker = receipt.get("workerIdentity")
+    writer_source = worker if isinstance(worker, dict) else {
+        "pid": receipt.get("workerPid") or receipt.get("launcherPid")
+    }
+    heartbeat_kind = "WORKER" if isinstance(worker, dict) else "SUPERVISOR"
+    receipt["heartbeat"] = {
+        "kind": heartbeat_kind,
+        "writerIdentity": _sha256_json(writer_source),
+        "lastSeenAt": str(receipt.get("lastHeartbeatAt") or now_iso()),
+        "ttlSeconds": max(1, int(float(receipt.get("heartbeatSeconds") or 30))),
+        "staleReason": (
+            "SERVICE_HEARTBEAT_STALE"
+            if receipt.get("reasonCode") == "HEARTBEAT_LOST"
+            else None
+        ),
+    }
+    receipt["logs"] = {
+        "stdout": _log_contract(Path(str(receipt.get("stdoutPath") or ""))),
+        "stderr": _log_contract(Path(str(receipt.get("stderrPath") or ""))),
+    }
+    cleanup_status = str(receipt.get("cleanupStatus") or "")
+    complete = cleanup_status in {
+        "NO_CHILD",
+        "PROCESS_EXITED",
+        "PROCESS_TREE_TERMINATED",
+    }
+    receipt["cleanup"] = {
+        "complete": complete,
+        "reasonCode": None if complete else receipt.get("reasonCode"),
+    }
+
+
+def _spawn_detached_worker(
+    argv: list[str],
+    *,
+    cwd: Path,
+    env: dict[str, str],
+    output: Any = subprocess.DEVNULL,
+) -> subprocess.Popen[bytes]:
+    kwargs: dict[str, Any] = {
+        "cwd": str(cwd),
+        "env": env,
+        "stdin": subprocess.DEVNULL,
+        "stdout": output,
+        "stderr": output,
+        "close_fds": True,
+    }
+    if os.name == "nt":
+        detached = 0x00000008
+        new_group = 0x00000200
+        no_window = 0x08000000
+        breakaway = 0x01000000
+        try:
+            return subprocess.Popen(
+                argv,
+                creationflags=detached | new_group | no_window | breakaway,
+                **kwargs,
+            )
+        except OSError:
+            return subprocess.Popen(
+                argv,
+                creationflags=detached | new_group | no_window,
+                **kwargs,
+            )
+    return subprocess.Popen(argv, start_new_session=True, **kwargs)
+
+
+def start_run_session(
+    *,
+    state_root: Path,
+    verification: str,
+    argv: list[str],
+    working_directory: Path,
+    environment: dict[str, str] | None = None,
+    timeout_seconds: float | None = None,
+    heartbeat_seconds: float = 30.0,
+    expected_duration_seconds: float | None = None,
+    product_identity: str | None = None,
+    resource_locks: list[str] | None = None,
+    run_id: str | None = None,
+    session_id: str | None = None,
+) -> dict[str, Any]:
+    """Start a re-attachable managed command without shell re-parsing.
+
+    The short-lived launch specification is removed by the worker immediately
+    after spawn. Environment values are inherited by the worker and hashed in
+    the durable receipt; they are never serialized.
+    """
+    if not verification.strip():
+        raise ValueError("RUN_SESSION_VERIFICATION_REQUIRED")
+    if not argv or not all(isinstance(item, str) and item for item in argv):
+        raise ValueError("RUN_SESSION_ARGV_REQUIRED")
+    if heartbeat_seconds <= 0:
+        raise ValueError("RUN_SESSION_HEARTBEAT_INVALID")
+    if timeout_seconds is not None and timeout_seconds <= 0:
+        raise ValueError("RUN_SESSION_TIMEOUT_INVALID")
+    normalized_resource_locks: list[str] = []
+    for raw_lock in resource_locks or []:
+        if (
+            not isinstance(raw_lock, str)
+            or not raw_lock.strip()
+            or len(raw_lock.strip()) > 256
+        ):
+            raise ValueError("RUN_SESSION_RESOURCE_LOCK_INVALID")
+        normalized_resource_locks.append(raw_lock.strip())
+    normalized_resource_locks = sorted(set(normalized_resource_locks))
+
+    state_root = state_root.expanduser().resolve()
+    working_directory = working_directory.expanduser().resolve()
+    if not working_directory.is_dir():
+        raise ValueError(f"RUN_SESSION_WORKDIR_MISSING: {working_directory}")
+    session_id = session_id or f"run-{uuid.uuid4().hex}"
+    run_id = run_id or session_id
+    session_root = _run_session_root(state_root, session_id)
+    session_root.mkdir(parents=True, exist_ok=False)
+    created_at = now_iso()
+    stdout_path = session_root / "stdout.log"
+    stderr_path = session_root / "stderr.log"
+    worker_log_path = session_root / "worker.log"
+    spec_path = session_root / "launch-spec.json"
+    overrides = dict(environment or {})
+    command_hash = _sha256_json(argv)
+    environment_hash = _sha256_json(overrides)
+    receipt: dict[str, Any] = {
+        "schemaVersion": RUN_SESSION_SCHEMA_VERSION,
+        "sessionId": session_id,
+        "runId": run_id,
+        "verification": verification,
+        "commandHash": command_hash,
+        "workingDirectory": str(working_directory),
+        "environmentHash": environment_hash,
+        "launcherPid": os.getpid(),
+        "workerPid": None,
+        "servicePid": None,
+        "processIdentity": None,
+        "createdAt": created_at,
+        "lastHeartbeatAt": created_at,
+        "startedAt": None,
+        "endedAt": None,
+        "exitCode": None,
+        "status": "STARTING",
+        "reasonCode": "WORKER_STARTING",
+        "stage": "prepare",
+        "stageStartedAt": created_at,
+        "stageTimings": [],
+        "stdoutPath": str(stdout_path),
+        "stderrPath": str(stderr_path),
+        "workerLogPath": str(worker_log_path),
+        "resultDigest": None,
+        "cleanupStatus": "PENDING",
+        "testProcessStarted": False,
+        "timeoutSeconds": timeout_seconds,
+        "heartbeatSeconds": heartbeat_seconds,
+        "expectedDurationSeconds": expected_duration_seconds,
+        "productIdentity": product_identity,
+        "resourceLocks": normalized_resource_locks,
+        "resourceLockTokens": {},
+        "resourceWaitMs": 0,
+        "activeTimeMs": 0,
+        "wallClockMs": 0,
+        "diagnosticPath": None,
+    }
+    _write_run_receipt(state_root, receipt)
+    lock_tokens, lock_conflict = _acquire_resource_locks(
+        state_root,
+        session_id,
+        normalized_resource_locks,
+    )
+    if lock_conflict is not None:
+        receipt.update(
+            {
+                "status": "INCOMPLETE",
+                "reasonCode": "RESOURCE_LOCK_BUSY",
+                "endedAt": now_iso(),
+                "cleanupStatus": "NO_CHILD",
+                "resourceLockConflict": lock_conflict,
+            }
+        )
+        _write_run_receipt(state_root, receipt)
+        return receipt
+    receipt["resourceLockTokens"] = lock_tokens
+    atomic_write_json(
+        _resource_lock_secrets_path(state_root, session_id),
+        {"schemaVersion": 1, "tokens": lock_tokens},
+    )
+    try:
+        _resource_lock_secrets_path(state_root, session_id).chmod(0o600)
+    except OSError:
+        pass
+    _write_run_receipt(state_root, receipt)
+    atomic_write_json(
+        spec_path,
+        {
+            "schemaVersion": 1,
+            "stateRoot": str(state_root),
+            "sessionId": session_id,
+            "argv": argv,
+            "heartbeatSeconds": heartbeat_seconds,
+        },
+    )
+    try:
+        spec_path.chmod(0o600)
+    except OSError:
+        pass
+
+    worker_env = {**os.environ, **overrides}
+    worker_env["PYTHONUTF8"] = "1"
+    worker_env["PYTHONIOENCODING"] = "utf-8"
+    worker_env["HARNESS_RUN_SESSION_WORKER"] = "1"
+    worker_argv = [
+        _absolute_executable(sys.executable),
+        str(Path(__file__).resolve()),
+        "_worker",
+        "--state-root",
+        str(state_root),
+        "--session-id",
+        session_id,
+    ]
+    try:
+        worker_log_path.touch()
+        worker = _spawn_detached_worker(
+            worker_argv,
+            cwd=working_directory,
+            env=worker_env,
+        )
+    except OSError as exc:
+        spec_path.unlink(missing_ok=True)
+        _resource_lock_secrets_path(state_root, session_id).unlink(missing_ok=True)
+        locks_released = _release_resource_locks(
+            state_root,
+            session_id,
+            lock_tokens,
+        )
+        receipt.update(
+            {
+                "status": "INCOMPLETE",
+                "reasonCode": "WORKER_LAUNCH_FAILED",
+                "endedAt": now_iso(),
+                "cleanupStatus": (
+                    "NO_CHILD"
+                    if locks_released
+                    else "RESOURCE_LOCK_RELEASE_FAILED"
+                ),
+                "error": str(exc),
+            }
+        )
+        _write_run_receipt(state_root, receipt)
+        return receipt
+    receipt["workerPid"] = worker.pid
+    receipt["workerIdentity"] = _process_identity(worker.pid, sys.executable)
+    # Best-effort early handoff. The worker repeats and verifies this transfer
+    # before spawning the managed command. Do not rewrite the session receipt
+    # here: the detached worker may already have advanced it to RUNNING.
+    _refresh_resource_locks(
+        state_root,
+        session_id,
+        lock_tokens,
+        dict(receipt["workerIdentity"]),
+    )
+    threading.Thread(target=worker.wait, daemon=True).start()
+    return receipt
+
+
+def _terminate_managed_child(
+    process: subprocess.Popen[bytes],
+    job: Any,
+    *,
+    attestation: dict[str, Any] | None = None,
+    ownership_proof: dict[str, Any] | None = None,
+) -> bool:
+    from harness_process import terminate_owned_tree
+
+    if isinstance(attestation, dict) and isinstance(ownership_proof, dict):
+        result = terminate_owned_tree(
+            attestation,
+            ownership_proof,
+            {"graceSeconds": 3.0},
+        )
+        if not result.get("cleanupComplete"):
+            return False
+    elif job is not None and getattr(job, "handle", None) is not None:
+        # Compatibility for callers still passing the old Windows job object;
+        # this branch is only used for an already-owned handle, never a PID.
+        job.terminate_and_wait()
+    else:
+        # PID-only cleanup is intentionally forbidden by the process provider.
+        return False
+    try:
+        process.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        return False
+    return process.poll() is not None
+
+
+def _run_session_worker(state_root: Path, session_id: str) -> int:
+    from harness_service import verify_process_identity
+
+    session_root = _run_session_root(state_root, session_id)
+    spec_path = session_root / "launch-spec.json"
+    receipt = _load_run_receipt(state_root, session_id)
+    receipt["resourceLockTokens"] = _load_resource_lock_tokens(
+        state_root,
+        session_id,
+        receipt,
+    )
+    try:
+        spec = json.loads(spec_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError) as exc:
+        _release_resource_locks(
+            state_root,
+            session_id,
+            dict(receipt.get("resourceLockTokens") or {}),
+        )
+        receipt.update(
+            {
+                "status": "INCOMPLETE",
+                "reasonCode": "LAUNCH_SPEC_INVALID",
+                "endedAt": now_iso(),
+                "cleanupStatus": "NO_CHILD",
+                "error": str(exc),
+            }
+        )
+        _write_run_receipt(state_root, receipt)
+        return 1
+    argv = [str(item) for item in spec.get("argv", [])]
+    heartbeat_seconds = max(float(spec.get("heartbeatSeconds") or 30.0), 0.01)
+    spec_path.unlink(missing_ok=True)
+    started_monotonic = time.monotonic()
+    _stage_transition(receipt, "spawn")
+    receipt.update(
+        {
+            "workerPid": os.getpid(),
+            "workerIdentity": _process_identity(os.getpid(), sys.executable),
+            "lastHeartbeatAt": now_iso(),
+        }
+    )
+    if not _refresh_resource_locks(
+        state_root,
+        session_id,
+        dict(receipt.get("resourceLockTokens") or {}),
+        dict(receipt["workerIdentity"]),
+    ):
+        receipt.update(
+            {
+                "status": "INCOMPLETE",
+                "reasonCode": "RESOURCE_LOCK_OWNERSHIP_LOST",
+                "endedAt": now_iso(),
+                "cleanupStatus": "NO_CHILD",
+            }
+        )
+        _write_run_receipt(state_root, receipt)
+        return 1
+    _write_run_receipt(state_root, receipt)
+
+    stdout_path = Path(str(receipt["stdoutPath"]))
+    stderr_path = Path(str(receipt["stderrPath"]))
+    stdout_path.parent.mkdir(parents=True, exist_ok=True)
+    job = None
+    spawned = None
+    ownership_proof: dict[str, Any] | None = None
+    identity: dict[str, Any] | None = None
+    process: subprocess.Popen[bytes] | None = None
+    try:
+        with stdout_path.open("wb", buffering=0) as stdout, stderr_path.open(
+            "wb", buffering=0
+        ) as stderr:
+            try:
+                from harness_process import spawn_structured_argv
+
+                spawned = spawn_structured_argv(
+                    argv,
+                    cwd=Path(str(receipt["workingDirectory"])),
+                    environment={
+                        "PYTHONUTF8": "1",
+                        "PYTHONIOENCODING": "utf-8",
+                    },
+                    owner_token=f"run:{session_id}",
+                    stdout=stdout,
+                    stderr=stderr,
+                )
+                process = spawned.process
+                ownership_proof = spawned.ownershipProof
+                _capture_provider_members(spawned)
+            except (OSError, ValueError, RuntimeError) as exc:
+                receipt.update(
+                    {
+                        "status": "INCOMPLETE",
+                        "reasonCode": "LAUNCHER_FAILED",
+                        "endedAt": now_iso(),
+                        "exitCode": None,
+                        "testProcessStarted": False,
+                        "cleanupStatus": "NO_CHILD",
+                        "error": str(exc),
+                    }
+                )
+                return 1
+            assert spawned is not None and process is not None
+            identity = spawned.attestation
+            receipt["processOwnershipProof"] = ownership_proof
+            _stage_transition(receipt, "execute")
+            receipt.update(
+                {
+                    "servicePid": process.pid,
+                    "processIdentity": identity,
+                    "startedAt": identity.get("createdAt"),
+                    "status": "RUNNING",
+                    "reasonCode": "CHILD_RUNNING",
+                    "testProcessStarted": True,
+                    "processTreeIsolated": ownership_proof is not None,
+                }
+            )
+            _write_run_receipt(state_root, receipt)
+
+            timeout_seconds = receipt.get("timeoutSeconds")
+            next_heartbeat = time.monotonic()
+            termination_reason: str | None = None
+            while process.poll() is None:
+                now = time.monotonic()
+                if timeout_seconds is not None and (
+                    now - started_monotonic >= float(timeout_seconds)
+                ):
+                    termination_reason = "TIMEOUT"
+                cancel_path = session_root / "cancel-request.json"
+                if cancel_path.is_file():
+                    termination_reason = "CANCEL_REQUESTED"
+                if termination_reason is not None:
+                    diagnostic_path = session_root / "diagnostic.json"
+                    from harness_process import (
+                        observe_process_identity,
+                        verify_process_identity as verify_attestation,
+                    )
+
+                    verified = verify_attestation(
+                        identity,
+                        observe_process_identity(process.pid),
+                    ).get("ok") is True
+                    job_owned = ownership_proof is not None
+                    if spawned is not None:
+                        _capture_provider_members(spawned)
+                    diagnostic = {
+                        "schemaVersion": 1,
+                        "sessionId": session_id,
+                        "reasonCode": termination_reason,
+                        "observedAt": now_iso(),
+                        "processIdentityVerified": verified,
+                        "terminationAuthority": (
+                            "JOB_OBJECT_OWNED"
+                            if job_owned
+                            else (
+                                "PROCESS_IDENTITY_VERIFIED"
+                                if verified
+                                else "NONE"
+                            )
+                        ),
+                        "pid": process.pid,
+                        "stdoutBytes": (
+                            stdout_path.stat().st_size if stdout_path.exists() else 0
+                        ),
+                        "stderrBytes": (
+                            stderr_path.stat().st_size if stderr_path.exists() else 0
+                        ),
+                    }
+                    atomic_write_json(diagnostic_path, diagnostic)
+                    receipt["diagnosticPath"] = str(diagnostic_path)
+                    if job_owned and verified:
+                        terminated = _terminate_managed_child(
+                            process,
+                            job,
+                            attestation=identity,
+                            ownership_proof=ownership_proof,
+                        )
+                        job = None
+                        if not terminated:
+                            receipt.update(
+                                {
+                                    "status": "INCOMPLETE",
+                                    "reasonCode": "PROCESS_TERMINATION_UNCONFIRMED",
+                                    "cleanupStatus": "PROCESS_TERMINATION_UNCONFIRMED",
+                                }
+                            )
+                    else:
+                        receipt.update(
+                            {
+                                "status": "INCOMPLETE",
+                                "reasonCode": "PROCESS_IDENTITY_UNVERIFIED",
+                                "cleanupStatus": "UNKNOWN_PROCESS_UNTOUCHED",
+                            }
+                        )
+                    break
+                if now >= next_heartbeat:
+                    receipt["lastHeartbeatAt"] = now_iso()
+                    receipt["activeTimeMs"] = int(
+                        (now - started_monotonic) * 1000
+                    )
+                    receipt["wallClockMs"] = receipt["activeTimeMs"]
+                    if not _refresh_resource_locks(
+                        state_root,
+                        session_id,
+                        dict(receipt.get("resourceLockTokens") or {}),
+                        dict(receipt["workerIdentity"]),
+                    ):
+                        receipt.update(
+                            {
+                                "status": "INCOMPLETE",
+                                "reasonCode": "RESOURCE_LOCK_OWNERSHIP_LOST",
+                                "cleanupStatus": "PROCESS_TREE_TERMINATION_REQUIRED",
+                            }
+                        )
+                        if spawned is not None:
+                            _capture_provider_members(spawned)
+                        _terminate_managed_child(
+                            process,
+                            job,
+                            attestation=identity,
+                            ownership_proof=ownership_proof,
+                        )
+                        job = None
+                        break
+                    _write_run_receipt(state_root, receipt)
+                    next_heartbeat = now + heartbeat_seconds
+                time.sleep(min(heartbeat_seconds, 0.05))
+
+            exit_code = process.poll()
+            _stage_transition(receipt, "summarize")
+            if termination_reason is not None and receipt["reasonCode"] not in {
+                "PROCESS_IDENTITY_UNVERIFIED",
+                "PROCESS_TERMINATION_UNCONFIRMED",
+                "RESOURCE_LOCK_OWNERSHIP_LOST",
+            }:
+                receipt.update(
+                    {
+                        "status": "CANCELLED",
+                        "reasonCode": termination_reason,
+                        "exitCode": exit_code,
+                        "cleanupStatus": "PROCESS_TREE_TERMINATED",
+                    }
+                )
+            elif receipt["reasonCode"] not in {
+                "PROCESS_IDENTITY_UNVERIFIED",
+                "PROCESS_TERMINATION_UNCONFIRMED",
+                "RESOURCE_LOCK_OWNERSHIP_LOST",
+            }:
+                receipt.update(
+                    {
+                        "status": "OK" if exit_code == 0 else "FAIL",
+                        "reasonCode": (
+                            "CHILD_EXIT_ZERO"
+                            if exit_code == 0
+                            else "CHILD_EXIT_NONZERO"
+                        ),
+                        "exitCode": exit_code,
+                        "cleanupStatus": "PROCESS_EXITED",
+                    }
+                )
+    except BaseException as exc:
+        receipt.update(
+            {
+                "status": "INCOMPLETE",
+                "reasonCode": "WORKER_FAILED",
+                "exitCode": None if process is None else process.poll(),
+                "cleanupStatus": "WORKER_EXCEPTION",
+                "error": str(exc),
+            }
+        )
+    finally:
+        if process is not None and process.poll() is None and ownership_proof is not None:
+            if spawned is not None:
+                _capture_provider_members(spawned)
+            tree_drained = _terminate_managed_child(
+                process,
+                job,
+                attestation=identity if isinstance(identity, dict) else None,
+                ownership_proof=ownership_proof,
+            )
+            if not tree_drained:
+                receipt.update(
+                    {
+                        "status": "INCOMPLETE",
+                        "reasonCode": "PROCESS_TREE_TERMINATION_UNCONFIRMED",
+                        "cleanupStatus": "PROCESS_TREE_TERMINATION_UNCONFIRMED",
+                    }
+                )
+            elif receipt.get("cleanupStatus") == "PROCESS_EXITED":
+                receipt["cleanupStatus"] = "PROCESS_TREE_TERMINATED"
+        ended = time.monotonic()
+        _stage_transition(receipt, "record")
+        receipt["endedAt"] = now_iso()
+        receipt["lastHeartbeatAt"] = receipt["endedAt"]
+        receipt["activeTimeMs"] = int((ended - started_monotonic) * 1000)
+        receipt["wallClockMs"] = receipt["activeTimeMs"] + int(
+            receipt.get("resourceWaitMs") or 0
+        )
+        digest = hashlib.sha256()
+        for path in (stdout_path, stderr_path):
+            if path.is_file():
+                digest.update(path.read_bytes())
+        receipt["resultDigest"] = "sha256:" + digest.hexdigest()
+        locks_released = _release_resource_locks(
+            state_root,
+            session_id,
+            dict(receipt.get("resourceLockTokens") or {}),
+        )
+        try:
+            _resource_lock_secrets_path(state_root, session_id).unlink(missing_ok=True)
+        except OSError:
+            locks_released = False
+        if not locks_released:
+            receipt.update(
+                {
+                    "status": "INCOMPLETE",
+                    "reasonCode": "RESOURCE_LOCK_RELEASE_FAILED",
+                    "cleanupStatus": "RESOURCE_LOCK_RELEASE_FAILED",
+                }
+            )
+        _close_current_stage(receipt)
+        _write_run_receipt(state_root, receipt)
+    return 0 if receipt.get("status") == "OK" else 1
+
+
+def _run_session_worker_with_log(state_root: Path, session_id: str) -> int:
+    worker_log_path = _run_session_root(state_root, session_id) / "worker.log"
+    try:
+        worker_log = worker_log_path.open(
+            "a",
+            encoding="utf-8",
+            errors="replace",
+            buffering=1,
+        )
+    except OSError:
+        return _run_session_worker(state_root, session_id)
+    with worker_log:
+        with (
+            contextlib.redirect_stdout(worker_log),
+            contextlib.redirect_stderr(worker_log),
+        ):
+            return _run_session_worker(state_root, session_id)
+
+
+def run_session_status(state_root: Path, session_id: str) -> dict[str, Any]:
+    from harness_service import is_pid_alive
+
+    receipt = _load_run_receipt(state_root, session_id)
+    worker_pid = receipt.get("workerPid")
+    worker_identity = receipt.get("workerIdentity")
+    if receipt.get("status") in RUN_TERMINAL_STATUSES:
+        if (
+            isinstance(worker_pid, int)
+            and worker_pid > 0
+            and is_pid_alive(worker_pid)
+            and _receipt_identity_state(receipt) is True
+        ):
+            finalizing = dict(receipt)
+            finalizing.update(
+                {
+                    "status": "FINALIZING",
+                    "reasonCode": "WORKER_FINALIZING",
+                }
+            )
+            return finalizing
+        return receipt
+    heartbeat_text = str(receipt.get("lastHeartbeatAt") or "")
+    try:
+        heartbeat_at = dt.datetime.fromisoformat(
+            heartbeat_text.replace("Z", "+00:00")
+        )
+        if heartbeat_at.tzinfo is None:
+            heartbeat_at = heartbeat_at.astimezone()
+        heartbeat_age = (
+            dt.datetime.now().astimezone() - heartbeat_at
+        ).total_seconds()
+    except ValueError:
+        heartbeat_age = float("inf")
+    grace = max(float(receipt.get("heartbeatSeconds") or 30.0) * 4, 2.0)
+    startup_grace = max(grace, 10.0)
+    # The detached worker owns the durable identity record.  The launcher can
+    # return before the worker has published it, so STARTING is intentionally
+    # treated as a bounded handshake window rather than an identity failure.
+    if (
+        receipt.get("status") == "STARTING"
+        and receipt.get("workerIdentity") is None
+        and heartbeat_age < startup_grace
+    ):
+        return receipt
+    identity_state = _receipt_identity_state(receipt)
+    worker_gone = (
+        isinstance(worker_pid, int)
+        and worker_pid > 0
+        and not is_pid_alive(worker_pid)
+    )
+    if worker_gone or identity_state is False or heartbeat_age >= grace:
+        latest = _load_run_receipt(state_root, session_id)
+        if latest.get("status") in RUN_TERMINAL_STATUSES:
+            return latest
+        if heartbeat_age < grace and worker_gone and identity_state is not False:
+            return latest
+        receipt.update(
+            {
+                "status": "INCOMPLETE",
+                "reasonCode": (
+                    "WORKER_IDENTITY_MISMATCH"
+                    if identity_state is False and not worker_gone
+                    else "HEARTBEAT_LOST"
+                ),
+                "endedAt": now_iso(),
+                "cleanupStatus": "WORKER_EXITED_WITHOUT_FINAL_RECEIPT",
+            }
+        )
+        _write_run_receipt(state_root, receipt)
+    return receipt
+
+
+def read_run_session_log(
+    state_root: Path,
+    session_id: str,
+    *,
+    stream: str = "stdout",
+    cursor: int = 0,
+    max_bytes: int = 64 * 1024,
+) -> dict[str, Any]:
+    if stream not in {"stdout", "stderr"}:
+        raise ValueError(f"RUN_SESSION_STREAM_INVALID: {stream}")
+    if cursor < 0 or max_bytes <= 0:
+        raise ValueError("RUN_SESSION_CURSOR_INVALID")
+    receipt = _load_run_receipt(state_root, session_id)
+    path = Path(str(receipt[f"{stream}Path"]))
+    raw = b""
+    decode_status = "OK"
+    size = path.stat().st_size if path.is_file() else 0
+    if path.is_file() and cursor < size:
+        with path.open("rb") as handle:
+            handle.seek(cursor)
+            raw = handle.read(max_bytes)
+        while raw:
+            try:
+                text = raw.decode("utf-8")
+                break
+            except UnicodeDecodeError as exc:
+                if exc.end != len(raw):
+                    # An invalid sequence in the middle is durable evidence,
+                    # so consume it and expose replacement text instead of
+                    # silently dropping bytes from the cursor stream.
+                    text = raw.decode("utf-8", errors="replace")
+                    decode_status = "LOG_DECODE_DEGRADED"
+                    break
+                if (
+                    receipt.get("status") in RUN_TERMINAL_STATUSES
+                    and cursor + len(raw) >= size
+                ):
+                    # Once the producer is terminal, an incomplete trailing
+                    # sequence cannot be completed by a later write. Preserve
+                    # and consume it with an explicit degraded status.
+                    text = raw.decode("utf-8", errors="replace")
+                    decode_status = "LOG_DECODE_DEGRADED"
+                    break
+                # A live writer may have split a multibyte character across
+                # this read. Keep the incomplete suffix for the next cursor
+                # request so callers never see duplicate replacement glyphs.
+                raw = raw[: exc.start]
+        else:
+            text = ""
+    else:
+        text = ""
+    next_cursor = cursor + len(raw)
+    terminal = receipt.get("status") in RUN_TERMINAL_STATUSES
+    return {
+        "ok": True,
+        "sessionId": session_id,
+        "stream": stream,
+        "cursor": cursor,
+        "nextCursor": next_cursor,
+        "text": text,
+        "eof": terminal and next_cursor >= size,
+        "status": receipt.get("status"),
+        "rawDigest": "sha256:" + hashlib.sha256(raw).hexdigest(),
+        "decodeStatus": decode_status,
+    }
+
+
+def cancel_run_session(
+    state_root: Path,
+    session_id: str,
+    *,
+    reason: str = "CANCEL_REQUESTED",
+) -> dict[str, Any]:
+    receipt = _load_run_receipt(state_root, session_id)
+    if receipt.get("status") in RUN_TERMINAL_STATUSES:
+        return receipt
+    if _receipt_identity_state(receipt) is not True:
+        return {
+            **receipt,
+            "ok": False,
+            "code": "WORKER_IDENTITY_UNVERIFIED",
+            "unknownProcessUntouched": True,
+        }
+    atomic_write_json(
+        _run_session_root(state_root, session_id) / "cancel-request.json",
+        {"reasonCode": reason, "requestedAt": now_iso()},
+    )
+    return {**receipt, "ok": True, "action": "cancel-requested"}
+
+
 def adapter_worktree(agent: str, change_id: str) -> dict[str, str]:
     if agent not in _ADAPTERS:
         raise ValueError(f"ADAPTER_UNKNOWN: {agent}")
@@ -221,6 +1733,35 @@ def build_parser() -> argparse.ArgumentParser:
     p_adapter.add_argument("--agent", choices=sorted(_ADAPTERS), required=True)
     p_adapter.add_argument("--change", required=True)
     p_adapter.add_argument("--json", action="store_true")
+    p_start = sub.add_parser("run-start", help="start a managed background run")
+    p_start.add_argument("--state-root", required=True)
+    p_start.add_argument("--verification", required=True)
+    p_start.add_argument("--working-directory", required=True)
+    p_start.add_argument("--timeout-seconds", type=float)
+    p_start.add_argument("--heartbeat-seconds", type=float, default=30.0)
+    p_start.add_argument("--expected-duration-seconds", type=float)
+    p_start.add_argument("--product-identity")
+    p_start.add_argument("--resource-lock", action="append", default=[])
+    p_start.add_argument("--json", action="store_true")
+    p_start.add_argument("argv", nargs=argparse.REMAINDER)
+    p_status = sub.add_parser("run-status", help="read a managed run receipt")
+    p_status.add_argument("--state-root", required=True)
+    p_status.add_argument("--session-id", required=True)
+    p_status.add_argument("--json", action="store_true")
+    p_log = sub.add_parser("run-log", help="read an incremental log page")
+    p_log.add_argument("--state-root", required=True)
+    p_log.add_argument("--session-id", required=True)
+    p_log.add_argument("--stream", choices=("stdout", "stderr"), default="stdout")
+    p_log.add_argument("--cursor", type=int, default=0)
+    p_log.add_argument("--max-bytes", type=int, default=64 * 1024)
+    p_log.add_argument("--json", action="store_true")
+    p_cancel = sub.add_parser("run-cancel", help="request identity-safe cancellation")
+    p_cancel.add_argument("--state-root", required=True)
+    p_cancel.add_argument("--session-id", required=True)
+    p_cancel.add_argument("--json", action="store_true")
+    p_worker = sub.add_parser("_worker", help=argparse.SUPPRESS)
+    p_worker.add_argument("--state-root", required=True)
+    p_worker.add_argument("--session-id", required=True)
     return parser
 
 
@@ -229,15 +1770,47 @@ def main(argv: list[str] | None = None) -> int:
     try:
         if args.command == "doctor":
             result = doctor(Path(args.project), Path(args.change_dir), agent=args.agent)
-        else:
+        elif args.command == "adapter":
             result = {"ok": True, "action": "adapter", **adapter_worktree(args.agent, args.change)}
+        elif args.command == "_worker":
+            return _run_session_worker_with_log(
+                Path(args.state_root),
+                args.session_id,
+            )
+        elif args.command == "run-start":
+            command_argv = list(args.argv)
+            if command_argv and command_argv[0] == "--":
+                command_argv = command_argv[1:]
+            result = start_run_session(
+                state_root=Path(args.state_root),
+                verification=args.verification,
+                argv=command_argv,
+                working_directory=Path(args.working_directory),
+                timeout_seconds=args.timeout_seconds,
+                heartbeat_seconds=args.heartbeat_seconds,
+                expected_duration_seconds=args.expected_duration_seconds,
+                product_identity=args.product_identity,
+                resource_locks=list(args.resource_lock),
+            )
+        elif args.command == "run-status":
+            result = run_session_status(Path(args.state_root), args.session_id)
+        elif args.command == "run-log":
+            result = read_run_session_log(
+                Path(args.state_root),
+                args.session_id,
+                stream=args.stream,
+                cursor=args.cursor,
+                max_bytes=args.max_bytes,
+            )
+        else:
+            result = cancel_run_session(Path(args.state_root), args.session_id)
     except (OSError, ValueError) as exc:
         code = str(exc).split(":", 1)[0]
         result = {"ok": False, "code": code, "error": str(exc)}
         stream = sys.stderr
         stream.write(json.dumps(result, ensure_ascii=False) + "\n")
         return 1
-    if args.json:
+    if getattr(args, "json", False):
         sys.stdout.write(json.dumps(result, ensure_ascii=False, indent=2) + "\n")
     else:
         sys.stdout.write(str(result.get("action")) + "\n")