agentic-runner 2.7.0__tar.gz → 3.0.0__tar.gz

{agentic_runner-2.7.0 → agentic_runner-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentic-runner
-Version: 2.7.0
+Version: 3.0.0
 Summary: The Agentic OS Runner: an activity-only Temporal executor for workspaces, Agent Runtimes and verb seams
 License-Expression: AGPL-3.0-only
 License-File: LICENSE
@@ -12,6 +12,9 @@ Requires-Dist: pydantic-settings<3.0,>=2.0
 Requires-Dist: pydantic<3.0,>=2.0
 Requires-Dist: pyjwt[crypto]>=2.13.0
 Requires-Dist: temporalio<2.0,>=1.10
+Provides-Extra: testing
+Requires-Dist: pytest-asyncio<1.0,>=0.24; extra == 'testing'
+Requires-Dist: pytest<9.0,>=8.0; extra == 'testing'
 Description-Content-Type: text/markdown
 
 # agentic-runner

{agentic_runner-2.7.0 → agentic_runner-3.0.0}/pyproject.toml

@@ -19,9 +19,20 @@ dependencies = [
   "temporalio>=1.10,<2.0",
 ]
 
+[project.optional-dependencies]
+# The conformance kit (`agentic_runner.testing`, docs/conformance.md): the fake control
+# plane needs nothing beyond the dependencies above; the scenario suite needs these.
+testing = [
+  "pytest>=8.0,<9.0",
+  "pytest-asyncio>=0.24,<1.0",
+]
+
 [project.scripts]
 agentic-runner = "agentic_runner.cli:main"
 
+[project.entry-points.pytest11]
+agentic_runner = "agentic_runner.testing.plugin"
+
 [build-system]
 requires = ["hatchling>=1.27,<2.0"]
 build-backend = "hatchling.build"

{agentic_runner-2.7.0 → agentic_runner-3.0.0}/src/agentic_runner/__init__.py

@@ -7,6 +7,6 @@ stay on the platform; this package imports none of them, and a CI partition test
 (``tests/test_package_partition.py``) fails the build if that changes.
 """
 
-__version__ = "2.7.0"
+__version__ = "3.0.0"
 
 __all__ = ["__version__"]

{agentic_runner-2.7.0 → agentic_runner-3.0.0}/src/agentic_runner/activities.py

@@ -38,7 +38,12 @@ from uuid import UUID
 from temporalio import activity
 from temporalio.exceptions import ApplicationError
 
-from agentic_runner.attempts import AttemptRecords, PriorAttemptAliveError, fence_work_record
+from agentic_runner.attempts import (
+    AttemptRecords,
+    PriorAttemptAliveError,
+    fence_work_record,
+    refuse_if_prior_attempt_alive,
+)
 from agentic_runner.callback import (
     CALLBACK_TOKEN_ENV,
     AnnotateRequest,
@@ -86,6 +91,7 @@ from agentic_runner.integrations.git.contracts import (
     PrepareVerifierWorkspaceRequest,
     PushBranchRequest,
 )
+from agentic_runner.integrations.git.evidence import read_head_commit
 from agentic_runner.integrations.git.workspace import (
     GitWorkspacePolicyError,
     contract_workspace_path,
@@ -115,6 +121,7 @@ from agentic_runner.workers.agent_runtime import (
     AuthModel,
     DirectiveRequest,
     DirectiveResult,
+    ResumableAgentRuntime,
 )
 from agentic_runner.workers.contract_isolation import (
     NO_CONTRACT,
@@ -332,8 +339,87 @@ _APPROVAL_POLLS_PER_ACTIVITY = 10
 _APPROVAL_ACTIVITY_TIME_BUDGET_SECONDS = 360.0
 
 
+@dataclass(frozen=True, slots=True)
+class HarnessSession:
+    """The harness session a Directive attempt started, and where it ran (local-agents 16).
+
+    A retry may resume it only when the Contract, the Workspace path and the head all
+    match exactly (ADR-0007, amendment 2026-10-03).
+    """
+
+    session_id: str
+    contract_id: str | None
+    workspace_path: str
+    head: str | None
+
+    @classmethod
+    def from_heartbeat(cls, details: object) -> "HarnessSession | None":
+        if not isinstance(details, Mapping):
+            return None
+        session_id = details.get("session_id")
+        contract_id = details.get("contract_id")
+        workspace_path = details.get("workspace_path")
+        head = details.get("head")
+        if (
+            not isinstance(session_id, str)
+            or not isinstance(workspace_path, str)
+            or not isinstance(contract_id, str | None)
+            or not isinstance(head, str | None)
+        ):
+            return None
+        return cls(session_id, contract_id, workspace_path, head)
+
+
+def _why_not_resume(
+    prior: HarnessSession | None,
+    here: HarnessSession,
+    agent_runtime: AgentRuntime,
+    sandbox: DirectiveSandbox | None,
+) -> str | None:
+    if prior is None:
+        return "no_prior_session"
+    if prior.contract_id != here.contract_id:
+        return "contract_changed"
+    if prior.workspace_path != here.workspace_path:
+        return "workspace_changed"
+    if here.head is None or prior.head != here.head:
+        return "head_changed"
+    if not isinstance(agent_runtime, ResumableAgentRuntime):
+        return "runtime_cannot_resume"
+    if not agent_runtime.has_session(prior.session_id, sandbox):
+        return "session_not_found"
+    return None
+
+
+class _Liveness:
+    """What one attempt's heartbeats carry: its first start, and its harness session.
+
+    Both ride in the Temporal heartbeat details rather than in the Runner's process
+    (ADR-0013 §3), so the retry that follows a lost pod still finds them.
+    """
+
+    def __init__(
+        self, *, first_started: float, now: float, prior_session: HarnessSession | None
+    ) -> None:
+        self.earlier_attempts_seconds = max(0.0, now - first_started)
+        self.prior_session = prior_session
+        self._first_started = first_started
+        self._session: HarnessSession | None = None
+
+    def details(self) -> tuple[object, ...]:
+        if self._session is None:
+            return (self._first_started,)
+        return (self._first_started, asdict(self._session))
+
+    def record_session(self, session: HarnessSession) -> None:
+        self._session = session
+        # At once, not at the next beat: the attempt may be lost before then.
+        if activity.in_activity():
+            activity.heartbeat(*self.details())
+
+
 @contextlib.asynccontextmanager
-async def _liveness_heartbeats() -> AsyncIterator[float]:
+async def _liveness_heartbeats() -> AsyncIterator[_Liveness]:
     """Emit periodic activity heartbeats from a background task while the body runs.
 
     Async-activity heartbeats are delivered on the worker event loop, so the wrapped
@@ -345,24 +431,29 @@ async def _liveness_heartbeats() -> AsyncIterator[float]:
     47, 23 item 4). Each beat carries the first attempt's wall-clock start as its
     heartbeat details, so the retry that follows a laptop's sleep -- the attempt Temporal
     failed on its heartbeat timeout -- charges the Work Record's wall-clock from there:
