athena-claude-coder 0.4.1__py3-none-any.whl

athena_claude_coder/__init__.py

@@ -0,0 +1,17 @@
+"""In-guest Agent Protocol server for Athena coding tasks (ADR 0006).
+
+The Athena deep agent delegates repository work to a ``claude-coder`` async
+subagent. Its Agent Protocol calls arrive here — inside the tenant's Talos v2
+computer, on loopback port 46100 — through the agora coding-worker proxy,
+which is the authorization boundary. This package answers exactly the routes
+the pinned ``langgraph_sdk`` client calls and drives one ``ClaudeSDKClient``
+per thread against the checkout at ``/workspace/template``.
+
+State lives on the persisted tree (``/workspace/.claude-state``): a SQLite
+ledger of threads, runs, messages and Claude session ids, a per-run event
+log, and the task's owner key as a single 0600 file that the ``apiKeyHelper``
+script reads. Processes do not survive a computer suspend; the ledger does,
+so a restart marks orphaned runs ``interrupted`` with the session id intact.
+"""
+
+__version__ = "0.4.1"

athena_claude_coder/app.py

@@ -0,0 +1,492 @@
+"""FastAPI Agent Protocol subset — exactly the routes langgraph_sdk 0.4.2 calls.
+
+``deepagents.middleware.async_subagents`` drives ``threads.create``,
+``runs.create``, ``runs.get``, ``threads.get`` (C6) and ``runs.cancel``;
+``threads.get_state`` is kept for parity. ``PUT /internal/credential`` is the
+proxy's key-rotation hook and ``GET /ok`` the unauthenticated health probe.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import uuid
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Annotated, Any, Literal
+
+from fastapi import APIRouter, Depends, FastAPI, Header, HTTPException, Query, Response
+from pydantic import BaseModel, ConfigDict, Field
+
+from athena_claude_coder.auth import (
+    GUEST_TOKEN_HEADER,
+    guest_token_dependency,
+    token_matches,
+)
+from athena_claude_coder.runner import (
+    HARD_MAX_CONCURRENT_TASKS,
+    ClientFactory,
+    PidAlive,
+    RunnerBusyError,
+    ThreadRunner,
+    clamp_slots,
+)
+from athena_claude_coder.settings import CoderSettings, load_settings
+from athena_claude_coder.store import Store, ThreadExistsError, credential_name
+from athena_claude_coder.transcript import (
+    DEFAULT_LIMIT,
+    find_transcript,
+    read_transcript,
+)
+
+logger = logging.getLogger(__name__)
+
+SWEEP_EVERY_SECONDS = 600.0
+
+
+ENVELOPE_MISSING_DETAIL = "run config lacks the athena credential envelope"
+ENVELOPE_BASE_URL_DETAIL = "athena envelope lacks anthropic_base_url"
+EMPTY_TASK_DETAIL = "empty task"
+THREAD_NOT_FOUND_DETAIL = "thread not found"
+THREAD_EXISTS_DETAIL = "thread already exists"
+RUN_NOT_FOUND_DETAIL = "run not found"
+NO_SESSION_DETAIL = "no session to hand off"
+TRANSCRIPT_NOT_FOUND_DETAIL = "no transcript for this thread yet"
+
+
+class ThreadCreateBody(BaseModel):
+    """``POST /threads`` — what ``langgraph_sdk`` ``threads.create`` sends."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    thread_id: str | None = None
+    metadata: dict[str, Any] | None = None
+    if_exists: Literal["raise", "do_nothing"] = "raise"
+
+
+class HandoffRequestBody(BaseModel):
+    """``POST /internal/handoff/request`` — from the ``athena-claude`` launcher."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    thread_id: str | None = None
+    launcher_pid: int | None = Field(default=None, ge=1)
+    """The launcher's PID; lets a lock whose terminal died be recognised as stale."""
+    takeover: bool = False
+    """Re-mint the lease even though another launcher holds the session."""
+
+
+class HandoffReturnBody(BaseModel):
+    """``POST /internal/handoff/return`` — sent by the launcher when Claude exits."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    thread_id: str | None = None
+    claude_session_id: str | None = None
+    owner_since: str | None = None
+    """The lease the request handed out; a mismatch makes the return a no-op."""
+
+
+class CredentialBody(BaseModel):
+    """``PUT /internal/credential`` — the proxy's rotation push."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    owner_key: str = Field(min_length=1)
+    expires_at: str | int | float | None = None
+    budget_user_id: str = ""
+    anthropic_base_url: str = Field(min_length=1)
+    thread_id: str | None = None
+    """Also rotate this task's own credential file, not only the shared one."""
+
+
+def _task_text(run_input: Any) -> str:
+    """Join the user-authored message content of a LangGraph ``input``.
+
+    Accepts ``{"role": "user", "content": str}`` (what deepagents sends),
+    LangChain-style ``{"type": "human", ...}``, and list-of-blocks content.
+    """
+    if not isinstance(run_input, dict):
+        return ""
+    messages = run_input.get("messages")
+    if not isinstance(messages, list):
+        return ""
+    parts: list[str] = []
+    for message in messages:
+        if not isinstance(message, dict):
+            continue
+        kind = str(message.get("role") or message.get("type") or "user").lower()
+        if kind not in ("user", "human"):
+            continue
+        content = message.get("content", "")
+        if isinstance(content, str):
+            parts.append(content)
+        elif isinstance(content, list):
+            parts.extend(
+                str(block.get("text", ""))
+                for block in content
+                if isinstance(block, dict) and block.get("type", "text") == "text"
+            )
+    return "\n\n".join(part for part in parts if part)
+
+
+def _positive_int(raw: Any, *, default: int) -> int:
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        return default
+    return value if value >= 1 else default
+
+
+def create_app(
+    settings: CoderSettings | None = None,
+    *,
+    client_factory: ClientFactory | None = None,
+    alive: PidAlive | None = None,
+) -> FastAPI:
+    """Build the server; `client_factory` and `alive` let tests substitute fakes."""
+    s = settings or load_settings()
+    store = Store(
+        sqlite_path=s.sqlite_path,
+        credential_path=s.credential_path,
+        credential_meta_path=s.credential_meta_path,
+    )
+    runner = ThreadRunner(
+        settings=s, store=store, client_factory=client_factory, alive=alive
+    )
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+        s.state_dir.mkdir(parents=True, exist_ok=True)
+        await store.open()
+        # Processes never survive a computer suspend; live-looking rows are orphans.
+        orphans = await store.mark_orphans_interrupted()
+        if orphans:
+            logger.warning("marked %d orphaned run(s) interrupted at startup", orphans)
+        stale = await runner.sweep_stale_human_locks()
+        if stale:
+            logger.warning("released stale human lock(s) at startup: %s", stale)
+        if not s.guest_token:
+            logger.warning(
+                "ATHENA_CODING_WORKER_TOKEN is not set; "
+                "every route except /ok answers 503"
+            )
+        sweep = asyncio.create_task(
+            runner.sweep_loop(every_seconds=SWEEP_EVERY_SECONDS),
+            name="claude-coder-sweep",
+        )
+        try:
+            yield
+        finally:
+            sweep.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await sweep
+            await runner.shutdown()
+            await store.close()
+
+    app = FastAPI(
+        title="athena-claude-coder",
+        version=s.package_version,
+        docs_url=None,
+        redoc_url=None,
+        openapi_url=None,
+        lifespan=lifespan,
+    )
+    app.state.settings = s
+    app.state.store = store
+    app.state.runner = runner
+
+    @app.get("/ok")
+    async def ok(
+        token: Annotated[str | None, Header(alias=GUEST_TOKEN_HEADER)] = None,
+    ) -> dict[str, Any]:
+        # Unauthenticated on purpose — the ensure command probes it on loopback
+        # before the token exists — but never more than liveness for a caller
+        # without the token: whether a task is running, and on which thread,
+        # is for the proxy only. A wrong token still gets 200 here, not 401.
+        payload: dict[str, Any] = {"ok": True, "version": s.package_version}
+        if token_matches(expected=s.guest_token, presented=token):
+            slots = await runner.slot_state()
+            busy_thread = runner.busy_thread()
+            payload["busy"] = slots["busy"]
+            payload["active_thread_id"] = busy_thread
+            payload["active_thread_ids"] = slots["active_thread_ids"]
+            payload["slots"] = {"used": slots["used"], "total": slots["total"]}
+            # The owner lock of the thread that matters right now: the live one,
+            # else the human-held or most recently touched session — and which
+            # thread that is, so a human lock can be tied to its task once the
+            # handoff has drained the run and `active_thread_id` is gone.
+            session = (
+                await store.get_session(thread_id=busy_thread)
+                if busy_thread is not None
+                else await store.human_held_session() or await store.latest_session()
+            )
+            payload["owner"] = session["owner"] if session is not None else "none"
+            payload["owner_since"] = (
+                session["owner_since"] if session is not None else None
+            )
+            payload["owner_thread_id"] = (
+                session["thread_id"] if session is not None else None
+            )
+        return payload
+
+    protected = APIRouter(dependencies=[Depends(guest_token_dependency(s.guest_token))])
+
+    @protected.post("/threads")
+    async def create_thread(body: ThreadCreateBody | None = None) -> dict[str, Any]:
+        body = body or ThreadCreateBody()
+        thread_id = body.thread_id or str(uuid.uuid4())
+        try:
+            thread = await store.create_thread(
+                thread_id=thread_id,
+                metadata=body.metadata or {},
+                if_exists=body.if_exists,
+            )
+        except ThreadExistsError as exc:
+            raise HTTPException(status_code=409, detail=THREAD_EXISTS_DETAIL) from exc
+        logger.info("thread %s created", thread_id)
+        return dict(thread)
+
+    # (C6) deepagents reads the result through threads.get, NOT threads.get_state:
+    # GET /threads/{thread_id} returns the langgraph Thread shape with
+    # values.messages populated. Both routes exist; /state alone would 404 every
+    # check_async_task.
+    @protected.get("/threads/{thread_id}")
+    async def get_thread(thread_id: str) -> dict[str, Any]:
+        thread = await store.get_thread(thread_id=thread_id)
+        if thread is None:
+            raise HTTPException(status_code=404, detail=THREAD_NOT_FOUND_DETAIL)
+        return dict(thread)
+
+    @protected.get("/threads/{thread_id}/state")
+    async def get_state(thread_id: str) -> dict[str, Any]:
+        state = await store.get_thread_state(thread_id=thread_id)
+        if state is None:
+            raise HTTPException(status_code=404, detail=THREAD_NOT_FOUND_DETAIL)
+        return dict(state)
+
+    @protected.post("/threads/{thread_id}/runs")
+    async def create_run(thread_id: str, body: dict[str, Any]) -> dict[str, Any]:
+        if not await store.thread_exists(thread_id=thread_id):
+            raise HTTPException(status_code=404, detail=THREAD_NOT_FOUND_DETAIL)
+        # The envelope is injected by the proxy on every run create; it is the
+        # only channel for identity, credential and budget, never the prompt.
+        athena = ((body.get("config") or {}).get("configurable") or {}).get("athena")
+        if (
+            not isinstance(athena, dict)
+            or not str(athena.get("owner_key") or "").strip()
+        ):
+            raise HTTPException(status_code=400, detail=ENVELOPE_MISSING_DETAIL)
+        anthropic_base_url = str(athena.get("anthropic_base_url") or "").strip()
+        if not anthropic_base_url:
+            raise HTTPException(status_code=400, detail=ENVELOPE_BASE_URL_DETAIL)
+        task_text = _task_text(body.get("input"))
+        if not task_text.strip():
+            raise HTTPException(status_code=400, detail=EMPTY_TASK_DETAIL)
+        strategy = str(body.get("multitask_strategy") or "reject")
+        # The workspace policy's slot count rides in the envelope; the guest owns
+        # the hard ceiling. More than one slot means a git worktree per thread.
+        requested_cap = _positive_int(athena.get("max_concurrent_tasks"), default=1)
+        max_concurrent_tasks = clamp_slots(requested_cap)
+        if requested_cap > max_concurrent_tasks:
+            logger.warning(
+                "envelope asks for %d concurrent tasks; "
+                "the hard maximum is %d — clamping",
+                requested_cap,
+                HARD_MAX_CONCURRENT_TASKS,
+            )
+        run_id = str(uuid.uuid4())
+        # Claim the slot before writing anything: a create that loses the race
+        # must leave no credential, transcript entry or run row behind.
+        try:
+            await runner.reserve(
+                thread_id=thread_id,
+                run_id=run_id,
+                multitask_strategy=strategy,
+                max_concurrent_tasks=max_concurrent_tasks,
+            )
+        except RunnerBusyError as exc:
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        try:
+            # The shared file (human launcher, baked helper) and this task's own
+            # file (what the run's settings point Claude at).
+            for name in (None, credential_name(thread_id)):
+                await store.put_credential(
+                    owner_key=str(athena["owner_key"]),
+                    expires_at=str(athena.get("owner_key_expires_at") or ""),
+                    budget_user_id=str(athena.get("budget_user_id") or ""),
+                    anthropic_base_url=anthropic_base_url,
+                    name=name,
+                )
+            await store.append_message(
+                thread_id=thread_id, type="human", content=task_text
+            )
+            created = await store.create_run(
+                run_id=run_id, thread_id=thread_id, multitask_strategy=strategy
+            )
+            await runner.start(
+                thread_id=thread_id,
+                run_id=run_id,
+                task_text=task_text,
+                athena=athena,
+                multitask_strategy=strategy,
+                max_concurrent_tasks=max_concurrent_tasks,
+            )
+        except RunnerBusyError as exc:
+            # Unreachable while the reservation is honoured; kept so a regression
+            # surfaces as a 409 with an error row rather than a stray pending run.
+            runner.release(thread_id=thread_id, run_id=run_id)
+            await store.set_run_status(run_id=run_id, status="error", error=str(exc))
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        except BaseException:
+            runner.release(thread_id=thread_id, run_id=run_id)
+            raise
+        logger.info(
+            "run %s created on thread %s (strategy=%s, parent=%s)",
+            run_id,
+            thread_id,
+            strategy,
+            athena.get("thread_id"),
+        )
+        # The run task may already have flipped the row to `running`; report
+        # whatever the ledger says now.
+        run = await store.get_run(run_id=run_id) or created
+        return dict(run)
+
+    @protected.get("/threads/{thread_id}/runs/{run_id}")
+    async def get_run(thread_id: str, run_id: str) -> dict[str, Any]:
+        run = await store.get_run(run_id=run_id)
+        if run is None or run["thread_id"] != thread_id:
+            raise HTTPException(status_code=404, detail=RUN_NOT_FOUND_DETAIL)
+        return dict(run)
+
+    @protected.post("/threads/{thread_id}/runs/{run_id}/cancel", status_code=204)
+    async def cancel_run(
+        thread_id: str,
+        run_id: str,
+        wait: Annotated[bool, Query()] = False,
+        action: Annotated[str, Query()] = "interrupt",
+    ) -> Response:
+        run = await store.get_run(run_id=run_id)
+        if run is None or run["thread_id"] != thread_id:
+            raise HTTPException(status_code=404, detail=RUN_NOT_FOUND_DETAIL)
+        # `action=rollback` would delete the run and its checkpoint on a
+        # LangGraph server; here every cancel is an interrupt — the workspace
+        # is the tenant's and is never deleted (proposal A2). `wait` is
+        # implicit: cancel returns after the bounded drain.
+        logger.info("run %s cancel (wait=%s, action=%s)", run_id, wait, action)
+        await runner.cancel(thread_id=thread_id, run_id=run_id)
+        return Response(status_code=204)
+
+    @protected.put("/internal/credential", status_code=204)
+    async def put_credential(body: CredentialBody) -> Response:
+        names: list[str | None] = [None]
+        if body.thread_id:
+            names.append(credential_name(body.thread_id))
+        for name in names:
+            await store.put_credential(
+                owner_key=body.owner_key,
+                expires_at="" if body.expires_at is None else str(body.expires_at),
+                budget_user_id=body.budget_user_id,
+                anthropic_base_url=body.anthropic_base_url,
+                name=name,
+            )
+        logger.info("credential rotated (budget_user=%s)", body.budget_user_id)
+        return Response(status_code=204)
+
+    async def _resolve_thread(requested: str | None, *, for_return: bool) -> str:
+        """Explicit thread id, else the live thread, else the latest session."""
+        if requested:
+            if not await store.thread_exists(thread_id=requested):
+                raise HTTPException(status_code=404, detail=THREAD_NOT_FOUND_DETAIL)
+            return requested
+        busy_thread = runner.busy_thread()
+        if busy_thread is not None:
+            return busy_thread
+        session = (await store.human_held_session() if for_return else None) or (
+            await store.latest_session()
+        )
+        if session is None:
+            raise HTTPException(status_code=404, detail=NO_SESSION_DETAIL)
+        return session["thread_id"]
+
+    @protected.post("/internal/handoff/request")
+    async def handoff_request(body: HandoffRequestBody | None = None) -> dict[str, Any]:
+        body = body or HandoffRequestBody()
+        thread_id = await _resolve_thread(body.thread_id, for_return=False)
+        try:
+            result = await runner.handoff_request(
+                thread_id=thread_id,
+                launcher_pid=body.launcher_pid,
+                takeover=body.takeover,
+            )
+        except RunnerBusyError as exc:
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        row = result["session"]
+        logger.info(
+            "thread %s: handoff request served (owner=%s, acquired=%s)",
+            thread_id,
+            row["owner"],
+            result["acquired"],
+        )
+        return {
+            "thread_id": row["thread_id"],
+            "claude_session_id": row["claude_session_id"],
+            "cwd": row["cwd"],
+            "owner": row["owner"],
+            "owner_since": row["owner_since"],
+            "acquired": result["acquired"],
+        }
+
+    @protected.post("/internal/handoff/return")
+    async def handoff_return(body: HandoffReturnBody | None = None) -> dict[str, Any]:
+        body = body or HandoffReturnBody()
+        thread_id = await _resolve_thread(body.thread_id, for_return=True)
+        row = await runner.handoff_return(
+            thread_id=thread_id,
+            claude_session_id=body.claude_session_id,
+            lease=body.owner_since,
+        )
+        logger.info(
+            "thread %s: handoff returned (session=%s)",
+            thread_id,
+            row["claude_session_id"],
+        )
+        return {"thread_id": row["thread_id"], "owner": row["owner"]}
+
+    # (P3.1) Agora reads a task's Claude turns through the guest — the transcript
+    # Claude Code writes under CLAUDE_CONFIG_DIR — because the session bridge has
+    # no credential a guest could hold. Read-only, never under the runner lock,
+    # parsed in a worker thread so a large file never blocks the server.
+    @protected.get("/threads/{thread_id}/transcript")
+    async def get_transcript(
+        thread_id: str,
+        after: Annotated[int, Query()] = 0,
+        limit: Annotated[int, Query()] = DEFAULT_LIMIT,
+    ) -> dict[str, Any]:
+        if not await store.thread_exists(thread_id=thread_id):
+            raise HTTPException(status_code=404, detail=THREAD_NOT_FOUND_DETAIL)
+        session = await store.get_session(thread_id=thread_id)
+        claude_session_id = session["claude_session_id"] if session else None
+        if not claude_session_id:
+            raise HTTPException(status_code=404, detail=TRANSCRIPT_NOT_FOUND_DETAIL)
+        path = find_transcript(
+            config_dir=s.claude_config_dir,
+            session_id=claude_session_id,
+            cwd=session["cwd"] if session else None,
+        )
+        if path is None:
+            raise HTTPException(status_code=404, detail=TRANSCRIPT_NOT_FOUND_DETAIL)
+        page = await asyncio.to_thread(
+            read_transcript, path=path, after=after, limit=limit
+        )
+        return {
+            "thread_id": thread_id,
+            "claude_session_id": claude_session_id,
+            "total": page["total"],
+            "entries": page["entries"],
+        }
+
+    app.include_router(protected)
+    return app

