@rryando/arcs 3.11.0 → 4.0.0

package/dist/web-server/routes/sessions.js

@@ -5,24 +5,32 @@
  * attached to a project. All mutations go through the locked session-store,
  * so the opencode discovery bridge and the web UI cannot clobber each other.
  *
- * `POST /sessions/:id/message` is the one route that reaches outside the store:
- * it proxies a prompt into the live runtime (opencode) or queues it for the
- * session to collect itself (claude-code). Every route here is browser-facing
- * and therefore already behind the global loopback-only `secureLocalRequest`
- * middleware — no per-route auth.
+ * Two routes reach outside the store, and they partition the session space
+ * rather than overlapping: `POST /sessions/:id/message` DELIVERS a prompt to a
+ * session something else drives (live injection for opencode, a queue the
+ * terminal drains for claude-code), while `POST /sessions/:id/turns` RUNS a
+ * headless `claude -p` turn against a thread ARCS owns. Every route here is
+ * browser-facing and therefore already behind the global loopback-only
+ * `secureLocalRequest` middleware — no per-route auth.
  */
 import { randomUUID } from "node:crypto";
-import { stat, unlink } from "node:fs/promises";
+import { open, readFile, stat, unlink } from "node:fs/promises";
 import { resolve } from "node:path";
 import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
 import { z } from "zod";
-import { appendReferenceTurn, appendSessionTurn, mirrorSessionTranscript, readSessionTurns, sessionTranscriptPath, } from "../../utils/claude-transcript.js";
+import { appendReferenceTurn, appendSessionTurn, readSessionTurns, referenceTurnText, sessionTranscriptPath, } from "../../utils/claude-transcript.js";
 import { DagError } from "../../utils/errors.js";
 import { readJsonSafe } from "../../utils/json.js";
-import { createSession, deleteSession, enqueueSessionMessage, getSession, listSessions, SESSION_LINKED_NODE_TYPES, SESSION_RUNTIME_TYPES, SESSION_STATUSES, updateSession, upsertSession, } from "../../utils/session-store.js";
-import { isRunLive, runClaudeJob } from "../claude-runner.js";
+import { beginSessionRun, canQueue, createSession, deleteSession, deriveSessionPhase, enqueueSessionMessage, getSession, listSessions, SESSION_LINKED_NODE_TYPES, SESSION_RUNTIME_TYPES, SESSION_STATUSES, sessionRunClaim, settleSessionRun, updateSession, upsertSession, } from "../../utils/session-store.js";
+import { normalizeIdentifier } from "../../utils/slug.js";
+import { isRunLive, liveRunPid, resolveTimeoutMs, runClaudeJob, } from "../claude-runner.js";
 import { createOpencodeSession, readOpencodeConfig, sendOpencodeMessage, } from "../opencode-client.js";