-    sleep is an outage, and the Budget keeps running through it.
+    sleep is an outage, and the Budget keeps running through it. Once the Agent Runtime
+    names its session, the beats carry that too (local-agents 16).
     """
+    now = time.time()
     if not activity.in_activity():
-        yield 0.0
+        yield _Liveness(first_started=now, now=now, prior_session=None)
         return
 
-    now = time.time()
     details = activity.info().heartbeat_details
-    first_started = float(details[0]) if details else now
+    liveness = _Liveness(
+        first_started=float(details[0]) if details else now,
+        now=now,
+        prior_session=HarnessSession.from_heartbeat(details[1]) if len(details) > 1 else None,
+    )
 
     async def beat() -> None:
         while True:
-            activity.heartbeat(first_started)
+            activity.heartbeat(*liveness.details())
             await asyncio.sleep(_HEARTBEAT_INTERVAL_SECONDS)
 
     heartbeater = asyncio.create_task(beat())
     try:
-        yield max(0.0, now - first_started)
+        yield liveness
     finally:
         heartbeater.cancel()
         with contextlib.suppress(asyncio.CancelledError):
@@ -1337,6 +1428,7 @@ def wipe_contract_residue(
 # Where a Runner-side routing refusal lands in the trail (PRD issue 42, 17 A11).
 _ROUTING_EVIDENCE_SOURCE = "runner.routing"
 PRIOR_ATTEMPT_ALIVE_EVIDENCE_SOURCE = "runner.prior_attempt_alive"
+HARNESS_SESSION_EVIDENCE_SOURCE = "runner.harness_session"
 DIRECTIVE_TOKEN_EVIDENCE_SOURCE = "runner.directive_token"
 AGENT_RUNTIME_EVIDENCE_SOURCE = "runner.agent_runtime"
 SKILLS_EVIDENCE_SOURCE = "runner.skills"
@@ -1613,6 +1705,63 @@ class RunnerRalphActivities:
                 },
             )
 
+    async def _harness_session(
+        self,
+        liveness: _Liveness,
+        *,
+        work_record_id: str,
+        directive_number: int,
+        agent_runtime: AgentRuntime,
+        contract_id: str | None,
+        workspace_path: Path,
+        sandbox: DirectiveSandbox | None,
+    ) -> tuple[str | None, Callable[[str], None]]:
+        """Resume the session an earlier attempt of this Directive started, or start fresh.
+
+        Returns the session to resume, if any, and the hook that files a fresh one in the
+        heartbeat details. Every retry writes one Evidence event saying which, and why --
+        never what the session holds (local-agents 16, ADR-0007 amendment 2026-10-03).
+        """
+
+        head = read_head_commit(
+            workspace_path=workspace_path, workspace_root=self._require_workspace_root()
+        )
+        here = HarnessSession(
+            session_id="",
+            contract_id=contract_id,
+            workspace_path=str(workspace_path),
+            head=head,
+        )
+
+        def start_fresh(session_id: str) -> None:
+            liveness.record_session(replace(here, session_id=session_id))
+
+        attempt = activity.info().attempt if activity.in_activity() else 1
+        if attempt == 1:
+            return None, start_fresh
+        # Made explicit rather than left to the spawn: the session to resume must not be
+        # one a still-running harness is writing (RR-05). A refusal raises into `_fenced`.
+        refuse_if_prior_attempt_alive()
+        prior = liveness.prior_session
+        reason = _why_not_resume(prior, here, agent_runtime, sandbox)
+        await self._fastapi_client.append_evidence(
+            work_record_id,
+            source=HARNESS_SESSION_EVIDENCE_SOURCE,
+            actor=self._actor(),
+            payload={
+                "event": "directive.harness_session",
+                "work_record_id": work_record_id,
+                "directive_number": directive_number,
+                "attempt": attempt,
+                "decision": "fresh" if reason else "resumed",
+                "reason": reason or "contract_workspace_and_head_match",
+            },
+        )
+        if reason is not None or prior is None:
+            return None, start_fresh
+        liveness.record_session(prior)
+        return prior.session_id, start_fresh
+
     @activity.defn(name="create_or_update_branch_pr")
     async def create_or_update_branch_pr(
         self,
@@ -1652,7 +1801,7 @@ class RunnerRalphActivities:
         asked: list[QuestionAsked],
     ) -> BranchPullRequestOutput:
         async with (
-            _liveness_heartbeats() as earlier_attempts_seconds,
+            _liveness_heartbeats() as liveness,
             contextlib.AsyncExitStack() as attempt_stack,
         ):
             if (
@@ -1670,7 +1819,7 @@ class RunnerRalphActivities:
                     pr_created=False,
                 )
 
-            directive_started = self._monotonic() - earlier_attempts_seconds
+            directive_started = self._monotonic() - liveness.earlier_attempts_seconds
             await self._advance_work_record_lifecycle(
                 request.work_record_id,
                 to_state="IN_PROGRESS",
@@ -1798,10 +1947,22 @@ class RunnerRalphActivities:
             )
             prompt_notes: list[str] = []
             await attempt.hooks.phase(HookName.PRE_RUNTIME)
+            sandbox = self._directive_sandbox(runtime_state, checkout_workspace)
+            resume_session_id, on_session_started = await self._harness_session(
+                liveness,
+                work_record_id=request.work_record_id,
+                directive_number=request.directive_number,
+                agent_runtime=agent_runtime,
+                contract_id=contract_id,
+                workspace_path=checkout_workspace,
+                sandbox=sandbox,
+            )
             codex_result = await agent_runtime.execute_directive(
                 DirectiveRequest(
-                    sandbox=self._directive_sandbox(runtime_state, checkout_workspace),
+                    sandbox=sandbox,
                     workspace_path=checkout_workspace,
+                    resume_session_id=resume_session_id,
+                    on_session_started=on_session_started,
                     # The attempt's callback socket and bearer, plus whatever the
                     # `environment` hook exported. The env allow-list gains these names
                     # and nothing else (PRD issue 09's invariant, issue 45's amendment).
@@ -4500,7 +4661,7 @@ class RunnerRalphActivities:
         """
 
         async with (
-            _liveness_heartbeats() as earlier_attempts_seconds,
+            _liveness_heartbeats() as liveness,
             contextlib.AsyncExitStack() as attempt_stack,
         ):
             if (
@@ -4516,7 +4677,7 @@ class RunnerRalphActivities:
                     branch_head_sha="",
                     summary="directive unavailable: runtime dependencies missing",
                 )
