panopticon-app 0.0.1__py3-none-any.whl

panopticon/__init__.py

@@ -0,0 +1,3 @@
+"""panopticon — keep an eye on your agents."""
+
+__version__ = "0.0.1"

panopticon/client.py

@@ -0,0 +1,324 @@
+"""The task service's REST client — shared by every caller outside the service itself.
+
+Both the in-container agent harness and the terminal controller (dashboard + CLI) talk to the
+task service over the same HTTP API, so they share one client. It wraps an
+:class:`httpx.Client` — real (pointed at the runner-injected service URL) or a FastAPI
+``TestClient`` in tests. Methods mirror the API one-for-one; reads return parsed JSON, writes
+return the updated resource. LLM-free — agents reach the LLM only inside the container.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from typing import Any, cast
+
+import httpx
+
+from panopticon.core.models import Status
+
+JsonObj = dict[str, Any]
+
+
+class TaskServiceClient:
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    @staticmethod
+    def _json(resp: httpx.Response) -> Any:
+        resp.raise_for_status()
+        return resp.json()
+
+    # -- reads --------------------------------------------------------------------
+
+    def list_workflows(self) -> list[JsonObj]:
+        return cast("list[JsonObj]", self._json(self._http.get("/workflows")))
+
+    def list_workflows_for_repo(self, repo_id: str) -> list[dict[str, str]]:
+        """Workflows visible for a repo, filtered by its preferences and each workflow's opt_in."""
+        return cast("list[dict[str, str]]", self._json(self._http.get(f"/repos/{repo_id}/workflows")))
+
+    def workflow_image_layer(self, name: str) -> str:
+        """The workflow's Dockerfile layer (ADR 0005); empty when it needs none."""
+        body = cast(JsonObj, self._json(self._http.get(f"/workflows/{name}/image-layer")))
+        return cast(str, body["layer"])
+
+    def get_repo(self, repo_id: str) -> JsonObj:
+        return cast(JsonObj, self._json(self._http.get(f"/repos/{repo_id}")))
+
+    def repo_image_layer(self, repo_id: str) -> str:
+        """The repo's Dockerfile layer (ADR 0005), read from its ``image_layer_file``; empty when
+        it declares none. Mirrors :meth:`workflow_image_layer`."""
+        body = cast(JsonObj, self._json(self._http.get(f"/repos/{repo_id}/image-layer")))
+        return cast(str, body["layer"])
+
+    def list_repos(self) -> list[JsonObj]:
+        return cast("list[JsonObj]", self._json(self._http.get("/repos")))
+
+    def list_tasks(self) -> list[JsonObj]:
+        return cast("list[JsonObj]", self._json(self._http.get("/tasks")))
+
+    def list_tasks_versioned(
+        self, *, since: int = 0, wait: float | None = None
+    ) -> tuple[list[JsonObj], int]:
+        """Block-until-change ``GET /tasks``: return ``(tasks, version)`` where ``version`` is the
+        store's change-feed cursor (the ``X-Tasks-Version`` header).
+
+        With ``wait`` set, the call long-polls — it parks on the server until a task changes past
+        ``since`` (the last version this caller saw) or ``wait`` seconds elapse, then returns the
+        current snapshot + version. Without ``wait`` it's an immediate snapshot + version. Feed the
+        returned ``version`` back as ``since`` on the next call to wait for the *next* change —
+        replacing a ``list_tasks()`` + ``sleep`` poll loop with one event-driven call.
+        """
+        params: dict[str, Any] = {"since": since}
+        if wait is None:
+            resp = self._http.get("/tasks", params=params)
+        else:
+            # Give the socket headroom past the server-side hold so the long-poll isn't cut short
+            # by httpx's default read timeout.
+            params["wait"] = wait
+            resp = self._http.get("/tasks", params=params, timeout=httpx.Timeout(wait + 10.0))
+        resp.raise_for_status()
+        version = int(resp.headers.get("X-Tasks-Version", "0"))
+        return cast("list[JsonObj]", resp.json()), version
+
+    def get_task(self, task_id: str) -> JsonObj:
+        return cast(JsonObj, self._json(self._http.get(f"/tasks/{task_id}")))
+
+    def list_transitions(self, task_id: str) -> list[str]:
+        return cast("list[str]", self._json(self._http.get(f"/tasks/{task_id}/transitions")))
+
+    def list_operations(self, task_id: str) -> dict[str, str]:
+        return cast("dict[str, str]", self._json(self._http.get(f"/tasks/{task_id}/operations")))
+
+    def list_states(self, task_id: str) -> list[str]:
+        """Every state of the task's workflow — the candidates for a free state-set."""
+        return cast("list[str]", self._json(self._http.get(f"/tasks/{task_id}/states")))
+
+    def list_skills(self, task_id: str) -> list[JsonObj]:
+        """The active workflow's in-container skills (the harness renders these to the CLI)."""
+        return cast("list[JsonObj]", self._json(self._http.get(f"/tasks/{task_id}/skills")))
+
+    def get_briefing(self, task_id: str) -> str:
+        """The agent's current-phase briefing (the user-prompt hook emits it into context)."""
+        body = cast(JsonObj, self._json(self._http.get(f"/tasks/{task_id}/briefing")))
+        return cast(str, body["briefing"])
+
+    def workflow_overview(self, task_id: str) -> str:
+        """The task's whole-workflow map (the launcher puts it in claude's system prompt)."""
+        body = cast(JsonObj, self._json(self._http.get(f"/tasks/{task_id}/workflow-overview")))
+        return cast(str, body["overview"])
+
+    def list_registrations(self, task_id: str) -> list[JsonObj]:
+        return cast("list[JsonObj]", self._json(self._http.get(f"/tasks/{task_id}/registrations")))
+
+    # -- repos / tasks ------------------------------------------------------------
+
+    def create_repo(
+        self,
+        repo_id: str,
+        name: str,
+        git_url: str,
+        default_base: str = "main",
+        *,
+        env_file: str | None = None,
+        capabilities: dict[str, Any] | None = None,
+        enabled_workflows: list[str] | None = None,
+        disabled_workflows: list[str] | None = None,
+    ) -> JsonObj:
+        body: dict[str, Any] = {
+            "id": repo_id, "name": name, "git_url": git_url, "default_base": default_base,
+            "env_file": env_file,
+            "enabled_workflows": enabled_workflows or [],
+            "disabled_workflows": disabled_workflows or [],
+        }
+        if capabilities is not None:
+            body["capabilities"] = capabilities
+        return cast(JsonObj, self._json(self._http.post("/repos", json=body)))
+
+    def update_repo(self, repo_id: str, **changes: Any) -> JsonObj:
+        """Partially update a repo (PATCH): only the supplied fields are sent, and the service
+        merges them onto the stored repo — so untouched fields (e.g. image_layer_file/capabilities)
+        are preserved."""
+        return cast(JsonObj, self._json(self._http.patch(f"/repos/{repo_id}", json=changes)))
+
+    def create_task(
+        self,
+        repo_id: str,
+        workflow: str,
+        memo: str | None = None,
+        *,
+        initial_prompt: str | None = None,
+    ) -> JsonObj:
+        body: JsonObj = {"repo_id": repo_id, "workflow": workflow, "memo": memo}
+        if initial_prompt is not None:
+            body["initial_prompt"] = initial_prompt
+        return cast(JsonObj, self._json(self._http.post("/tasks", json=body)))
+
+    def set_slug(self, task_id: str, slug: str) -> JsonObj:
+        return cast(JsonObj, self._json(self._http.put(f"/tasks/{task_id}/slug", json={"slug": slug})))
+
+    def set_url(self, task_id: str, url: str) -> JsonObj:
+        return cast(JsonObj, self._json(self._http.put(f"/tasks/{task_id}/url", json={"url": url})))
+
+    def set_tokens_used(self, task_id: str, tokens_used: int) -> JsonObj:
+        """Record cumulative tokens used by claude in this container (the Stop hook reports it)."""
+        return cast(JsonObj, self._json(self._http.put(
+            f"/tasks/{task_id}/tokens-used", json={"tokens_used": tokens_used})))
+
+    def set_token_estimate(self, task_id: str, token_estimate: int) -> JsonObj:
+        """Record the agent's forecast of the total tokens this task will consume (set in planning)."""
+        return cast(JsonObj, self._json(self._http.put(
+            f"/tasks/{task_id}/token-estimate", json={"token_estimate": token_estimate})))
+
+    def set_state(self, task_id: str, state: str) -> JsonObj:
+        """The user's free override — move the task to any state (bypasses the graph and gate)."""
+        return cast(JsonObj, self._json(self._http.put(f"/tasks/{task_id}/state", json={"state": state})))
+
+    def set_turn(self, task_id: str, turn: str) -> JsonObj:
+        """Flip who holds the turn (the in-container stop/user-prompt hooks call this)."""
+        return cast(JsonObj, self._json(self._http.put(f"/tasks/{task_id}/turn", json={"turn": turn})))
+
+    def set_blocked(self, task_id: str, blocked: bool) -> JsonObj:
+        """Set/clear the deliberate `blocked` marker (survives turn flips)."""
+        return cast(JsonObj, self._json(self._http.put(f"/tasks/{task_id}/blocked", json={"blocked": blocked})))
+
+    def set_governor(self, task_id: str, governor_task_id: str | None) -> JsonObj:
+        """Set or clear the governor task (the task that oversees this one)."""
+        return cast(JsonObj, self._json(self._http.put(
+            f"/tasks/{task_id}/governor", json={"governor_task_id": governor_task_id})))
+
+    def set_dependencies(self, task_id: str, dep_ids: list[str]) -> JsonObj:
+        """Replace the task's dependency list (task IDs that must complete first)."""
+        return cast(JsonObj, self._json(self._http.put(f"/tasks/{task_id}/dependencies", json={"dep_ids": dep_ids})))
+
+    def record_provisioning(self, task_id: str, branch: str, clone: str) -> JsonObj:
+        """Record the slug-named branch + per-task clone the session service created (ADR 0011)."""
+        body: JsonObj = {"branch": branch, "clone": clone}
+        return cast(JsonObj, self._json(self._http.put(f"/tasks/{task_id}/provisioning", json=body)))
+
+    def claim(self, task_id: str, runner_id: str) -> JsonObj:
+        """Claim an unclaimed task for `runner_id` (the spawn gate); 409 if another runner holds it."""
+        return cast(JsonObj, self._json(self._http.put(f"/tasks/{task_id}/claim", json={"runner_id": runner_id})))
+
+    def release(self, task_id: str) -> JsonObj:
+        """Release a task's claim (back to unclaimed) so it can be re-claimed / respawned."""
+        return cast(JsonObj, self._json(self._http.delete(f"/tasks/{task_id}/claim")))
+
+    def request_transition(
+        self, task_id: str, to_state: str, *, trigger: str | None = None, note: str | None = None
+    ) -> JsonObj:
+        body: JsonObj = {"to_state": to_state, "trigger": trigger, "note": note}
+        return cast(JsonObj, self._json(self._http.post(f"/tasks/{task_id}/transition", json=body)))
+
+    def apply_operation(self, task_id: str, operation: str) -> JsonObj:
+        """Apply a named core operation (e.g. advance/drop); the workflow resolves the target."""
+        return cast(JsonObj, self._json(self._http.post(f"/tasks/{task_id}/operations/{operation}")))
+
+    def resolve_responsibility(
+        self, task_id: str, key: str, status: Status, comment: str | None = None
+    ) -> JsonObj:
+        """Resolve one of the current state's promised responsibilities (MET or FAILED)."""
+        body: JsonObj = {"key": key, "status": status.value, "comment": comment}
+        return cast(JsonObj, self._json(self._http.post(f"/tasks/{task_id}/responsibilities", json=body)))
+
+    # -- artifacts ----------------------------------------------------------------
+
+    def list_artifacts(self, task_id: str) -> list[str]:
+        return cast(list[str], self._json(self._http.get(f"/tasks/{task_id}/artifacts")))
+
+    def put_artifact(self, task_id: str, name: str, content: bytes) -> None:
+        self._http.put(f"/tasks/{task_id}/artifacts/{name}", content=content).raise_for_status()
+
+    def get_artifact(self, task_id: str, name: str) -> bytes:
+        resp = self._http.get(f"/tasks/{task_id}/artifacts/{name}")
+        resp.raise_for_status()
+        return resp.content
+
+    # -- liveness -----------------------------------------------------------------
+
+    def register(self, task_id: str, container_id: str, runner_id: str | None = None) -> JsonObj:
+        return cast(
+            JsonObj,
+            self._json(
+                self._http.post(
+                    f"/tasks/{task_id}/registrations",
+                    json={"container_id": container_id, "runner_id": runner_id},
+                )
+            ),
+        )
+
+    def live(
+        self, task_id: str, *, container_id: str, runner_id: str | None = None
+    ) -> Generator[None, None, None]:
+        """Hold the long-lived liveness connection open, yielding once per server keepalive.
+
+        The open connection is the liveness signal: the service registers the container on connect
+        and removes it the instant this stream drops (clean ``close()``, or the process dying). The
+        caller iterates and may stop at any tick (closing the generator closes the connection — a
+        clean deregister); if the connection drops underneath, ``httpx`` raises, which the caller
+        treats as a cue to reconnect. Replaces the old register + heartbeat-loop + deregister.
+        """
+        with self._http.stream(
+            "GET",
+            f"/tasks/{task_id}/live",
+            params={"container_id": container_id, "runner_id": runner_id},
+            timeout=None,  # the connection is meant to stay open for the container's lifetime
+        ) as resp:
+            resp.raise_for_status()
+            for _ in resp.iter_lines():
+                yield None
+
+    def deregister(self, registration_id: str) -> None:
+        self._http.delete(f"/registrations/{registration_id}").raise_for_status()
+
+    # -- container lifecycle (the session service reports its spawn progress) -----
+
+    def report_lifecycle(
+        self, task_id: str, runner_id: str, phase: str, detail: str | None = None
+    ) -> JsonObj:
+        """Report this runner's latest spawn phase for a task (claiming → … → awaiting, or failed),
+        so the dashboard can surface the steps to becoming live. Cleared on claim release/reclaim."""
+        body: JsonObj = {"runner_id": runner_id, "phase": phase, "detail": detail}
+        return cast(JsonObj, self._json(self._http.put(f"/tasks/{task_id}/lifecycle", json=body)))
+
+    def clear_lifecycle(self, task_id: str) -> JsonObj:
+        """Drop a task's reported spawn phase (e.g. its container vanished → composes ``down``)."""
+        return cast(JsonObj, self._json(self._http.delete(f"/tasks/{task_id}/lifecycle")))
+
+    # -- host (runner) liveness + reclaim -----------------------------------------
+
+    def live_runner(self, runner_id: str, *, host: str | None = None) -> Generator[None, None, None]:
+        """Hold this host's liveness connection open, yielding once per server keepalive.
+
+        The host-liveness mirror of :meth:`live` one layer up: the open ``/runners/{id}/live`` stream
+        is the signal that this session-service daemon is alive. The task service marks the runner
+        live on connect and drops it from ``live_runners`` the instant this stream closes (a clean
+        ``close()`` or the daemon dying). The caller (the daemon) holds it for its whole life,
+        reconnecting if it drops underneath. ``host`` is the runner's hostname, passed as a query
+        param so the task service can surface it for the terminal supervisor's remote attach (M5).
+        """
+        params = {"host": host} if host is not None else {}
+        with self._http.stream(
+            "GET",
+            f"/runners/{runner_id}/live",
+            params=params,
+            timeout=None,  # the connection is meant to stay open for the daemon's lifetime
+        ) as resp:
+            resp.raise_for_status()
+            for _ in resp.iter_lines():
+                yield None
+
+    def live_runners(self) -> list[JsonObj]:
+        """The runners currently holding a host-liveness connection, each as ``{id, host}``."""
+        return cast(list[JsonObj], self._json(self._http.get("/runners")))
+
+    def get_runner(self, runner_id: str) -> JsonObj | None:
+        """The registration details for a single live runner, or ``None`` if not connected."""
+        resp = self._http.get(f"/runners/{runner_id}")
+        if resp.status_code == 404:
+            return None
+        return cast(JsonObj, self._json(resp))
+
+    def reclaim_runner(self, runner_id: str) -> list[JsonObj]:
+        """Release a (dead) runner's non-terminal claims so a healthy host respawns them."""
+        return cast(list[JsonObj], self._json(self._http.post(f"/runners/{runner_id}/reclaim")))