athena_claude_coder/auth.py

@@ -0,0 +1,45 @@
+"""The guest shared secret (C7).
+
+Anyone who can mint a router grant for port 46100 reaches this server, so a
+grant alone is not enough: the proxy's ensure command exports a random
+``ATHENA_CODING_WORKER_TOKEN`` into the server's environment and the proxy
+sends the same value on every request. ``GET /ok`` stays open — the ensure
+command curls it on loopback before the token exists.
+
+Fail closed: with no token configured, every protected route answers 503
+rather than letting the comparison degrade to "anything matches empty".
+"""
+
+from __future__ import annotations
+
+import hmac
+from collections.abc import Awaitable, Callable
+from typing import Annotated
+
+from fastapi import Header, HTTPException
+
+GUEST_TOKEN_HEADER = "X-Athena-Coding-Worker-Token"
+
+TOKEN_NOT_CONFIGURED_DETAIL = "guest token not configured"
+TOKEN_INVALID_DETAIL = "invalid guest token"
+
+
+def token_matches(*, expected: str | None, presented: str | None) -> bool:
+    """Constant-time equality; ``False`` whenever either side is unset or empty."""
+    if not expected or not presented:
+        return False
+    return hmac.compare_digest(presented.encode("utf-8"), expected.encode("utf-8"))
+
+
+def guest_token_dependency(expected: str | None) -> Callable[..., Awaitable[None]]:
+    """Build the FastAPI dependency that guards every route except ``/ok``."""
+
+    async def require_guest_token(
+        token: Annotated[str | None, Header(alias=GUEST_TOKEN_HEADER)] = None,
+    ) -> None:
+        if not expected:
+            raise HTTPException(status_code=503, detail=TOKEN_NOT_CONFIGURED_DETAIL)
+        if not token_matches(expected=expected, presented=token):
+            raise HTTPException(status_code=401, detail=TOKEN_INVALID_DETAIL)
+
+    return require_guest_token

