@rryando/arcs 3.10.0 → 4.0.0

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

@@ -0,0 +1,1298 @@
+/**
+ * Session routes — full CRUD over the per-project session index.
+ *
+ * Sessions are runtime records for agent sessions (opencode, claude-code)
+ * 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.
+ *
+ * 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 { 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, readSessionTurns, referenceTurnText, sessionTranscriptPath, } from "../../utils/claude-transcript.js";
+import { DagError } from "../../utils/errors.js";
+import { readJsonSafe } from "../../utils/json.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 { 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),
+    runtimeSessionId: z.string().min(1),
+    status: z.enum(SESSION_STATUSES).optional(),
+    startedAt: z.string().optional(),
+    lastMessageAt: z.string().optional(),
+    userEmail: z.string().optional(),
+    metadata: z.record(z.unknown()).optional(),
+});
+const updateSessionSchema = z.object({
+    status: z.enum(SESSION_STATUSES).optional(),
+    lastMessageAt: z.string().nullable().optional(),
+    userEmail: z.string().nullable().optional(),
+    metadata: z.record(z.unknown()).nullable().optional(),
+    /** `null` on either linkage field unlinks the session entirely. */
+    linkedNodeType: z.enum(SESSION_LINKED_NODE_TYPES).nullable().optional(),
+    linkedNodeId: z.string().nullable().optional(),
+});
+/**
+ * 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(),
+        id: z.string(),
+        startOffset: z.number(),
+        endOffset: z.number(),
+    }),
+    text: z.string(),
+    source: z.object({
+        kind: z.enum(["overview", "knowledge", "plan"]),
+        label: z.string(),
+        doc: z.string().optional(),
+        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/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),
+    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;
+}
+function requireOpencodeConfig() {
+    const config = readOpencodeConfig();
+    if (!config) {
+        throw new DagError("OPENCODE_NOT_CONFIGURED", "No opencode endpoint configured — set OPENCODE_PORT (or ARCS_OPENCODE_URL) " +
+            "so ARCS can reach a running `opencode serve`.");
+    }
+    return config;
+}
+/**
+ * The worktree a newly created session should run in.
+ *
+ * Guessing is not an option: opencode happily creates a session in its own
+ * working directory when no directory is supplied, which would silently point
+ * the agent at the wrong repository. An unregistered project is an error.
+ */
+async function primaryWorkspacePath(projectDir, slug) {
+    const meta = await readJsonSafe(resolve(projectDir, "meta.json"));
+    const directory = meta?.workspacePaths?.[0];
+    if (!directory) {
+        throw new DagError("PROJECT_WORKSPACE_UNSET", `Project "${slug}" has no registered workspace path, so there is no directory to ` +
+            `create a session in — run \`arcs project update-paths ${slug} --add <path>\` first.`);
+    }
+    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)) {
+        filters.status = status;
+    }
+    if (runtimeType && SESSION_RUNTIME_TYPES.includes(runtimeType)) {
+        filters.runtimeType = 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;
+}
+/**
+ * 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) {
+    // 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,
+        });
+    }
+    // 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.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: await withPhases(projectDir, sessions) };
+}));
+sessionsRoute.post("/api/p/:slug/sessions", async (c) => respond(c, async () => {
+    const projectDir = requireProjectDir(c.req.param("slug"));
+    const input = await parseBody(c, createSessionSchema);
+    return createSession(projectDir, input);
+}, 201));
+/**
+ * Creates a live opencode session in the project's primary workspace.
+ *
+ * The new session is mirrored into the index straight away rather than waiting
+ * for the discovery stream to notice it, so the caller can select and message
+ * it immediately. The stream's own `session.created` event lands moments later
+ * and merges into the same record.
+ *
+ * There is deliberately no claude-code counterpart: a Claude Code session only
+ * exists once a user runs `claude` in a linked directory, so there is nothing
+ * for ARCS to create remotely.
+ */
+sessionsRoute.post("/api/p/:slug/sessions/opencode/new", async (c) => respond(c, async () => {
+    const slug = c.req.param("slug");
+    const projectDir = requireProjectDir(slug);
+    const { title } = await parseBody(c, createOpencodeSessionSchema);
+    const directory = await primaryWorkspacePath(projectDir, slug);
+    const config = requireOpencodeConfig();
+    const created = await createOpencodeSession(config, {
+        directory,
+        ...(title && { title }),
+    });
+    return upsertSession(projectDir, {
+        runtimeType: "opencode",
+        runtimeSessionId: created.runtimeSessionId,
+        status: "active",
+        metadata: { directory, ...(created.title && { title: created.title }) },
+    });
+}, 201));
+sessionsRoute.get("/api/p/:slug/sessions/:id", async (c) => respond(c, async () => {
+    const projectDir = requireProjectDir(c.req.param("slug"));
+    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"));
+    const input = await parseBody(c, updateSessionSchema);
+    return updateSession(projectDir, { id: c.req.param("id"), ...input });
+}));
+/**
+ * Sends a message to the runtime behind a session.
+ *
+ * Delivery is asymmetric by runtime, and deliberately so: opencode sessions get
+ * live injection (the running agent picks the prompt up mid-turn), while Claude
+ * Code sessions get queued delivery (the session itself drains the queue at its
+ * next hook checkpoint — Claude Code exposes no live channel to inject into).
+ * 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
+ * swallowed no-op on failure (the message itself was already delivered).
+ */
+sessionsRoute.post("/api/p/:slug/sessions/:id/message", async (c) => respond(c, async () => {
+    const projectDir = requireProjectDir(c.req.param("slug"));
+    const { message, reference } = await parseBody(c, sendMessageSchema);
+    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);
+    }
+    else {
+        await sendOpencodeMessage(requireOpencodeConfig(), {
+            runtimeSessionId: session.runtimeSessionId,
+            ...(sessionDirectory(session) && { directory: sessionDirectory(session) }),
+        }, message);
+        updated = await updateSession(projectDir, {
+            id: session.normalizedId,
+            lastMessageAt: new Date().toISOString(),
+        });
+    }
+    // Delivery succeeded (or was accepted into the queue) — record the
+    // reference turn against the session's transcript sidecar, carrying the
+    // payload verbatim so the web UI can render click-through.
+    if (reference !== undefined) {
+        await appendReference(projectDir, session.normalizedId, reference);
+    }
+    return updated;
+}));
+/**
+ * The thread record `threadRef` names, or `undefined` when the index answers
+ * that there is no such record.
+ *
+ * `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.
+ */
+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`);
+        }
+    }
+    else if (session.origin === "arcs") {
+        threadId = session.runtimeSessionId;
+        existing = session;
+    }
+    else {
+        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`);
+    }
+    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.
+    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 finalize never surfaces on the accepted 202.
+    // The trailing catch is defensive — the runner never rejects.
+    runClaudeJob({
+        argv,
+        cwd: dir,
+        timeoutMs,
+        writeTargetKey: writeTarget.normalizedId,
+        // 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 {
+        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 () => {
+    const projectDir = requireProjectDir(c.req.param("slug"));
+    // Resolve through the index first: the sidecar filename keys on the
+    // session's canonical normalizedId, so a non-slugified route id must not
+    // re-derive the filename (deleteSession alone would orphan the sidecar).
+    const session = await getSession(projectDir, c.req.param("id"));
+    await deleteSession(projectDir, session.normalizedId);
+    try {
+        await unlink(sessionTranscriptPath(projectDir, session.normalizedId));
+    }
+    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 };
+}));
+/**
+ * Reads the session's transcript sidecar (mirrored Claude Code lines plus
+ * ARCS-authored reference turns) into the read-model the web UI renders.
+ * An absent sidecar answers an empty transcript with `mirroredAt: null`; once
+ * the sidecar exists, `mirroredAt` is the file mtime so the UI can show how
+ * fresh the mirror is.
+ */
+sessionsRoute.get("/api/p/:slug/sessions/:id/transcript", async (c) => respond(c, async () => {
+    const projectDir = requireProjectDir(c.req.param("slug"));
+    const session = await getSession(projectDir, c.req.param("id"));
+    let mirroredAt = null;
+    try {
+        const info = await stat(sessionTranscriptPath(projectDir, session.normalizedId));
+        if (info.isFile())
+            mirroredAt = info.mtime.toISOString();
+    }
+    catch {
+        // No sidecar yet — empty transcript, nothing mirrored.
+    }
+    if (mirroredAt === null)
+        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