panopticon/container/__init__.py

@@ -0,0 +1,7 @@
+"""In-container code: the task-service client and the entrypoint protocol.
+
+This is the *only* package permitted to call an LLM (the agent runs here) — the
+determinism invariant exempts it. The entrypoint (``python -m panopticon.container``) runs the
+real slug + held-liveness-connection protocol; the agent step is still a stay-alive
+placeholder (no LLM yet), wired up in a later slice.
+"""

panopticon/container/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m panopticon.container`` — the task container's entrypoint."""
+
+from __future__ import annotations
+
+from panopticon.container.entrypoint import main
+
+if __name__ == "__main__":
+    main()

panopticon/container/agent.py

@@ -0,0 +1,211 @@
+"""The in-container **agent launcher** — what the runner's tmux pane runs.
+
+It prepares the agent CLI's surface from the active workflow (skills + turn-flip hooks), then
+`exec`s the agent. This is the only LLM-bearing path (the determinism invariant): the
+**bootstrap** is deterministic and unit-tested with fakes; the **launch** (real `claude`) is
+injectable and only runs for real in a `skipif`-gated integration / a live container — never in CI.
+
+Auth is the ``CLAUDE_CODE_OAUTH_TOKEN`` env var the runner injects from the repo's ``env_file``;
+the launcher does no credential wiring of its own.
+
+The container's entrypoint (`python -m panopticon.container`) holds the liveness connection;
+this runs alongside it in the tmux pane, so `tmux attach` reaches the live agent.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+
+import httpx
+
+from panopticon.client import TaskServiceClient
+from panopticon.container.config import update_json_config
+from panopticon.container.hooks import write_settings
+from panopticon.container.skills import write_commands, write_operation_commands
+from panopticon.core.models import Skill
+
+#: claude's main config file. Holds (besides per-container state) per-project trust acceptance.
+CONFIG_FILE = ".claude.json"
+
+
+#: Filename of the rendered MCP client config in the config dir; claude is pointed at it via
+#: ``--mcp-config`` so it connects to the task service's MCP server (task operations as tools).
+MCP_CONFIG_FILE = "panopticon-mcp.json"
+#: Filename of the rendered workflow overview (the whole-lifecycle map); claude gets its contents in
+#: the system prompt via ``--append-system-prompt`` so the agent always knows the workflow's shape.
+WORKFLOW_OVERVIEW_FILE = "workflow-overview.md"
+
+
+def render_skills(client: TaskServiceClient, task_id: str, home: Path) -> list[Path]:
+    """Render the active workflow's skills to the agent CLI surface (`.claude/commands/`)."""
+    skills = [Skill(**s) for s in client.list_skills(task_id)]
+    return write_commands(skills, home, task_id)
+
+
+def render_operations(client: TaskServiceClient, task_id: str, home: Path) -> list[Path]:
+    """Render the active workflow's available core operations (advance/drop/…) as slash-commands.
+
+    Reflects the *active workflow's* declared moves (ADR 0004), so a github-peer-reviewed and a
+    free-form container expose different operation commands — not a fixed global menu.
+    """
+    return write_operation_commands(client.list_operations(task_id), home, task_id)
+
+
+def write_mcp_config(config_dir: Path, service_url: str) -> Path:
+    """Write claude's MCP client config so it connects to the task service's MCP server.
+
+    A single ``panopticon`` HTTP server at ``<service_url>/mcp`` — the same control plane the
+    container already polls (``PANOPTICON_SERVICE_URL``, the in-container view). Returns the path,
+    which the launcher passes to ``claude --mcp-config``."""
+    config_dir.mkdir(parents=True, exist_ok=True)
+    path = config_dir / MCP_CONFIG_FILE
+    server = {"type": "http", "url": f"{service_url.rstrip('/')}/mcp"}
+    path.write_text(json.dumps({"mcpServers": {"panopticon": server}}, indent=2))
+    return path
+
+
+def write_workflow_overview(config_dir: Path, overview: str) -> Path | None:
+    """Write the whole-workflow map so the launcher can put it in claude's system prompt. Returns the
+    path, or ``None`` when there's no overview (skipped — the agent just gets the per-turn briefing)."""
+    if not overview.strip():
+        return None
+    config_dir.mkdir(parents=True, exist_ok=True)
+    path = config_dir / WORKFLOW_OVERVIEW_FILE
+    path.write_text(overview)
+    return path
+
+
+def trust_workspace(config_dir: Path, cwd: Path) -> Path:
+    """Pre-accept claude's "Do you trust the files in this folder?" dialog for ``cwd``.
+
+    The trust dialog is **separate** from the permission prompts ``--dangerously-skip-permissions``
+    skips (cf. claude issue #45298): it blocks on startup until accepted, and there's no operator in
+    the container to accept it. claude records acceptance per-project in ``<config>/.claude.json``
+    under ``projects[<cwd>].hasTrustDialogAccepted``; we seed exactly that (and mark onboarding done,
+    the other first-run blocker). Merge-in-place so we don't clobber config claude writes itself, and
+    idempotent. The path encoding is
+    undocumented internals — a safe degradation if it ever drifts is that the dialog reappears, which
+    only matters in an (already attended) interactive re-attach.
+    """
+    config = config_dir / CONFIG_FILE
+    with update_json_config(config) as data:
+        data["hasCompletedOnboarding"] = True
+        projects = data.setdefault("projects", {})
+        projects.setdefault(str(cwd), {})["hasTrustDialogAccepted"] = True
+    return config
+
+
+#: Sent to claude as the first message when a container restarts mid-task on the agent's turn.
+INTERRUPT_PROMPT = "You were interrupted. Continue."
+
+
+def _claude_argv(
+    config_dir: Path,
+    cwd: Path,
+    *,
+    initial_prompt: str | None = None,
+    turn: str | None = None,
+) -> list[str]:
+    """`claude` argv, resuming the project's most recent conversation if one exists.
+
+    The agent runs unattended in a throwaway container on a per-task clone, so it launches with
+    ``--dangerously-skip-permissions`` — there's no operator to answer permission prompts, and the
+    blast radius is the task's own checkout. claude keeps per-project transcripts under
+    ``<config>/projects/<cwd with '/' → '-'>``; when one is there we ``--continue`` it instead of
+    starting fresh. The config dir is a **per-task volume** (the runner mounts it; ``CONFIG_MOUNT``),
+    so this resumes both within a container's life and **across respawn/recreate** — claude history
+    persists even though the container layer is thrown away. If our path encoding ever misses
+    claude's, we simply start fresh — a safe degradation.
+
+    On a **first run** (no prior session) with an ``initial_prompt``, the prompt is appended as a
+    positional argument so claude processes it immediately. On a **resumed session** (``--continue``)
+    the ``initial_prompt`` is omitted — the agent is already mid-task. When the resumed session is
+    the agent's turn (``turn == "agent"``), :data:`INTERRUPT_PROMPT` is appended instead so the
+    agent automatically picks up where it left off rather than waiting for user input.
+    """
+    argv = ["claude", "--dangerously-skip-permissions"]
+    overview = config_dir / WORKFLOW_OVERVIEW_FILE
+    if overview.exists():  # the whole-workflow map → claude's system prompt (so it knows the shape)
+        argv += ["--append-system-prompt", overview.read_text()]
+    mcp_config = config_dir / MCP_CONFIG_FILE
+    if mcp_config.exists():  # connect to the task service's MCP server, and *only* it
+        argv += ["--mcp-config", str(mcp_config), "--strict-mcp-config"]
+    project = config_dir / "projects" / str(cwd).replace("/", "-")
+    if any(project.glob("*.jsonl")):
+        argv.append("--continue")
+        if turn == "agent":
+            argv.append(INTERRUPT_PROMPT)  # positional: auto-resume after container restart
+    elif initial_prompt:
+        argv.append(initial_prompt)  # positional: claude sends this as the agent's first message
+    return argv
+
+
+def _run_claude(config_dir: Path) -> None:  # pragma: no cover - real LLM; skipif-gated / live only
+    """Run `claude` (resuming the session if any) in the foreground; return when it exits.
+
+    Unlike an ``exec``, this returns control to :func:`main` when claude exits, so it can stop the
+    container (the task → down → respawn). claude inherits this pane's TTY (it's the interactive
+    surface ``tmux attach`` reaches)."""
+    initial_prompt = os.environ.get("PANOPTICON_INITIAL_PROMPT") or None
+    turn = os.environ.get("PANOPTICON_TASK_TURN") or None
+    argv = _claude_argv(config_dir, Path.cwd(), initial_prompt=initial_prompt, turn=turn)
+    subprocess.run(argv, env={**os.environ, "CLAUDE_CONFIG_DIR": str(config_dir)})
+
+
+def _stop_container() -> None:  # pragma: no cover - signals the real container's PID 1
+    """Stop the container by signalling the entrypoint (PID 1, the liveness connection). Both it and this
+    launcher run as the same unprivileged user, so the signal is permitted; PID 1 deregisters and
+    exits on SIGTERM, so the container stops → the task shows **down** → the operator respawns (`R`),
+    resuming from the per-task config volume."""
+    os.kill(1, signal.SIGTERM)
+
+
+def _default_client(service_url: str) -> TaskServiceClient:
+    return TaskServiceClient(httpx.Client(base_url=service_url))
+
+
+def main(
+    *,
+    client_factory: Callable[[str], TaskServiceClient] = _default_client,
+    home: Path | None = None,
+    launch: Callable[[Path], None] = _run_claude,
+    on_exit: Callable[[], None] = _stop_container,
+) -> None:
+    """Bootstrap the agent CLI from the active workflow (skills + turn-flip hooks), run the agent,
+    then stop the container when it exits. The CLI config dir is a per-task volume
+    (`<home>/.claude`); auth comes from the ``CLAUDE_CODE_OAUTH_TOKEN`` env var the runner injects.
+
+    When the agent (claude) exits, ``on_exit`` stops the container so the task goes **down** rather
+    than lingering live-but-unconnectable — the operator respawns it with `R` (history resumes)."""
+    env = os.environ
+    service_url = env["PANOPTICON_SERVICE_URL"]
+    client = client_factory(service_url)
+    config_dir = (home or Path.home()) / ".claude"
+    task_id = env["PANOPTICON_TASK_ID"]
+    runner_id = env.get("PANOPTICON_RUNNER_ID")
+    if not env.get("CLAUDE_CODE_OAUTH_TOKEN") and not env.get("ANTHROPIC_API_KEY"):
+        if runner_id:
+            client.report_lifecycle(
+                task_id,
+                runner_id,
+                phase="failed",
+                detail="No auth token — set CLAUDE_CODE_OAUTH_TOKEN in the repo's env_file (see docs/container-auth.md)",
+            )
+        return
+    render_skills(client, task_id, config_dir.parent)
+    render_operations(client, task_id, config_dir.parent)  # advance/drop/… as slash-commands
+    write_settings(config_dir.parent)  # turn-flip hooks → <home>/.claude/settings.json
+    write_mcp_config(config_dir, service_url)  # point claude at the task service's MCP server
+    write_workflow_overview(config_dir, client.workflow_overview(task_id))  # → system prompt (the map)
+    trust_workspace(config_dir, Path.cwd())  # pre-accept the trust dialog (no operator to)
+    launch(config_dir)  # the agent runs until it exits...
+    on_exit()  # ...then stop the container (task → down → respawn)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

panopticon/container/config.py

@@ -0,0 +1,28 @@
+"""The single place we touch claude's on-disk JSON config (`.claude.json`, `.claude/settings.json`).
+
+A **read-merge-write** so a caller states only the keys it cares about and never clobbers the
+rest: load whatever's already there (or start empty), let the caller mutate it in the ``with``
+block, then write it back with stable 2-space indentation on a clean exit. claude-specific, like
+its callers (M3 revisits for other CLIs).
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+
+@contextmanager
+def update_json_config(path: Path) -> Iterator[dict[str, Any]]:
+    """Yield ``path``'s JSON (``{}`` if absent) to mutate in place, then write it back on clean exit.
+
+    Creates ``path``'s parent directory if needed, so callers needn't pre-create the config dir. If
+    the ``with`` block raises, the file is left untouched — no half-written config.
+    """
+    data: dict[str, Any] = json.loads(path.read_text()) if path.exists() else {}
+    yield data
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2))