athena_claude_coder/main.py

@@ -0,0 +1,113 @@
+"""Console entry point: ``athena-claude-coder serve`` and ``--version``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+from collections.abc import MutableMapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from athena_claude_coder import __version__
+from athena_claude_coder.settings import CoderSettings, load_settings
+from athena_claude_coder.store import write_private_file
+
+logger = logging.getLogger(__name__)
+
+SCRUBBED_ENV_VARS: tuple[str, ...] = (
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    "CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR",
+)
+"""Credential variables the server must never hand to a Claude process (C9)."""
+
+API_KEY_HELPER_PATH = "/opt/athena/bin/athena-claude-key"
+"""Installed by the bake; prints ``<state_dir>/credential`` and nothing else."""
+
+
+def scrub_credential_env(environ: MutableMapping[str, str] | None = None) -> list[str]:
+    """Remove every credential variable from `environ`; return the names removed.
+
+    (C9) ``ClaudeAgentOptions.env`` is merged *over* ``os.environ`` and cannot
+    unset a key. The guest boot env carries the per-computer gateway key and
+    pm2 hands it to this process, so without this pop every task would bill
+    the computer's uncapped key instead of its own task budget. The SDK reads
+    ``os.environ`` at connect time, so scrubbing once here covers every client
+    the runner builds.
+    """
+    env = os.environ if environ is None else environ
+    removed: list[str] = []
+    for name in SCRUBBED_ENV_VARS:
+        if env.pop(name, None) is not None:
+            removed.append(name)
+    return removed
+
+
+def claude_settings_document() -> dict[str, Any]:
+    """The ``--settings`` file every Claude session is launched with."""
+    return {
+        "apiKeyHelper": API_KEY_HELPER_PATH,
+        "env": {"ENABLE_TOOL_SEARCH": "true"},
+    }
+
+
+def write_claude_settings(*, settings: CoderSettings) -> Path:
+    path = settings.claude_settings_path
+    write_private_file(
+        path=path, content=json.dumps(claude_settings_document(), indent=2)
+    )
+    return path
+
+
+def serve(*, settings: CoderSettings | None = None) -> None:
+    """Scrub the inherited credential env, write settings.json, run uvicorn."""
+    scrubbed = scrub_credential_env()
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s"
+    )
+    if scrubbed:
+        logger.info("scrubbed inherited credential env: %s", ", ".join(scrubbed))
+    s = settings or load_settings()
+    s.state_dir.mkdir(parents=True, exist_ok=True)
+    write_claude_settings(settings=s)
+
+    import uvicorn
+
+    from athena_claude_coder.app import create_app
+
+    logger.info(
+        "athena-claude-coder %s serving on %s:%d (state=%s, repo=%s)",
+        s.package_version,
+        s.bind_host,
+        s.port,
+        s.state_dir,
+        s.repo_dir,
+    )
+    uvicorn.run(create_app(s), host=s.bind_host, port=s.port, log_level="info")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="athena-claude-coder",
+        description="In-guest Agent Protocol server for Athena coding tasks",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    subcommands = parser.add_subparsers(dest="command", required=True)
+    subcommands.add_parser("serve", help="run the server on the loopback port")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "serve":
+        serve()
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())