-import { parseBody, requireProjectDir, respond } from "../respond.js";
+import { buildPermissionArgv, RUN_INTENTS } from "../permission-policy.js";
+import { buildStagedEnvironment, planStageRefresh, renderReferences } from "../prompt-assembly.js";
+import { fail, parseBody, requireProjectDir, respond } from "../respond.js";
+import { foldRunEventLog, pruneRunEventLogs, RUN_EVENT_LOG_MAX_BYTES, runEventLogPath, } from "../run-event-log.js";
+import { isProcessAlive, reconcileSessionPhases } from "../session-reconciler.js";
 export const sessionsRoute = new Hono();
 const createSessionSchema = z.object({
     runtimeType: z.enum(SESSION_RUNTIME_TYPES),
@@ -42,11 +50,21 @@ const updateSessionSchema = z.object({
     linkedNodeType: z.enum(SESSION_LINKED_NODE_TYPES).nullable().optional(),
     linkedNodeId: z.string().nullable().optional(),
 });
-/** A document section the caller is pointing the session at. When present, the
- *  delivery call is followed by an ARCS-authored reference turn in the session's
- *  transcript sidecar (see appendReferenceTurn). Shared by POST /message and
- *  POST /run so both routes accept byte-identical reference payloads. */
-const sessionReferenceSchema = z.object({
+/**
+ * The `doc` variant — a markdown document section.
+ *
+ * FROZEN, field for field: this is the only reference shape that existed before
+ * the union, so every reference turn already on disk carries exactly these keys
+ * and nothing else. Widening or tightening `section`/`source` here would strand
+ * those sidecars, so the union adds a tag and touches nothing else. The tag is
+ * REQUIRED here, exactly as on the pointer variants: a legacy body carrying no
+ * tag never reaches this schema untagged, because `sessionReferenceSchema`'s
+ * preprocess fills it in before the union runs. That preprocess is the whole
+ * legacy mechanism — a default here would be a dead second one implying the tag
+ * is optional at this boundary when it cannot be.
+ */
+const docReferenceSchema = z.object({
+    type: z.literal("doc"),
     section: z.object({
         depth: z.number(),
         text: z.string(),
@@ -62,22 +80,107 @@ const sessionReferenceSchema = z.object({
         id: z.string().optional(),
     }),
 });
+/** The `file` variant — a line range in a workspace file. `headRev` rides along
+ *  so a later diff can tell whether the file moved under the agent. */
+const fileReferenceSchema = z.object({
+    type: z.literal("file"),
+    path: z.string().min(1),
+    startLine: z.number().int().min(1),
+    endLine: z.number().int().min(1),
+    excerpt: z.string().optional(),
+    headRev: z.string().optional(),
+});
+/** The `node` variant — a DAG entity, with no text slice of its own. */
+const nodeReferenceSchema = z.object({
+    type: z.literal("node"),
+    kind: z.enum(["task", "plan", "knowledge"]),
+    id: z.string().min(1),
+});
+/**
+ * Something the caller is pointing the session at. When present, the delivery
+ * call is followed by an ARCS-authored reference turn in the session's
+ * transcript sidecar (see `appendReference`). Shared by POST /message and POST
+ * /turns so both routes accept byte-identical reference payloads.
+ *
+ * A discriminated union on `type`, so an unknown variant is REJECTED (400
+ * INVALID_BODY naming the three tags) rather than coerced into the nearest
+ * shape. The one accommodation is the preprocess below: a body with no `type`
+ * at all can only be a pre-union doc reference — every caller and every stored
+ * turn predating the union is exactly that — so the tag is filled in before the
+ * union sees it. Nothing else is inferred: an explicitly tagged body is matched
+ * on its own tag and fails on its own merits.
+ */
+const sessionReferenceSchema = z
+    .preprocess((value) => typeof value === "object" && value !== null && !Array.isArray(value) && !("type" in value)
+    ? { ...value, type: "doc" }
+    : value, z.discriminatedUnion("type", [docReferenceSchema, fileReferenceSchema, nodeReferenceSchema]))
+    .superRefine((reference, ctx) => {
+    // A backwards slice would render a nonsense pointer into the prompt. Checked
+    // here rather than on the variant because a discriminated-union option must
+    // stay a plain object schema.
+    if (reference.type === "file" && reference.endLine < reference.startLine) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["endLine"],
+            message: `endLine (${reference.endLine}) must be >= startLine (${reference.startLine})`,
+        });
+    }
+});
 const sendMessageSchema = z.object({
     message: z.string().min(1),
     reference: sessionReferenceSchema.optional(),
 });
-/** Payload for POST /sessions/:id/run — a headless `claude -p` targeting mode.
- *  `threadId` is the stable-mode thread to reuse; when absent (and the
- *  referenced session is not itself an ARCS-owned thread) one is minted. */
-const runClaudeMessageSchema = z.object({
-    mode: z.enum(["resume", "oneshot", "stable"]),
+/**
+ * Payload for POST /sessions/:id/turns — one turn of a headless conversation.
+ *
+ * `intent` is a PERMISSION POLICY, not a delivery mode: it selects the tool set
+ * and permission mode `buildPermissionArgv` emits (`ask` → read-only + plan,
+ * `change` → the edit surface + acceptEdits) and decides nothing else. Native
+ * delivery (`POST /:id/message`) has no intent at all — ARCS authors no argv
+ * there, so the two are orthogonal and never collapse into one enum.
+ *
+ * `threadRef` names an ARCS thread RECORD to continue — never a claude uuid,
+ * and never an observed session (that is what adoption is for). `refs` are the
+ * turn's references: they render into the user-facing prompt AND land on the
+ * sidecar. `guards` is validated and then deliberately ignored here; the
+ * change-intent preflight that reads it is a separate task, and accepting the
+ * key now keeps that task from being a breaking payload change.
+ */
+const turnSchema = z.object({
+    intent: z.enum(RUN_INTENTS),
     message: z.string().min(1),
-    threadId: z.string().optional(),
-    reference: sessionReferenceSchema.optional(),
+    refs: z.array(sessionReferenceSchema).optional(),
+    threadRef: z.string().min(1).optional(),
+    guards: z.record(z.unknown()).optional(),
 });
 const createOpencodeSessionSchema = z.object({
     title: z.string().min(1).optional(),
 });
+/**
+ * Records a delivered reference on the session's transcript sidecar. Shared by
+ * POST /message and POST /turns so both write the same record for the same
+ * payload.
+ *
+ * A `doc` reference writes exactly the fields this route has always written —
+ * `text`, `ts`, `section`, `source`, in that order — so the serialized line is
+ * byte-identical to one written before the union existed: no tag is added to the
+ * DOC record.
+ *
+ * That is NOT "the tag never reaches disk". The pointer kinds have no historical
+ * fields, so they ride `ref` whole — discriminator included — and a stored
+ * `ref: {type: "file"|"node", ...}` is exactly what makes a pointer turn
+ * re-readable as its own variant. The tag is on disk there, correctly and
+ * necessarily; it is only the frozen doc record that stays untagged.
+ */
+async function appendReference(projectDir, sessionId, reference) {
+    await appendReferenceTurn(projectDir, sessionId, {
+        text: referenceTurnText(reference),
+        ts: new Date().toISOString(),
+        ...(reference.type === "doc"
+            ? { section: reference.section, source: reference.source }
+            : { ref: reference }),
+    });
+}
 function sessionDirectory(session) {
     const directory = session.metadata?.directory;
     return typeof directory === "string" && directory ? directory : undefined;
@@ -106,6 +209,11 @@ async function primaryWorkspacePath(projectDir, slug) {
     }
     return directory;
 }
+/** A metadata slot read back as a real string, or `undefined`. A hand-edited
+ *  index (and a cleared key, written as `""`) can carry anything here. */
+function metadataString(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
 function parseFilters(status, runtimeType) {
     const filters = {};
     if (status && SESSION_STATUSES.includes(status)) {
@@ -116,71 +224,240 @@ function parseFilters(status, runtimeType) {
     }
     return filters;
 }
+// The state this module decides from — `sessionState()` and the predicates over
+// it — is NOT defined here. It lives in `src/shared/session-vocabulary.ts`, the
+// zero-import leaf `web/src/components/SessionStatusBadge.tsx` imports too, so
+// an affordance the client offers and the answer this server gives are computed
+// by the same function rather than by two copies of it. The reachable
+// (status, phase) pairs are enumerated there.
+/**
+ * Epoch-ms deadline the claimed run will be killed at, when the spawn site
+ * persisted one. Validated rather than trusted — a hand-edited index can carry
+ * anything under this key.
+ */
+function runDeadlineAt(session) {
+    const value = session.metadata?.runDeadlineAt;
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
 /**
- * Mode-1 write-back (T005): the callback the route registers on runClaudeJob,
- * invoked by the runner after the headless child fully exits — on every outcome
- * (success/error/timeout/killed).
- *
- * - resume: mirrors the resumed session's runtime transcript into its sidecar
- *   via the persisted metadata.transcriptPath (hook-events T004 persists it at
- *   its checkpoints). The path is re-read fresh from the store — it may have
- *   been updated between the 202 and the run's exit. An absent path is a no-op;
- *   mirrorSessionTranscript is offset-idempotent and never throws, so repeated
- *   write-backs never duplicate and failures are inert.
- * - oneshot/stable: never mirror — their sidecars are appendSessionTurn-owned.
- *   On a success outcome the captured reply is appended as an assistant turn
- *   (every reply lands in the sidecar); error/timeout outcomes append nothing.
+ * The claimed run's own deadline, standing in for the store's fixed heartbeat
+ * TTL.
+ *
+ * `RUN_HEARTBEAT_TTL_MS` is sized to the runner's 10-minute DEFAULT_TIMEOUT_MS,
+ * but `resolveTimeoutMs` honours an explicit `timeoutMs` and
+ * `ARCS_CLAUDE_RUN_TIMEOUT_MS`, and nothing refreshes `heartbeatAt` mid-run —
+ * so past minute 10 a perfectly healthy 30-minute run derives `idle`, and the
+ * reconciler cannot rescue it because it early-returns on any non-`running`
+ * derivation and never probes the pid. The spawn site is the only place that
+ * knows the timeout, so it persists the resulting deadline on the claim
+ * (`metadata.runDeadlineAt`) and it is read back here as that run's TTL:
+ *
+ *  - inside the deadline the pid decides, exactly as the reconciler would;
+ *  - past it the claim is not evidence of anything — the runner has already
+ *    SIGTERMed then SIGKILLed the child — so it demotes to `idle`.
+ *
+ * Only ever consulted for a record that still holds a claim AND carries a
+ * deadline; anything else (including every claim written before this field
+ * existed) keeps the reconciler's own answer untouched.
+ */
+function runDeadlinePhase(session, phase, now) {
+    // A terminal status outranks every liveness signal — a session that is over
+    // is never reopened here.
+    if (phase === "failed" || phase === "ended")
+        return phase;
+    const deadlineAt = runDeadlineAt(session);
+    if (sessionRunClaim(session) === undefined || deadlineAt === undefined)
+        return phase;
+    if (now > deadlineAt)
+        return "idle";
+    const pid = session.currentRunPid;
+    // No pid to probe (the spawn produced none) — the deadline stands alone.
+    if (typeof pid !== "number")
+        return "running";
+    return isProcessAlive(pid) ? "running" : "idle";
+}
+/**
+ * Attaches the reconciled phase to each session of ONE response.
+ *
+ * `reconcileSessionPhases` takes the project's whole index and runs AT MOST one
+ * `claude agents --json` probe for it, so this is never one probe per session —
+ * and the detail route pays exactly what the list does. At most, because the
+ * probe is lazy: a request whose records all answer from their own evidence
+ * (terminal, idle, or holding a run claim) spawns no subprocess at all. A record
+ * that appeared between the two reads is not in the reconciler's answer and
+ * falls back to its own store-derived phase.
+ */
+async function withPhases(projectDir, sessions) {
+    const now = Date.now();
+    const reconciled = new Map((await reconcileSessionPhases(projectDir, { now })).map((view) => [view.sessionId, view.phase]));
+    return sessions.map((session) => ({
+        ...session,
+        phase: runDeadlinePhase(session, reconciled.get(session.normalizedId) ?? deriveSessionPhase(session, { now }), now),
+    }));
+}
+/** Existing `metadata.run` as a mergeable object — anything else reads empty. */
+function runMetadata(session) {
+    const run = session.metadata?.run;
+    if (typeof run !== "object" || run === null || Array.isArray(run))
+        return {};
+    return run;
+}
+/**
+ * Claude's own words for the two ways a thread's seed decision can be wrong,
+ * observed on claude 2.1.223's flag validation (exit 1, before any network
+ * call): `--session-id <id>` on an id it already knows, and `--resume <id>` on
+ * one it does not.
+ *
+ * FRAGILE BY CONSTRUCTION, and stated as such rather than hidden: these are a
+ * CLI's human-facing stderr strings, not a stable contract, and a claude patch
+ * release can reword either without notice. Each branch is therefore pinned by
+ * a test driving the literal message, and each is a REPAIR rather than a
+ * behaviour: a message that stops matching costs the self-heal, never the run.
+ */
+const THREAD_SEED_CONFLICT_PATTERN = /already in use/i;
+const THREAD_UNKNOWN_PATTERN = /No conversation found with session ID/i;
+/**
+ * Reads the child's error text as EVIDENCE about the thread's seed decision and
+ * repairs the record from it.
+ *
+ * `metadata.threadInitialized` is persisted at SPAWN — its honest meaning is
+ * "ARCS has already handed this uuid to `--session-id`", which the route knows
+ * with certainty the moment it builds argv and which survives a server crash
+ * where the settle never runs. That alone closes the wedge (a run that times
+ * out after claude registered the uuid no longer re-seeds forever). These two
+ * branches close the remainder, where the flag and claude disagree:
+ *
+ *  - "already in use" — claude HAS the id ARCS thought it had not handed over.
+ *    The flag was a false negative; set it and the next turn resumes.
+ *  - "No conversation found with session ID" — claude does NOT have the id ARCS
+ *    resumed. Clearing the flag alone would re-seed the SAME uuid, so the uuid
+ *    is re-minted with it. `adoptedClaudeSessionId` is cleared in the same
+ *    write: it is the id claude could not find, and keeping it would re-issue
+ *    the identical doomed `--resume` on every later turn — the exact wedge this
+ *    repair exists to prevent. `adoptedFrom` stays, because the record's
+ *    provenance is still true and never reaches argv.
+ */
+function repairThreadSeed(record) {
+    const error = typeof record.error === "string" ? record.error : "";
+    if (error === "")
+        return { metadata: {} };
+    if (THREAD_SEED_CONFLICT_PATTERN.test(error)) {
+        return { errorCode: "THREAD_SEED_CONFLICT", metadata: { threadInitialized: true } };
+    }
+    if (THREAD_UNKNOWN_PATTERN.test(error)) {
+        return {
+            errorCode: "THREAD_UNKNOWN_TO_CLAUDE",
+            metadata: {
+                threadInitialized: false,
+                claudeSessionId: randomUUID(),
+                adoptedClaudeSessionId: "",
+            },
+        };
+    }
+    return { metadata: {} };
+}
+/**
+ * The write-back the route registers on runClaudeJob, invoked by the runner
+ * after the headless child fully exits — on every outcome (success / error /
+ * timeout / killed).
+ *
+ * Every write target is an ARCS-owned thread, so there is exactly one sidecar
+ * discipline: `appendSessionTurn`-owned, never mirrored. The run's own event log
+ * folds down first (assistant text plus one turn per tool_use, every turn tagged
+ * with the run id so a second fold is a no-op). Only when that fold produced no
+ * assistant text — no log, an empty log, a child that spoke only through the
+ * terminal `result` envelope — does the captured reply get appended as an
+ * assistant turn on a success outcome; error/timeout outcomes append nothing.
+ *
+ * The observed session an adopted thread was forked from is never touched here:
+ * `ctx.writeTarget` is the fork, and the fork's transcript is its own.
  *
  * Every path finalizes metadata.run with the settled record (pid/startedAt/
  * mode plus endedAt/outcome/error/replyChars) so the panel shows the true
  * result. Best-effort by contract: the runner swallows any error thrown here,
  * so a failed write-back never surfaces on the accepted 202.
+ *
+ * The run CLAIM is released here too, by `settleSessionRun` rather than by a
+ * hand-assembled `metadata.run` write: releasing the claim and stamping the
+ * outcome is one read-modify-write under the store lock, guarded by the run id
+ * so a run that has already been superseded never settles a newer one out from
+ * under it.
  */
 async function writeBackRun(projectDir, ctx, record) {
-    if (ctx.mode === "resume") {
-        let target = ctx.writeTarget;
-        try {
-            target = await getSession(projectDir, ctx.writeTarget.normalizedId);
-        }
-        catch {
-            // Session deleted mid-run — fall back to the write-target captured at 202.
-        }
-        const transcriptPath = target.metadata?.transcriptPath;
-        if (typeof transcriptPath === "string" && transcriptPath !== "") {
-            await mirrorSessionTranscript(projectDir, ctx.writeTarget.normalizedId, transcriptPath);
-        }
-    }
-    else if (record.outcome === "success" && record.replyText !== undefined) {
-        // Modes 2/3 on success: the captured reply lands in the sidecar as an
-        // assistant turn (minted in the shared negative id space after the user
-        // turn and any reference). Error/timeout outcomes append nothing.
+    // Never settle a claim that is still being written (see ctx.claimed).
+    await ctx.claimed;
+    // Fold the run's durable event log down into the sidecar first. Idempotent by
+    // its own output — every folded turn carries the run id, and a run already
+    // represented there folds to nothing.
+    const fold = await foldRunEventLog(projectDir, ctx.writeTarget.normalizedId, ctx.runId);
+    if (!fold.assistantTextFolded && record.outcome === "success" && record.replyText !== undefined) {
+        // Nothing in the log spoke for this run (no log at all, or only tool
+        // turns): the captured reply lands in the sidecar as an assistant turn,
+        // minted in the shared negative id space after the user turn and any
+        // reference. Tagged with the run id too, so it is covered by the same
+        // no-second-fold guard. Error/timeout outcomes append nothing.
         await appendSessionTurn(projectDir, ctx.writeTarget.normalizedId, {
             type: "assistant",
             text: record.replyText,
+            run: ctx.runId,
         });
     }
-    const run = {
-        pid: record.pid,
-        startedAt: record.startedAt,
-        mode: ctx.mode,
-        ...(record.endedAt !== undefined && { endedAt: record.endedAt }),
+    // Bounded retention: the log that just settled is the newest, so it always
+    // survives and the sessions dir stays capped at RUN_EVENT_LOG_RETENTION logs
+    // per session however many runs it accumulates.
+    await pruneRunEventLogs(projectDir, ctx.writeTarget.normalizedId);
+    const repair = repairThreadSeed(record);
+    // ONE write: the outcome, everything the runner measured, the seed-decision
+    // repair, and the claim release. `endedAt` rides the record so the run is
+    // stamped with the moment the CHILD exited, not the moment this write ran.
+    //
+    // Leaving any of it to a follow-up `updateSession` is what made the repair
+    // unsound, because the RUNNER frees its concurrency slot (endRun) BEFORE it
+    // fires this write-back: from the moment the claim is released the next turn
+    // is accepted, so a repair one write later is both readable in the gap — the
+    // record reads settled-and-failed while still carrying the seed state that
+    // failed it, and the next turn re-issues the very `--resume` claude just
+    // refused — and able to land AFTER that turn claimed the record, clobbering
+    // its live metadata.run and re-minting its uuid mid-flight. The `runId` guard
+    // is only honest inside the settle's own lock.
+    await settleSessionRun(projectDir, ctx.writeTarget.normalizedId, {
+        runId: ctx.runId,
         outcome: record.outcome,
         ...(record.error !== undefined && { error: record.error }),
-        ...(record.replyChars !== undefined && { replyChars: record.replyChars }),
-    };
-    const runMetadata = { run };
-    if (ctx.mode === "stable" && ctx.firstStableSpawn && record.outcome === "success") {
-        runMetadata.threadInitialized = true;
-    }
-    await updateSession(projectDir, {
-        id: ctx.writeTarget.normalizedId,
-        metadata: runMetadata,
+        ...(record.endedAt !== undefined && { endedAt: record.endedAt }),
+        // Everything the RUNNER measured, which no claim could have known at spawn:
+        // the pid/startedAt the child actually reported, the run's intent, and the
+        // stream observations — time-to-first-token and wire-format drift are only
+        // readable after the fact if they reach disk.
+        run: {
+            pid: record.pid,
+            startedAt: record.startedAt,
+            mode: ctx.intent,
+            // Typed, so the panel can act on the failure rather than render opaque
+            // CLI text at the user.
+            ...(repair.errorCode !== undefined && { errorCode: repair.errorCode }),
+            ...(record.replyChars !== undefined && { replyChars: record.replyChars }),
+            ...(record.firstTokenAt !== undefined && { firstTokenAt: record.firstTokenAt }),
+            ...(record.skippedLines !== undefined && { skippedLines: record.skippedLines }),
+            ...(record.eventLogLines !== undefined && { eventLogLines: record.eventLogLines }),
+            // Whether the log is the WHOLE stream. `eventLogLines` alone cannot say:
+            // a log capped on its first chunk reports zero lines, the same number a
+            // child that never spoke reports. Anything that later tails this file by
+            // offset reads this before it treats the file as complete.
+            ...(record.eventLogTruncated !== undefined && {
+                eventLogTruncated: record.eventLogTruncated,
+            }),
+            // A log that could not be written is REPORTED here, never thrown: the run
+            // itself already succeeded or failed on its own merits.
+            ...(record.eventLogError !== undefined && { eventLogError: record.eventLogError }),
+        },
+        ...(Object.keys(repair.metadata).length > 0 && { metadata: repair.metadata }),
     });
 }
 sessionsRoute.get("/api/p/:slug/sessions", async (c) => respond(c, async () => {
     const projectDir = requireProjectDir(c.req.param("slug"));
     const sessions = await listSessions(projectDir, parseFilters(c.req.query("status"), c.req.query("runtimeType")));
-    return { sessions };
+    return { sessions: await withPhases(projectDir, sessions) };
 }));
 sessionsRoute.post("/api/p/:slug/sessions", async (c) => respond(c, async () => {
     const projectDir = requireProjectDir(c.req.param("slug"));
@@ -218,7 +495,9 @@ sessionsRoute.post("/api/p/:slug/sessions/opencode/new", async (c) => respond(c,
 }, 201));
 sessionsRoute.get("/api/p/:slug/sessions/:id", async (c) => respond(c, async () => {
     const projectDir = requireProjectDir(c.req.param("slug"));
-    return getSession(projectDir, c.req.param("id"));
+    const session = await getSession(projectDir, c.req.param("id"));
+    const [view] = await withPhases(projectDir, [session]);
+    return view;
 }));
 sessionsRoute.patch("/api/p/:slug/sessions/:id", async (c) => respond(c, async () => {
     const projectDir = requireProjectDir(c.req.param("slug"));
@@ -235,6 +514,19 @@ sessionsRoute.patch("/api/p/:slug/sessions/:id", async (c) => respond(c, async (
  * Both answer with the updated session, so the caller can tell them apart by
  * `messageQueue` rather than by branching on `runtimeType` itself.
  *
+ * Queued delivery needs a terminal session to drain the queue, so it is gated
+ * on the `canQueue` capability derived from the session's persisted origin. An
+ * `arcs`-origin thread has nothing attached that would ever read the queue:
+ * accepting the message would make this route a black hole that answers 200 and
+ * silently drops the prompt, so it is refused outright and the caller is sent to
+ * `POST /turns`, which actually drives such a thread.
+ *
+ * The refusal holds by CONSTRUCTION rather than by a second check: `canQueue`
+ * reads `origin`, and every record `POST /turns` writes to is `arcs`-origin.
+ * The two routes therefore partition the session space — native delivery serves
+ * exactly the observed sessions the headless path refuses to write to, which is
+ * why `native` is a delivery channel and not a run intent.
+ *
  * A `reference` body field appends an ARCS-authored reference turn to the
  * session's transcript sidecar, but only after delivery has succeeded — a
  * failed send must never leave a dangling reference behind. The append is a
@@ -246,6 +538,11 @@ sessionsRoute.post("/api/p/:slug/sessions/:id/message", async (c) => respond(c,
     const session = await getSession(projectDir, c.req.param("id"));
     let updated;
     if (session.runtimeType === "claude-code") {
+        if (!canQueue(session)) {
+            throw new DagError("SESSION_QUEUE_UNSUPPORTED", `cannot queue a message for session "${session.normalizedId}": it is an ARCS-owned ` +
+                `thread with no terminal session attached, so nothing would ever drain the queue — ` +
+                `drive it with POST /api/p/<slug>/sessions/${session.normalizedId}/turns instead.`);
+        }
         // Queued, not sent: `lastMessageAt` stays untouched until the session
         // actually drains this at a checkpoint.
         updated = await enqueueSessionMessage(projectDir, session.normalizedId, message);
@@ -262,143 +559,340 @@ sessionsRoute.post("/api/p/:slug/sessions/:id/message", async (c) => respond(c,
     }
     // Delivery succeeded (or was accepted into the queue) — record the
     // reference turn against the session's transcript sidecar, carrying the
-    // section/source payload verbatim so the web UI can render click-through.
+    // payload verbatim so the web UI can render click-through.
     if (reference !== undefined) {
-        await appendReferenceTurn(projectDir, session.normalizedId, {
-            text: reference.text,
-            ts: new Date().toISOString(),
-            section: reference.section,
-            source: reference.source,
-        });
+        await appendReference(projectDir, session.normalizedId, reference);
     }
     return updated;
 }));
 /**
- * Starts a headless `claude -p` job in one of three targeting modes and answers
- * 202 with the write-target session — the record the run's transcript and reply
- * land on. The 202 is the acceptance: the run proceeds out-of-band in the
- * runner, whose exit-time write-back (T005) then settles the run — finalizing
- * `metadata.run` with the outcome on every path and, for resume mode, mirroring
- * the resumed session's transcript into its sidecar.
- *
- * - resume: the referenced session must be a claude-code session that is not
- *   currently active; the run resumes its runtime thread in the session's own
- *   directory.
- * - oneshot: the run targets a deterministic ARCS-owned session
- *   (`arcs-oneshot-<slug>`) recreated idempotently on every call, in the
- *   project's primary workspace.
- * - stable: the run targets a persistent ARCS-owned thread (`arcs-thread-<slug>-
- *   <uuid4>` minted once then reused) so a conversation accumulates in one
- *   sidecar; the first successful spawn seeds the thread (`--session-id`),
- *   later spawns resume it (`--resume` + `--session-id`).
- *
- * Modes 2/3 append the user turn (and optional reference) to the write-target
- * sidecar immediately — the panel shows the prompt before the run ends, with
- * delivery-first ordering (user turn before reference). Mode 1 never appends:
- * its transcript write-back happens at exit (T005).
+ * The thread record `threadRef` names, or `undefined` when the index answers
+ * that there is no such record.
  *
- * Concurrency: one live run per write-target. The runner's beginRun is the
- * atomic claim; the read-only isRunLive probe here answers the common
- * overlapping case with a proper 409 before anything is appended or spawned
- * (a rare race between probe and claim is still refused by the runner itself).
+ * `getSession`'s `ITEM_NOT_FOUND` is NOT evidence of absence: `readSessionIndex`
+ * folds an unreadable index into an empty one (`readJsonSafe` swallows every
+ * error class), so an EACCES or an EISDIR on a live index arrives wearing the
+ * deleted record's code. Minting on that answer would upsert a fresh ARCS
+ * thread over a name that already belongs to something else — and worse, would
+ * seed a uuid onto a thread claude already knows. So a not-found is believed
+ * only when a DIRECT read of the index says this record is not listed (or that
+ * there is no index at all); anything else is reported as unavailable and the
+ * caller retries.
  */
-sessionsRoute.post("/api/p/:slug/sessions/:id/run", async (c) => respond(c, async () => {
-    const slug = c.req.param("slug");
-    const projectDir = requireProjectDir(slug);
-    const { mode, message, threadId, reference } = await parseBody(c, runClaudeMessageSchema);
-    const session = await getSession(projectDir, c.req.param("id"));
-    let writeTarget;
-    let dir;
-    let runThreadId;
-    let firstStableSpawn = false;
-    if (mode === "resume") {
-        if (session.runtimeType !== "claude-code") {
-            throw new DagError("CLAUDE_RUN_TARGET_INVALID", `cannot resume session "${session.normalizedId}": only claude-code sessions can be run headlessly`);
-        }
-        if (session.status === "active") {
-            throw new DagError("CLAUDE_SESSION_ACTIVE", `cannot resume session "${session.normalizedId}": the session is still active`);
+async function readThreadRecord(projectDir, threadRef) {
+    try {
+        return await getSession(projectDir, threadRef);
+    }
+    catch (err) {
+        if (!(err instanceof DagError) || err.code !== "ITEM_NOT_FOUND")
+            throw err;
+    }
+    if (await sessionIndexAnswered(projectDir, normalizeIdentifier(threadRef)))
+        return undefined;
+    throw new DagError("SESSION_INDEX_UNAVAILABLE", `cannot tell whether thread "${threadRef}" exists — the session index did not answer for ` +
+        `it, and minting a second record over that name would re-seed a uuid claude may already ` +
+        `hold. Retry once the index reads.`);
+}
+/**
+ * Resolves the record this turn writes to, the uuid claude is told, and whether
+ * this spawn claims that uuid or continues it.
+ *
+ * Three branches, and only these three:
+ *
+ *  1. `threadRef` — the caller names an ARCS thread RECORD to continue. It may
+ *     name one that does not exist yet (a fresh thread is minted for it), but
+ *     never an observed session: that is refused rather than quietly claimed,
+ *     because ARCS writing run state onto a record with a live terminal behind
+ *     it is exactly what adoption exists to avoid.
+ *  2. the referenced session IS an ARCS thread — continue it.
+ *  3. ADOPTION — the referenced session is one ARCS merely observes, so a NEW
+ *     thread is minted and its first spawn forks the observed session:
+ *     `--resume <observed uuid> --session-id <fresh uuid> --fork-session`.
+ *     Probed on claude 2.1.223: the fork inherits the observed context and
+ *     writes a SEPARATE transcript, leaving the original untouched — so
+ *     adoption preserves continuity without needing to read a claude-chosen id
+ *     back off the stream.
+ *
+ * Adoption is deliberately NOT idempotent: every turn addressed to the observed
+ * session forks it again, from whatever state the human has left it in. The
+ * 202 names the write target, and continuing THAT thread (by id, or by
+ * `threadRef`) is how a conversation accumulates in one sidecar.
+ */
+async function resolveTurnTarget(projectDir, slug, session, threadRef) {
+    let existing;
+    let threadId;
+    /** Provenance, written only on the upsert that MINTS an adopted thread. */
+    let adoptedFrom;
+    let adoptedClaudeSessionId;
+    if (threadRef !== undefined) {
+        threadId = threadRef;
+        existing = await readThreadRecord(projectDir, threadRef);
+        if (existing !== undefined && existing.origin !== "arcs") {
+            throw new DagError("TURN_THREAD_NOT_OWNED", `cannot continue thread "${existing.normalizedId}": it is a session ARCS observes, not ` +
+                `an ARCS-owned thread — omit threadRef to fork it into one instead`);
         }
-        writeTarget = session;
-        dir = sessionDirectory(session) ?? (await primaryWorkspacePath(projectDir, slug));
+    }
+    else if (session.origin === "arcs") {
+        threadId = session.runtimeSessionId;
+        existing = session;
     }
     else {
-        dir = await primaryWorkspacePath(projectDir, slug);
-        if (mode === "oneshot") {
-            writeTarget = await upsertSession(projectDir, {
-                runtimeType: "claude-code",
-                runtimeSessionId: `arcs-oneshot-${slug}`,
-                metadata: { control: "arcs-owned", directory: dir },
-            });
-        }
-        else {
-            // stable — reuse the referenced session's own thread when ARCS owns
-            // it, otherwise take the payload threadId or mint a fresh one.
-            const thread = (session.metadata?.control === "arcs-owned" && session.runtimeSessionId) ||
-                threadId ||
-                `arcs-thread-${slug}-${randomUUID()}`;
-            runThreadId = thread;
-            writeTarget = await upsertSession(projectDir, {
-                runtimeType: "claude-code",
-                runtimeSessionId: thread,
-                metadata: { control: "arcs-owned", directory: dir },
-            });
-            firstStableSpawn = writeTarget.metadata?.threadInitialized !== true;
+        if (session.runtimeType !== "claude-code") {
+            throw new DagError("CLAUDE_RUN_TARGET_INVALID", `cannot drive session "${session.normalizedId}" headlessly: only a claude-code session ` +
+                `carries a claude thread to fork`);
         }
+        threadId = `arcs-thread-${slug}-${randomUUID()}`;
+        adoptedFrom = session.normalizedId;
+        adoptedClaudeSessionId = session.runtimeSessionId;
+    }
+    const meta = existing?.metadata;
+    const persistedUuid = metadataString(meta?.claudeSessionId);
+    // The SEED DECISION. `threadInitialized` means "ARCS has already handed this
+    // uuid to --session-id" and is persisted at spawn, so a thread whose first
+    // run timed out (or whose server died) resumes on the next turn instead of
+    // re-seeding an id claude has already registered.
+    const seeding = meta?.threadInitialized !== true || persistedUuid === undefined;
+    const claudeSessionId = persistedUuid ?? randomUUID();
+    // A fork is only ever the spawn that CLAIMS the new id; once the thread is
+    // seeded it continues on its own uuid and the observed session is done with.
+    const forkFrom = seeding
+        ? (adoptedClaudeSessionId ?? metadataString(meta?.adoptedClaudeSessionId))
+        : undefined;
+    // HARD SAFETY ASSERTION. `--resume A --session-id A --fork-session` is
+    // ACCEPTED by claude 2.1.223 — exit 0, empty stderr — and appends to the
+    // ORIGINAL transcript, hijacking the human's live terminal thread (measured:
+    // the source grew 11 -> 20 lines). There is no error to notice it by, so the
+    // only thing standing between a corrupt record and a hijacked session is this
+    // check. Unreachable from a freshly minted uuid; reachable from a hand-edited
+    // or half-repaired index, which is precisely why it is enforced here.
+    if (forkFrom !== undefined && forkFrom === claudeSessionId) {
+        throw new DagError("CLAUDE_FORK_ID_COLLISION", `refusing to fork thread "${threadId}": its claude session id and the session it would ` +
+            `fork are the same id ("${forkFrom}"), which claude accepts silently and appends to the ` +
+            `ORIGINAL session — re-mint metadata.claudeSessionId before running this thread again`);
+    }
+    const dir = sessionDirectory(existing ?? session) ?? (await primaryWorkspacePath(projectDir, slug));
+    const writeTarget = await upsertSession(projectDir, {
+        runtimeType: "claude-code",
+        runtimeSessionId: threadId,
+        // Create-only in the store: an upsert never rewrites provenance, so this
+        // marks a freshly minted thread and is inert on one that already exists.
+        origin: "arcs",
+        metadata: {
+            control: "arcs-owned",
+            directory: dir,
+            claudeSessionId,
+            ...(adoptedFrom !== undefined && { adoptedFrom, adoptedClaudeSessionId }),
+        },
+    });
+    return {
+        writeTarget,
+        claudeSessionId,
+        ...(forkFrom !== undefined && { forkFrom }),
+        seeding,
+        dir,
+    };
+}
+/**
+ * The turn's user-facing prompt: the message, then its rendered reference block.
+ *
+ * References ride the PROMPT, never `--append-system-prompt`. The system tier is
+ * the STABLE one — byte-identical across turns is what makes the prompt cache
+ * pay — while a reference belongs to the turn that sent it and to no other.
+ * Staging them would break the cache on every send and leave the pointer in the
+ * conversation long after the turn it was meant for.
+ */
+function turnPrompt(message, refs) {
+    const block = renderReferences(refs ?? []);
+    return block === "" ? message : `${message}\n\n${block}`;
+}
+/**
+ * Targeting tokens for one spawn — everything before the permission segment.
+ *
+ * Exactly three shapes, and the fork's ORDER is the probed one:
+ *  - fresh thread seed:  -p <prompt> --session-id <new> --output-format json
+ *  - thread resume:      -p <prompt> --resume <own> --output-format json
+ *  - observed adoption:  -p <prompt> --resume <observed> --session-id <new>
+ *                        --fork-session --output-format json
+ *
+ * `--session-id` alongside `--resume` without `--fork-session` exits 1 at flag
+ * validation ("--session-id can only be used with --continue or --resume if
+ * --fork-session is also specified"), so the three tokens are never split.
+ */
+function turnTargetingArgv(prompt, target) {
+    const argv = ["-p", prompt];
+    if (target.seeding && target.forkFrom !== undefined) {
+        argv.push("--resume", target.forkFrom, "--session-id", target.claudeSessionId, "--fork-session");
+    }
+    else if (target.seeding) {
+        argv.push("--session-id", target.claudeSessionId);
     }
+    else {
+        argv.push("--resume", target.claudeSessionId);
+    }
+    argv.push("--output-format", "json");
+    return argv;
+}
+/**
+ * One turn of a headless `claude -p` conversation. Answers 202 with the run's
+ * id, the stream to tail it on, and the record it writes to — the acceptance,
+ * not the result: the run proceeds out-of-band in the runner, whose exit-time
+ * write-back settles it.
+ *
+ * WHAT THE CALLER CHOOSES is an INTENT (`ask` | `change`), never a targeting
+ * mode. Where the turn lands is derived from the record it is addressed to (see
+ * `resolveTurnTarget`): an ARCS thread continues, an observed session is forked
+ * into a new one. Delivery is the orthogonal axis and lives on the other route —
+ * `POST /:id/message` queues into a terminal session, for which ARCS authors no
+ * argv and an intent would mean nothing.
+ *
+ * ARGV OWNERSHIP, which is the safety property: every tool and permission token
+ * comes from `buildPermissionArgv` and this route builds none. It keeps only
+ * the targeting tokens above, and the permission segment is appended LAST —
+ * `--tools` is variadic (it eats following tokens until the next dash-leading
+ * one) and `--append-system-prompt` consumes exactly one following token, so a
+ * segment placed before `-p` would swallow the prompt or the staged text. The
+ * staged environment reaches the child through that segment's
+ * `stagedSystemPrompt` slot and nowhere else; a second direct push would emit
+ * the flag twice.
+ *
+ * The user turn (and one reference turn per `refs` entry) is appended to the
+ * write target's sidecar immediately, so the panel shows the prompt before the
+ * run ends, with delivery-first ordering.
+ *
+ * Staged environment (W2): a spawn that STARTS a conversation — a fresh seed and
+ * an adoption fork alike, since the forked context has never seen ARCS's block —
+ * always carries it; a spawn that CONTINUES one carries it only on a restage.
+ *
+ * Concurrency: one live run per write-target. The runner's beginRun is the
+ * atomic claim; the read-only isRunLive probe here answers the common
+ * overlapping case with a proper 409 before anything is appended or spawned.
+ */
+sessionsRoute.post("/api/p/:slug/sessions/:id/turns", async (c) => respond(c, async () => {
+    const slug = c.req.param("slug");
+    const projectDir = requireProjectDir(slug);
+    // `guards` is validated by the schema and deliberately not read here —
+    // the change-intent preflight that consumes it is a separate task.
+    const { intent, message, refs, threadRef } = await parseBody(c, turnSchema);
+    const session = await getSession(projectDir, c.req.param("id"));
+    const target = await resolveTurnTarget(projectDir, slug, session, threadRef);
+    const { writeTarget, dir, seeding } = target;
     // One live run per write-target — refuse before appending anything.
     if (isRunLive(writeTarget.normalizedId)) {
         throw new DagError("CLAUDE_RUN_IN_PROGRESS", `a claude run for "${writeTarget.normalizedId}" is already in progress`);
     }
-    if (mode !== "resume") {
-        await appendSessionTurn(projectDir, writeTarget.normalizedId, {
-            type: "user",
-            text: message,
-        });
-        if (reference !== undefined) {
-            await appendReferenceTurn(projectDir, writeTarget.normalizedId, {
-                text: reference.text,
-                ts: new Date().toISOString(),
-                section: reference.section,
-                source: reference.source,
-            });
-        }
+    await appendSessionTurn(projectDir, writeTarget.normalizedId, {
+        type: "user",
+        text: message,
+    });
+    for (const reference of refs ?? []) {
+        await appendReference(projectDir, writeTarget.normalizedId, reference);
     }
     // NOTE: no "--cwd" flag — claude >= 2.x rejects it ("error: unknown
     // option '--cwd'"), settling every headless run as outcome:error. The
     // spawn applies the working directory via options.cwd below instead.
-    let argv;
-    if (mode === "resume") {
-        argv = ["-p", message, "--resume", session.runtimeSessionId, "--output-format", "json"];
-    }
-    else if (mode === "oneshot") {
-        argv = ["-p", message, "--output-format", "json"];
-    }
-    else {
-        const thread = runThreadId;
-        argv = firstStableSpawn
-            ? ["-p", message, "--session-id", thread, "--output-format", "json"]
-            : ["-p", message, "--resume", thread, "--session-id", thread, "--output-format", "json"];
-    }
+    const argv = turnTargetingArgv(turnPrompt(message, refs), target);
+    // --- Staged environment (W2) -----------------------------------------
+    //
+    // Keyed on the WRITE TARGET, never on the referenced session: the write
+    // target is the record the run lands on and the record `metadata.stage`
+    // is persisted to, so the fingerprint compared next turn describes the
+    // same node the text was built from.
+    const stageOpts = { workspaceRoot: dir };
+    const refresh = await planStageRefresh(projectDir, slug, writeTarget, stageOpts);
+    const staged = refresh.staged ??
+        (seeding
+            ? await buildStagedEnvironment(projectDir, slug, writeTarget, {
+                ...stageOpts,
+                // The same watermark planStageRefresh stamps with, so this record
+                // stays mtime-comparable even though this path never persists it.
+                now: refresh.probedAt,
+            })
+            : undefined);
+    // LAST, and the only source of tool/permission tokens. The staged text is
+    // handed over as this segment's value slot rather than pushed directly —
+    // one flag, one emitter.
+    argv.push(...buildPermissionArgv({
+        intent,
+        ...(staged !== undefined && { stagedSystemPrompt: staged.text }),
+    }));
+    // The run's own ceiling, resolved HERE so the deadline persisted with the
+    // claim is the same number the runner arms its kill timer with (it
+    // prefers this over its own env/default lookup).
+    const runId = randomUUID();
+    const timeoutMs = resolveTimeoutMs(undefined, process.env);
+    // Persisted next to the claim rather than inside metadata.run, which
+    // `beginSessionRun` replaces wholesale: as sibling keys these cannot be
+    // clobbered by the claim, nor the claim by them.
+    await updateSession(projectDir, {
+        id: writeTarget.normalizedId,
+        metadata: {
+            runDeadlineAt: Date.now() + timeoutMs,
+            // AT SPAWN, not at settle. The uuid is in argv from this point on, so
+            // "ARCS has handed it over" is true now and stays true through a
+            // timeout, an error, or a server that dies before the settle runs —
+            // the three ways the old settle-time write left a thread re-seeding
+            // forever into "Session ID … is already in use".
+            ...(seeding && { threadInitialized: true }),
+            // Written EXACTLY when the refresh asks for it. On the cheap exit
+            // nothing was rebuilt, so re-stamping the record would move the very
+            // watermark the next turn's freshness decision is made against.
+            ...(refresh.persist && refresh.stage ? { stage: refresh.stage } : {}),
+        },
+    });
+    // Claim the record BEFORE the child exists: from here on, a server that
+    // dies mid-run leaves a claim behind rather than an invisible orphan, and
+    // the startup sweep (settleOrphanedRunsOnStartup) is what settles it.
+    await beginSessionRun(projectDir, writeTarget.normalizedId, { runId });
+    // Gate for the write-back: it must not settle (and release) the claim
+    // while the pid write below is still in flight.
+    let claimComplete = () => { };
+    const claimed = new Promise((resolveClaim) => {
+        claimComplete = resolveClaim;
+    });
     // Fire-and-forget: the run proceeds out-of-band. The runner invokes the
     // registered write-back after the child fully exits (it resolves on
     // `close`) on every outcome path; write-back failures are swallowed by
-    // the runner, so a failed mirror/finalize never surfaces on the accepted
-    // 202. The trailing catch is defensive — the runner never rejects.
+    // the runner, so a failed finalize never surfaces on the accepted 202.
+    // The trailing catch is defensive — the runner never rejects.
     runClaudeJob({
         argv,
         cwd: dir,
+        timeoutMs,
         writeTargetKey: writeTarget.normalizedId,
-        onSettled: (record) => writeBackRun(projectDir, { mode, writeTarget, firstStableSpawn }, record),
+        // The SAME runId the claim above persisted as currentRunId — the log's
+        // filename and the session record can never name different runs.
+        eventLog: { projectDir, sessionId: writeTarget.normalizedId, runId },
+        onSettled: (record) => writeBackRun(projectDir, { intent, writeTarget, runId, claimed }, record),
     }).catch(() => {
         // Best-effort — the write-back lives inside the runner's onSettled.
     });
+    // runClaudeJob spawns synchronously (nothing is awaited before its
+    // beginRun), so the child's pid is readable right here — and the claim it
+    // lands on is the one written above, never a later run's. `undefined`
+    // means the spawn produced no live run at all and `null` means it
+    // produced no pid; neither is something to persist, and the claim then
+    // stands on its heartbeat/deadline alone.
+    try {
+        const pid = liveRunPid(writeTarget.normalizedId);
+        if (typeof pid === "number") {
+            await beginSessionRun(projectDir, writeTarget.normalizedId, { runId, pid });
+        }
+    }
+    catch {
+        // A claim ARCS could not complete is not a reason to fail an accepted
+        // run — the record simply carries no pid for it.
+    }
+    finally {
+        claimComplete();
+    }
     return {
-        session: writeTarget,
-        run: {
-            accepted: true,
-            mode,
-            ...(mode === "stable" && { threadId: runThreadId }),
-        },
+        runId,
+        // Keyed on the WRITE TARGET's id, never on the path `:id`: under
+        // adoption they are different records, and a stream URL built from the
+        // path id answers 200 and then emits nothing — indistinguishable from a
+        // child that never spoke.
+        streamUrl: `/api/p/${slug}/sessions/${writeTarget.normalizedId}/runs/${runId}/stream`,
+        writeTargetId: writeTarget.normalizedId,
     };
 }, 202));
 sessionsRoute.delete("/api/p/:slug/sessions/:id", async (c) => respond(c, async () => {
@@ -414,6 +908,9 @@ sessionsRoute.delete("/api/p/:slug/sessions/:id", async (c) => respond(c, async
     catch {
         // Sidecar may not exist — a failed unlink is a swallowed no-op.
     }
+    // Retention only ever prunes at a settle, and a deleted session never
+    // settles again — its logs would otherwise sit in the sessions dir forever.
+    await pruneRunEventLogs(projectDir, session.normalizedId, 0);
     return { deleted: true };
 }));
 /**
@@ -439,4 +936,363 @@ sessionsRoute.get("/api/p/:slug/sessions/:id/transcript", async (c) => respond(c
         return { turns: [], mirroredAt: null };
     return { turns: await readSessionTurns(projectDir, session.normalizedId), mirroredAt };
 }));
+// ---------------------------------------------------------------------------
+// Run event stream — a stateless tail of one run's event log
+// ---------------------------------------------------------------------------
+/**
+ * How often an attached tail re-reads the log.
+ *
+ * Sized against the DAG stream's 250ms debounce (`watcher.ts`, feeding
+ * `routes/events.ts`), which is exactly what makes that channel unusable for
+ * tokens and why this is a second channel at all: a quarter second of
+ * coalescing is invisible on a graph repaint and jarring on text arriving word
+ * by word. This is a different channel with a different budget, so it polls
+ * rather than debounces, and it polls an order faster.
+ *
+ * Polling rather than `fs.watch`: watch semantics vary by platform and
+ * filesystem (and still need a poll fallback to be total), and a watcher is
+ * per-connection state — the one thing this route may not hold.
+ */
+const RUN_TAIL_POLL_MS = 100;
+/** The framing byte. A line is only a record once THIS terminates it. */
+const RUN_LOG_NEWLINE = 0x0a;
+/**
+ * Whether the index, read DIRECTLY, answers that THIS SESSION is not in it —
+ * the only thing that turns `getSession`'s not-found into "the session is gone".
+ *
+ * `ITEM_NOT_FOUND` is not by itself evidence of deletion: `readSessionIndex`
+ * folds an unreadable index into an EMPTY one (`readJsonSafe` swallows every
+ * error class), so an `EACCES`, an `EISDIR` or a malformed index on a live
+ * session arrives wearing the deleted session's code.
+ *
+ * The question asked here is about the SESSION, never about the file. "The
+ * index parses" is NOT the same answer: this is a second, later read, so a
+ * failure that CLEARS between the two makes the file parse while the session is
+ * still listed in it — settling a live run on nothing but a flicker. Only a
+ * parse that completes AND does not list `sessionId` answers, plus `ENOENT`,
+ * where the record the session would have to be in is not there at all.
+ *
+ * Deliberate trade: an index that is readable but MALFORMED (`sessions` present
+ * and not an array), or that only the store's JSONC-tolerant reader accepts and
+ * this plain parse does not, never answers at all — so a tail whose session
+ * really was deleted keeps polling for the life of the connection rather than
+ * ending. That is the intended direction — absent evidence must not look like
+ * evidence of silence — and it is unbounded on purpose. The repair for a broken
+ * index is to repair the index; do not "fix" this back into a settle.
+ *
+ * Re-deriving the index path here (rather than asking the store) is the whole
+ * point: the store's own reader is the thing that cannot distinguish these.
+ */
+async function sessionIndexAnswered(projectDir, sessionId) {
+    try {
+        const raw = await readFile(resolve(projectDir, "sessions", "index.json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.sessions))
+            return false;
+        return !parsed.sessions.some((s) => s?.normalizedId === sessionId);
+    }
+    catch (err) {
+        return err.code === "ENOENT";
+    }
+}
+/**
+ * Whether the run is still live, read from the SESSION RECORD rather than from
+ * the runner's in-memory `liveRuns` map.
+ *
+ * The claim is the only liveness signal that survives a restart, and it is what
+ * keeps this route stateless: `isRunLive` would answer "no" for every run
+ * inherited from a dead server process, closing a stream whose child is still
+ * writing. The claim also settles exactly once, under the store lock, in the
+ * same write that stamps the outcome — so "claim gone" and "outcome readable"
+ * can never disagree.
+ */
+async function readRunTailState(projectDir, sessionId, runId) {
+    let session;
+    try {
+        session = await getSession(projectDir, sessionId);
+    }
+    catch (err) {
+        // Two reads, and only their AGREEMENT settles: `getSession` raised
+        // not-found AND a direct read of the index answers that this session is not
+        // in it (or that there is no index at all). Everything else — another error
+        // class, or an index that cannot answer for this session — keeps the tail
+        // polling, because absent evidence must not look like evidence of silence:
+        // the `end` frame a transient read failure would emit here is byte-identical
+        // to the legitimate superseded-run one, the client contract below is to
+        // `close()` on `end`, and so a live run's remaining lines would never reach
+        // that consumer at all. Staying open costs one more poll and nothing else.
+        if (!(err instanceof DagError) || err.code !== "ITEM_NOT_FOUND")
+            return { settled: false };
+        return { settled: await sessionIndexAnswered(projectDir, sessionId) };
+    }
+    if (sessionRunClaim(session) === runId)
+        return { settled: false };
+    const run = runMetadata(session);
+    // A newer run owns the record: this one is over (its claim is gone), but its
+    // outcome and completeness are no longer on disk to report.
+    if (run.runId !== runId)
+        return { settled: true };
+    return {
+        settled: true,
+        ...(typeof run.outcome === "string" && { outcome: run.outcome }),
+        // Only ever written as `true` (claude-runner omits it otherwise), so its
+        // absence on THIS run's own record means the log is whole.
+        truncated: run.eventLogTruncated === true,
+    };
+}
+const EMPTY_TAIL_READ = { lines: [], bytes: 0 };
+/**
+ * Every COMPLETE line the log holds at or after `byteOffset`.
+ *
+ * The trailing-partial rule is the whole point of this function. While a run is
+ * live the file's last bytes may be a record the child is still writing, and the
+ * log also leaves an orphaned fragment behind wherever it lost bytes and refused
+ * to extend the open line. Both look identical from here — unterminated bytes at
+ * EOF — so neither is ever emitted: consumption stops AT the last newline and
+ * `bytes` reports only that much, leaving the fragment to be re-read by the next
+ * poll once (and if) it completes. Emitting it would fabricate a record the child
+ * never wrote, and a fabricated record is undetectable downstream.
+ *
+ * Decoding only the consumed region is also what keeps multi-byte UTF-8 intact:
+ * `0x0a` cannot appear inside a multi-byte sequence, so a cut at a newline is
+ * always a character boundary however the child chunked its writes.
+ *
+ * Total, like everything else that touches this log: a file that is not there
+ * yet (the claim is written BEFORE the child spawns), was pruned, or cannot be
+ * read reads as nothing new.
+ */
+async function readRunLogLines(path, byteOffset) {
+    let handle;
+    try {
+        handle = await open(path, "r");
+    }
+    catch {
+        return EMPTY_TAIL_READ;
+    }
+    try {
+        const { size } = await handle.stat();
+        // Bounded by the same ceiling `foldRunEventLog` reads against — the same
+        // ceiling, NOT the same handling: the fold refuses an oversized file whole
+        // where this clamps to the ceiling and tails what fits. The writer cannot
+        // produce such a file (`push` refuses the crossing chunk and reserves the
+        // byte `terminate` may add), so the two never disagree on a log this server
+        // wrote. The clamp stands for what that leaves: bytes past a ceiling the log
+        // never wrote are not tailed as if the log had written them, and this
+        // allocation can never exceed the log's own maximum size.
+        const end = Math.min(size, RUN_EVENT_LOG_MAX_BYTES);
+        // Nothing new. `<` rather than `===` covers the file shrinking under us,
+        // which an append-only log cannot do — but reading a negative length could.
+        if (end <= byteOffset)
+            return EMPTY_TAIL_READ;
+        const buffer = Buffer.allocUnsafe(end - byteOffset);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, byteOffset);
+        const chunk = buffer.subarray(0, bytesRead);
+        const lines = [];
+        let consumed = 0;
+        for (;;) {
+            const at = chunk.indexOf(RUN_LOG_NEWLINE, consumed);
+            if (at === -1)
+                break;
+            // Verbatim, terminator excluded: the log is the source of truth and this
+            // is a view of it, so nothing here trims, parses or repairs a line.
+            lines.push(chunk.toString("utf-8", consumed, at));
+            consumed = at + 1;
+        }
+        return { lines, bytes: consumed };
+    }
+    catch {
+        return EMPTY_TAIL_READ;
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+/**
+ * Digits and nothing else — no sign, no exponent, no whitespace, no separators.
+ *
+ * Leading zeros ARE accepted (`?from=007` is offset 7), because they are the one
+ * decoration that cannot change the value in base 10: every shape refused above
+ * either names a different number than it reads as, or names none at all.
+ */
+const RUN_TAIL_OFFSET_PATTERN = /^\d+$/;
+/**
+ * Where the tail starts, as an ABSOLUTE line offset into the log.
+ *
+ * The same contract `mirrorOffset` implements for transcript mirroring
+ * (`src/utils/claude-transcript.ts`): the value is the index of the next line
+ * the client has NOT seen — last seen offset + 1 — so a reconnect at it can
+ * neither duplicate nor skip. The log is append-only, so a line's index is fixed
+ * forever and the offset means the same thing to every connection.
+ *
+ * Two sources, and the LARGER wins. `from` is what an explicit reconnect passes;
+ * `Last-Event-ID` is what a browser `EventSource` replays automatically on its
+ * own reconnect, where the URL (and therefore `from`) is frozen at whatever the
+ * first connect used. Both are lower bounds on "lines I already hold", so their
+ * max is the only value that satisfies both — honouring `from` alone would make
+ * every automatic reconnect re-deliver the whole run.
+ *
+ * The consequence, which is what a client author actually needs: a request that
+ * carries `Last-Event-ID` CANNOT REWIND below it, whatever `?from=` says. That
+ * is the right trade rather than a limitation to work around — a browser only
+ * replays the header on an automatic reconnect of the same `EventSource`, so a
+ * deliberate rewind is a fresh `EventSource` (or a plain GET), neither of which
+ * sends the header at all.
+ *
+ * Garbage is REFUSED rather than clamped: the only clamp available is 0, which
+ * silently replays the entire log — precisely the duplicate storm the offset
+ * exists to prevent. Refusal is DIGITS ONLY plus a `MAX_SAFE_INTEGER` bound,
+ * because `Number()` + `Number.isInteger` is not refusal: it admits `1e3`,
+ * `0x2`, whitespace-padded values and results past `MAX_SAFE_INTEGER`. Every
+ * one of those is fail-safe in direction — they only move the tail forward —
+ * but none of them is the "non-negative integer" this documents, and `1e21`
+ * buys an end-frame-only stream indistinguishable from a run that said nothing.
+ * A doc stricter than its code is a defect on its own.
+ */
+function parseRunTailOffset(from, lastEventId) {
+    const parse = (raw, label) => {
+        if (raw === undefined || raw === "")
+            return 0;
+        if (!RUN_TAIL_OFFSET_PATTERN.test(raw) || Number(raw) > Number.MAX_SAFE_INTEGER) {
+            throw new DagError("INVALID_RUN_STREAM_OFFSET", `${label} must be a non-negative integer line offset no greater than ` +
+                `${Number.MAX_SAFE_INTEGER}, got "${raw}"`);
+        }
+        return Number(raw);
+    };
+    return Math.max(parse(from, "from"), parse(lastEventId, "Last-Event-ID"));
+}
+/**
+ * Answers a pre-stream resolution failure as JSON rather than as a stream.
+ *
+ * `respond` cannot be reused: it wraps the SUCCESS path in the envelope too, and
+ * this route's success is an event stream with no envelope at all. The refusals
+ * still speak the shared envelope, because a client that asked for a pruned run
+ * needs a 404 it can read off `res.status` — not a 200 stream that says nothing
+ * and closes, which is what a run whose child was silent looks like.
+ */
+function runStreamFailure(c, err) {
+    if (err instanceof DagError) {
+        return c.json(fail(err.code, err.message), err.code.includes("NOT_FOUND") ? 404 : 400);
+    }
+    console.error("[arcs-web] run stream preflight failed", err);
+    return c.json(fail("internal_error", "Unexpected server error"), 500);
+}
+/**
+ * Tails one run's durable event log as SSE, live or after the fact.
+ *
+ * The log is the source of truth and this is a VIEW of it — a stateless tail,
+ * not a subscription. Every frame is derived from `?from=` plus the file, the
+ * only state is two numbers on this request's own stack, and nothing keyed on a
+ * run or a connection exists anywhere in this module. That is what makes a
+ * server restart cost exactly one client reconnect: the new process can answer
+ * the same GET with the same bytes, because it never knew anything the file did
+ * not already say.
+ *
+ * Frames, all of them carrying an absolute line offset:
+ *  - `line`  `{ offset, line }` — the log's line at `offset`, verbatim.
+ *  - `end`   `{ offset, outcome?, truncated? }` — the run has settled and the
+ *            log is drained; `offset` is the log's total complete-line count,
+ *            i.e. the `from` that would now return nothing.
+ *
+ * The SSE `id` field is the RESUME cursor rather than the frame's own index
+ * (`offset + 1` on a line, `offset` on the end frame), which is what makes an
+ * `EventSource` auto-reconnect land exactly where it left off with no client
+ * arithmetic. Note that an `EventSource` reconnects on ANY stream end, `end`
+ * frame included — the client is expected to `close()` on `end`; the reconnect
+ * is harmless (it replays nothing and closes again) but it is the client's job
+ * to stop it. The header it replays merges as `max(from, Last-Event-ID)`, so a
+ * request carrying it CANNOT REWIND below it — a deliberate rewind is a fresh
+ * `EventSource` (or a plain GET), which sends no header at all.
+ *
+ * Ordering that carries the whole live/settled distinction: the settle is
+ * observed BEFORE the read, never after. A run settled at that instant appends
+ * nothing later, so the read that follows is guaranteed to see the log whole —
+ * the other order loses every line written between the read and the check. A GET
+ * issued after settle therefore takes exactly one pass: replay from `from`, one
+ * `end` frame, close.
+ *
+ * `truncated` on the `end` frame is how a consumer tells "I reached the end of
+ * the stream" from "I reached a hole the log refused to fill" — a capped log
+ * ends on a line boundary and is indistinguishable from a complete one by
+ * reading it. It is only readable at settle: while the run is live the flag
+ * lives in the writer's memory and reaches disk (as
+ * `metadata.run.eventLogTruncated`) only when the write-back stamps the outcome,
+ * so a live tail cannot report it and does not pretend to.
+ *
+ * A read route by construction — it opens nothing, spawns nothing and writes
+ * nothing — so it sits behind the loopback check alone, exactly like every other
+ * GET here, and the `X-ARCS-Token` mutation gate passes it through on method.
+ */
+sessionsRoute.get("/api/p/:slug/sessions/:id/runs/:runId/stream", async (c) => {
+    const runId = c.req.param("runId");
+    let projectDir;
+    let sessionId;
+    let logPath;
+    let fromOffset;
+    try {
+        projectDir = requireProjectDir(c.req.param("slug"));
+        const session = await getSession(projectDir, c.req.param("id"));
+        sessionId = session.normalizedId;
+        fromOffset = parseRunTailOffset(c.req.query("from"), c.req.header("last-event-id"));
+        // Keyed on the canonical id, exactly as the writer keys it; the run id
+        // reaches a filename through `runEventLogSegment`, which sanitizes it, so a
+        // traversal-shaped runId cannot address anything outside the sessions dir.
+        logPath = runEventLogPath(projectDir, sessionId, runId);
+        let logged = false;
+        try {
+            logged = (await stat(logPath)).isFile();
+        }
+        catch {
+            // Not written yet — the claim lands BEFORE the child spawns, so a tail
+            // that connects on the 202 legitimately arrives ahead of the file.
+        }
+        // Neither a log nor a claim: the run never existed under this id, or
+        // retention has already pruned it. Refused rather than answered with an
+        // empty stream, for the same reason `eventLogTruncated` exists — absent
+        // evidence must never look like evidence of silence.
+        if (!logged && sessionRunClaim(session) !== runId) {
+            throw new DagError("RUN_EVENT_LOG_NOT_FOUND", `no event log for run "${runId}" on session "${sessionId}" — it is not the ` +
+                `session's live run and its log is not on disk (pruned, or never written)`);
+        }
+    }
+    catch (err) {
+        return runStreamFailure(c, err);
+    }
+    return streamSSE(c, async (stream) => {
+        /** Absolute index of the next line at `byteOffset`. */
+        let lineOffset = 0;
+        /** Bytes of the log already framed into lines — never inside a record. */
+        let byteOffset = 0;
+        while (!stream.aborted) {
+            const state = await readRunTailState(projectDir, sessionId, runId);
+            const { lines, bytes } = await readRunLogLines(logPath, byteOffset);
+            byteOffset += bytes;
+            for (const line of lines) {
+                const offset = lineOffset;
+                lineOffset += 1;
+                // Counted but not sent: the client already holds it. Counting is what
+                // keeps offsets ABSOLUTE — a skipped line still occupies its index.
+                if (offset < fromOffset)
+                    continue;
+                await stream.writeSSE({
+                    event: "line",
+                    id: String(offset + 1),
+                    data: JSON.stringify({ offset, line }),
+                });
+            }
+            if (state.settled) {
+                await stream.writeSSE({
+                    event: "end",
+                    id: String(lineOffset),
+                    data: JSON.stringify({
+                        offset: lineOffset,
+                        ...(state.outcome !== undefined && { outcome: state.outcome }),
+                        ...(state.truncated !== undefined && { truncated: state.truncated }),
+                    }),
+                });
+                return;
+            }
+            await stream.sleep(RUN_TAIL_POLL_MS);
+        }
+    });
+});
 //# sourceMappingURL=sessions.js.map