-            directive_started = self._monotonic() - earlier_attempts_seconds
+            directive_started = self._monotonic() - liveness.earlier_attempts_seconds
             # Loop back into the working state for another runtime turn.
             await self._advance_work_record_lifecycle(
                 request.work_record_id,
@@ -4584,10 +4745,22 @@ class RunnerRalphActivities:
             )
             prompt_notes: list[str] = []
             await attempt.hooks.phase(HookName.PRE_RUNTIME)
+            sandbox = self._directive_sandbox(state, state.workspace_path)
+            resume_session_id, on_session_started = await self._harness_session(
+                liveness,
+                work_record_id=request.work_record_id,
+                directive_number=request.directive_number,
+                agent_runtime=agent_runtime,
+                contract_id=state.contract_id,
+                workspace_path=state.workspace_path,
+                sandbox=sandbox,
+            )
             codex_result = await agent_runtime.execute_directive(
                 DirectiveRequest(
-                    sandbox=self._directive_sandbox(state, state.workspace_path),
+                    sandbox=sandbox,
                     workspace_path=state.workspace_path,
+                    resume_session_id=resume_session_id,
+                    on_session_started=on_session_started,
                     extra_env=attempt.env,
                     mcp_servers=attempt.mcp_servers,
                     egress_allow_list=attempt.egress_allow_list,

{agentic_runner-2.7.0 → agentic_runner-3.0.0}/src/agentic_runner/host_store.py

@@ -19,7 +19,6 @@ operator's act, through ``agentic-runner credential set``.
 
 from __future__ import annotations
 
-import os
 import shutil
 import subprocess
 import sys
@@ -28,6 +27,7 @@ from pathlib import Path
 from typing import Protocol
 
 from agentic_runner.credentials import DirectoryCredentialStore
+from agentic_runner.private_state import private_read, private_write
 from agentic_runner_contracts.runner_registration import StoreKind
 
 __all__ = [
@@ -66,16 +66,12 @@ class FileCredentialStore(DirectoryCredentialStore):
         super().__init__(root)
         self.root = root
 
+    def get(self, reference: str) -> str | None:
+        raw = private_read(self.root / _single_segment(reference))
+        return None if raw is None else raw.decode("utf-8").strip()
+
     def put(self, reference: str, value: str) -> None:
-        self.root.mkdir(parents=True, exist_ok=True)
-        self.root.chmod(0o700)
-        path = self.root / _single_segment(reference)
-        # Created 0600 rather than chmod-ed after: there is no instant at which the value
-        # sits in a file another uid can open.
-        descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
-        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
-            handle.write(value)
-        path.chmod(0o600)
+        private_write(self.root / _single_segment(reference), value.encode("utf-8"))
 
 
 class KeychainStore:

{agentic_runner-2.7.0 → agentic_runner-3.0.0}/src/agentic_runner/integrations/git/evidence.py

@@ -117,6 +117,33 @@ def collect_git_evidence(
     )
 
 
+def read_head_commit(
+    *,
+    workspace_path: Path,
+    workspace_root: Path,
+    command_timeout_seconds: int = 10,
+) -> str | None:
+    """The Workspace's HEAD commit, or None when it has none (no clone, an unborn branch).
+
+    Reads the tree directly rather than through the workspace adapter: an in-place
+    Directive retried on a restarted Runner finds its clone on disk but not in the
+    adapter's registry.
+    """
+
+    resolved_workspace = resolve_workspace_path(workspace_root, workspace_path)
+    if not os.path.lexists(resolved_workspace / ".git"):
+        return None
+    require_runner_owned_git_dir(resolved_workspace)
+    head = _run_git_evidence_command(
+        ["rev-parse", "--verify", "--quiet", "HEAD"],
+        cwd=resolved_workspace,
+        output_limit_bytes=256,
+        command_timeout_seconds=command_timeout_seconds,
+    )
+    commit = head.stdout.strip()
+    return commit if head.returncode == 0 and commit else None
+
+
 def build_git_evidence(
     *,
     workspace_path: Path,

{agentic_runner-2.7.0 → agentic_runner-3.0.0}/src/agentic_runner/lifecycle.py

@@ -13,6 +13,7 @@ from pathlib import Path
 
 from pydantic import TypeAdapter
 
+from agentic_runner.private_state import private_read, private_write
 from agentic_runner_contracts.runner_registration import LifecycleEvent, LifecycleKind
 
 __all__ = ["LIFECYCLE_FILENAME", "LifecycleOutbox"]
@@ -33,9 +34,8 @@ class LifecycleOutbox:
         self._write(events[-_KEEP:])
 
     def pending(self) -> list[LifecycleEvent]:
-        if not self._path.is_file():
-            return []
-        return _EVENTS.validate_json(self._path.read_bytes())
+        raw = private_read(self._path)
+        return [] if raw is None else _EVENTS.validate_json(raw)
 
     def acknowledge(self, sent: list[LifecycleEvent]) -> None:
         """Drop what an acknowledged heartbeat carried; keep anything added meanwhile."""
@@ -44,5 +44,4 @@ class LifecycleOutbox:
         self._write(remaining)
 
     def _write(self, events: list[LifecycleEvent]) -> None:
-        self._path.parent.mkdir(parents=True, exist_ok=True)
-        self._path.write_bytes(_EVENTS.dump_json(events))
+        private_write(self._path, _EVENTS.dump_json(events))

{agentic_runner-2.7.0 → agentic_runner-3.0.0}/src/agentic_runner/message_store.py

@@ -32,6 +32,7 @@ from uuid import UUID, uuid4
 
 from temporalio.client import Client
 
+from agentic_runner.private_state import private_write
 from agentic_runner_contracts.channel_messages import (
     PENDING_MESSAGES_SIGNAL,
     MessageEnvelope,
@@ -134,9 +135,11 @@ class MessageStore:
         )
         path = self._path(contract_id, work_record_id)
         _ensure_dir(path.parent)
-        with path.open("a", encoding="utf-8") as handle:
+        descriptor = os.open(
+            path, os.O_WRONLY | os.O_APPEND | os.O_CREAT | os.O_NOFOLLOW, _FILE_MODE
+        )
+        with os.fdopen(descriptor, "a", encoding="utf-8") as handle:
             handle.write(envelope.model_dump_json() + "\n")
-        path.chmod(_FILE_MODE)
         return envelope
 
     def read(
@@ -187,9 +190,7 @@ class MessageStore:
         cursors = self._cursors(contract_id, work_record_id)
         cursors[agent_id] = str(through.message_id)
         path = self._cursor_path(contract_id, work_record_id)
-        _ensure_dir(path.parent)
-        path.write_text(json.dumps(cursors), encoding="utf-8")
-        path.chmod(_FILE_MODE)
+        private_write(path, json.dumps(cursors).encode("utf-8"))
 
     def transcript(self, request: TranscriptRequest) -> TranscriptDelivery:
         """The pull-through's answer: every body, or the Contract state that seals them."""
@@ -222,8 +223,7 @@ class MessageStore:
         if not stores:
             return 0
         marker = contract_dir / SEALED_MARKER
-        marker.write_text(json.dumps({"contract_state": contract_state}), encoding="utf-8")
-        marker.chmod(_FILE_MODE)
+        private_write(marker, json.dumps({"contract_state": contract_state}).encode("utf-8"))
         return len(stores)
 
     def sealed_state(self, contract_id: str) -> str | None:

agentic_runner-3.0.0/src/agentic_runner/private_state.py

@@ -0,0 +1,138 @@
+"""The state directory's one writer and one reader (runner-repo issue 08).
+
+The state directory holds the Runner's private identity key and the Recipient Key, so
+nothing in it may be readable by another uid for even an instant, and no crash may leave a
+half-written file where the identity was. Every file the Runner writes there goes through
+:func:`private_write` and every file it reads through :func:`private_read`; both refuse a
+directory or file that is a symlink, belongs to another uid or carries a group or other
+permission bit, rather than tightening it -- a state directory in that shape was put there
+by someone else, and the Runner cannot know what they read while it was open.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import errno
+import os
+import secrets
+import stat
+from collections.abc import Callable, Iterable
+from pathlib import Path
+
+__all__ = [
+    "UnsafeStateError",
+    "ensure_private_dir",
+    "private_read",
+    "private_write",
+    "require_private_files",
+]
+
+_DIR_MODE = 0o700
+_FILE_MODE = 0o600
+_GROUP_OTHER_BITS = 0o077
+
+
+class UnsafeStateError(RuntimeError):
+    """The state directory, or a file in it, is not this Runner's alone."""
+
+    reason = "unsafe_state_dir"
+
+
+def ensure_private_dir(path: Path) -> None:
+    """Create ``path`` 0700 if it is missing, else refuse it unless it is private already."""
+
+    try:
+        os.mkdir(path, _DIR_MODE)
+    except FileExistsError:
+        pass
+    except FileNotFoundError:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        os.mkdir(path, _DIR_MODE)
+    _require_private(path, os.lstat(path), stat.S_ISDIR, "directory", "chmod 700")
+
+
+def require_private_files(directory: Path, names: Iterable[str]) -> None:
+    """Refuse any of ``directory``'s ``names`` that exists and is not private; skip the rest."""
+
+    for name in names:
+        path = directory / name
+        try:
+            status = os.lstat(path)
+        except FileNotFoundError:
+            continue
+        _require_private(path, status, stat.S_ISREG, "file", "chmod 600")
+
+
+def private_write(path: Path, data: bytes) -> None:
+    """Replace ``path`` with ``data``: 0600 from the first byte, and all-or-nothing.
+
+    A temp file beside the target, created exclusively and without following a planted
+    symlink, then renamed over it: a reader sees the old content or the new, never a
+    truncated identity, and the rename is made durable by syncing the directory too.
+    """
+
+    ensure_private_dir(path.parent)
+    temporary = path.with_name(f".{path.name}.{secrets.token_hex(8)}.tmp")
+    descriptor = os.open(
+        temporary, os.O_CREAT | os.O_EXCL | os.O_WRONLY | os.O_NOFOLLOW, _FILE_MODE
+    )
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    except BaseException:
+        with contextlib.suppress(FileNotFoundError):
+            os.unlink(temporary)
+        raise
+    directory = os.open(path.parent, os.O_RDONLY)
+    try:
+        os.fsync(directory)
+    finally:
+        os.close(directory)
+
+
+def private_read(path: Path) -> bytes | None:
+    """``path``'s content, or ``None`` if it does not exist; refused unless private."""
+
+    parent = path.parent
+    try:
+        parent_status = os.lstat(parent)
+    except FileNotFoundError:
+        return None
+    _require_private(parent, parent_status, stat.S_ISDIR, "directory", "chmod 700")
+    try:
+        descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)
+    except FileNotFoundError:
+        return None
+    except OSError as error:
+        if error.errno == errno.ELOOP:
+            raise UnsafeStateError(f"{path} is a symlink; refusing to read through it") from error
+        raise
+    with os.fdopen(descriptor, "rb") as handle:
+        _require_private(path, os.fstat(handle.fileno()), stat.S_ISREG, "file", "chmod 600")
+        return handle.read()
+
+
+def _require_private(
+    path: Path,
+    status: os.stat_result,
+    is_kind: Callable[[int], bool],
+    kind: str,
+    remedy: str,
+) -> None:
+    if stat.S_ISLNK(status.st_mode):
+        raise UnsafeStateError(f"{path} is a symlink; the state {kind} must be a real {kind}")
+    if not is_kind(status.st_mode):
+        raise UnsafeStateError(f"{path} is not a {kind}")
+    euid = os.geteuid()
+    if status.st_uid != euid:
+        raise UnsafeStateError(
+            f"{path} is owned by uid {status.st_uid}, not this Runner's uid {euid}"
+        )
+    if status.st_mode & _GROUP_OTHER_BITS:
+        raise UnsafeStateError(
+            f"{path} is mode {stat.S_IMODE(status.st_mode):04o}, open to group or others; "
+            f"`{remedy} {path}` if nobody else could have read it"
+        )

{agentic_runner-2.7.0 → agentic_runner-3.0.0}/src/agentic_runner/registration.py

@@ -33,6 +33,7 @@ from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
 from pydantic import BaseModel, ConfigDict
 
 from agentic_runner import __version__ as runner_version
+from agentic_runner.private_state import private_read, private_write
 from agentic_runner_contracts import __version__ as contracts_version
 from agentic_runner_contracts.channel_messages import TRANSCRIPT_DELIVERIES_PATH, TranscriptDelivery
 from agentic_runner_contracts.runner_registration import (
@@ -64,6 +65,10 @@ DIRECTIVE_TOKEN_PATH = "/api/runner/v1/runners/directive-token"
 INTAKE_WORK_RECORDS_PATH = "/api/runner/v1/runners/intake/work-records"
 INTAKE_IGNORED_PATH = "/api/runner/v1/runners/intake/ignored"
 
+# The refusal a revoked Runner's heartbeat earns (06 §2: revocation *is* the refused
+# heartbeat). The one reason this process stops on rather than retries.
+RUNNER_REVOKED_REASON = "runner_revoked"
+
 # What the state directory holds after a successful bootstrap. One file, mode 0600: the
 # private key is in it, and a Runner that loses it re-bootstraps rather than recovering.
 STATE_FILENAME = "runner-identity.json"
@@ -208,19 +213,12 @@ def _version(value: str) -> tuple[int, ...]:
 def load_state(state_dir: Path) -> RunnerState | None:
     """The persisted identity, or ``None`` on a first boot."""
 
-    path = state_dir / STATE_FILENAME
-    if not path.exists():
-        return None
-    return RunnerState.model_validate_json(path.read_text(encoding="utf-8"))
+    raw = private_read(state_dir / STATE_FILENAME)
+    return None if raw is None else RunnerState.model_validate_json(raw)
 
 
 def save_state(state_dir: Path, state: RunnerState) -> None:
-    state_dir.mkdir(parents=True, exist_ok=True)
-    path = state_dir / STATE_FILENAME
-    path.write_text(state.model_dump_json(), encoding="utf-8")
-    # The private key is in this file; a shared PVC or a workstation home is not a place
-    # to leave it group-readable.
-    path.chmod(0o600)
+    private_write(state_dir / STATE_FILENAME, state.model_dump_json().encode("utf-8"))
 
 
 class RunnerRegistrationClient: