@rryando/arcs 3.11.0 → 4.1.0

package/dist/utils/git.js

@@ -1,4 +1,18 @@
-import { execSync } from "node:child_process";
+import { execFile, execSync } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * Ceiling on one async git invocation. A `git` that never returns — a
+ * network-backed worktree, an index.lock held by another process — must fail
+ * closed to "no revision" rather than pin a request open forever. Generous
+ * enough that a cold `rev-parse` on a large repo still answers.
+ *
+ * Exported for the tests that assert the deadline is actually honoured.
+ */
+export const GIT_ASYNC_TIMEOUT_MS = 2000;
+/** Slack the raced deadline allows the child's own kill path before giving up
+ *  on it, so a child that DOES die on signal reports its real failure. */
+const GIT_DEADLINE_GRACE_MS = 100;
 function exec(cmd, cwd) {
     try {
         return execSync(cmd, {
@@ -11,12 +25,62 @@ function exec(cmd, cwd) {
         return null;
     }
 }
+/**
+ * Async: run `git` with an argv array, never a shell, and never a sync spawn.
+ * Same contract as `exec` above — trimmed stdout, or `null` for any failure —
+ * so an async caller reads the same values a sync one would.
+ *
+ * The deadline is RACED, not delegated to `timeout`. Node's `timeout` option
+ * guarantees a kill ATTEMPT, not a settlement: it signals the child and then
+ * waits for `close`, so a child that cannot act on the signal never fires the
+ * callback and the promise stays pending forever — a request that hangs holding
+ * its connection even though the timeout fired. The realistic instance is
+ * D-state I/O on a stalled NFS/FUSE mount, which is exactly the wedged-worktree
+ * case this budget exists for; `killSignal: "SIGKILL"` narrows the window (it
+ * beats a child that merely ignores SIGTERM) but does not close it, since
+ * SIGKILL does not touch uninterruptible sleep either. Racing our own timer is
+ * what actually bounds the caller, and `unref` keeps a pending timer from
+ * holding the process open on the way out.
+ *
+ * What this does NOT do is reap the child: nothing can until the I/O returns.
+ * A caller that retries against a stalled mount still accumulates live children
+ * — bound that separately if it ever matters here.
+ */
+function execAsync(args, cwd) {
+    const ran = execFileAsync("git", args, {
+        encoding: "utf-8",
+        cwd,
+        timeout: GIT_ASYNC_TIMEOUT_MS,
+        killSignal: "SIGKILL",
+        windowsHide: true,
+    })
+        .then(({ stdout }) => stdout.trim())
+        .catch(() => null);
+    const expired = new Promise((resolve) => {
+        setTimeout(() => resolve(null), GIT_ASYNC_TIMEOUT_MS + GIT_DEADLINE_GRACE_MS).unref();
+    });
+    return Promise.race([ran, expired]);
+}
 export function isGitRepo(cwd) {
     return exec("git rev-parse --is-inside-work-tree", cwd) === "true";
 }
 export function getHeadCommit(cwd) {
     return exec("git rev-parse --short HEAD", cwd);
 }
+/**
+ * Async twin of `getHeadCommit`, for callers on a request path.
+ *
+ * The sync export stays as it is — its callers are CLI, where blocking costs
+ * nothing. A server is the opposite case: `execSync` holds the whole event
+ * loop for the child's entire lifetime, so one file view stalls every other
+ * in-flight request and every open SSE stream. Use this one from a handler.
+ *
+ * Settles within `GIT_ASYNC_TIMEOUT_MS` plus a small grace no matter what the
+ * child does — see `execAsync` for why that needs a race rather than a timeout.
+ */
+export async function getHeadCommitAsync(cwd) {
+    return execAsync(["rev-parse", "--short", "HEAD"], cwd);
+}
 export function getGitLog(cwd, options) {
     const limit = options?.limit ?? 50;
     const since = options?.since;

package/dist/utils/git.js.map

@@ -1 +1 @@
-{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/utils/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAS9C,SAAS,IAAI,CAAC,GAAW,EAAE,GAAW;IACpC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,GAAG,EAAE;YACnB,QAAQ,EAAE,OAAO;YACjB,GAAG;YACH,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,OAAO,IAAI,CAAC,qCAAqC,EAAE,GAAG,CAAC,KAAK,MAAM,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,IAAI,CAAC,4BAA4B,EAAE,GAAG,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,GAAW,EACX,OAA4C;IAE5C,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,CAAC;IAE7B,IAAI,GAAG,GAAG,mCAAmC,KAAK,EAAE,CAAC;IACrD,IAAI,KAAK,EAAE,CAAC;QACV,kEAAkE;QAClE,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACnC,GAAG,IAAI,IAAI,KAAK,QAAQ,CAAC;QAC3B,CAAC;aAAM,CAAC;YACN,GAAG,IAAI,aAAa,KAAK,GAAG,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC9B,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAEvB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,OAAO,GAAkB,EAAE,CAAC;IAElC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACzB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1B,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAErC,oCAAoC;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,+CAA+C,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;QACxF,MAAM,YAAY,GAAG,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAEhF,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,UAAkB;IAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,wBAAwB,UAAU,OAAO,EAAE,GAAG,CAAC,CAAC;IACpE,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/utils/git.ts"],"names":[],"mappings":"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"}

package/dist/utils/hook-contract.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The wire contract shared by everything on the Claude Code session bridge:
+ * the event names the hook is registered under, and the address it posts to.
+ *
+ * These values are duplicated across process boundaries by necessity — the
+ * server validates them, the installer writes them into settings.json, and
+ * `scripts/claude-code-session-hook.mjs` runs standalone under Claude Code with
+ * no ARCS import available. Every duplicate that CAN import derives from here;
+ * the one that cannot (the `.mjs`, which must stay dependency-free so a broken
+ * bridge is inert rather than fatal) keeps its own literals and is pinned to
+ * this module by `test/hook-contract-parity.test.ts`, which fails on any
+ * divergence in either direction.
+ */
+/**
+ * The four Claude Code events the bridge registers for. One script is installed
+ * under all of them; it dispatches internally on `hook_event_name`.
+ *
+ * A readonly tuple so `z.enum()` consumes it directly — the route's validation
+ * and the installer's registration can never drift apart. Adding a fifth event
+ * here without adding it to the hook script breaks the parity test.
+ */
+export declare const HOOK_EVENTS: readonly ["SessionStart", "UserPromptSubmit", "SessionEnd", "Stop"];
+export type HookEventName = (typeof HOOK_EVENTS)[number];
+/** Loopback only: `arcs web` refuses to bind anything else. */
+export declare const DEFAULT_WEB_HOST = "127.0.0.1";
+/** Default `arcs web` port, and therefore the port every hook is installed with. */
+export declare const DEFAULT_WEB_PORT = 4173;
+/**
+ * Where an installed hook posts when `--url` was not given.
+ *
+ * Baked into the settings.json command string at install time, so changing it
+ * only affects hooks installed afterwards — an already-installed hook keeps
+ * posting to the URL it was written with.
+ */
+export declare const DEFAULT_SERVER_URL = "http://127.0.0.1:4173";
+//# sourceMappingURL=hook-contract.d.ts.map

package/dist/utils/hook-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-contract.d.ts","sourceRoot":"","sources":["../../src/utils/hook-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,qEAAsE,CAAC;AAE/F,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAE5C,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,0BAAmD,CAAC"}

package/dist/utils/hook-contract.js

@@ -0,0 +1,35 @@
+/**
+ * The wire contract shared by everything on the Claude Code session bridge:
+ * the event names the hook is registered under, and the address it posts to.
+ *
+ * These values are duplicated across process boundaries by necessity — the
+ * server validates them, the installer writes them into settings.json, and
+ * `scripts/claude-code-session-hook.mjs` runs standalone under Claude Code with
+ * no ARCS import available. Every duplicate that CAN import derives from here;
+ * the one that cannot (the `.mjs`, which must stay dependency-free so a broken
+ * bridge is inert rather than fatal) keeps its own literals and is pinned to
+ * this module by `test/hook-contract-parity.test.ts`, which fails on any
+ * divergence in either direction.
+ */
+/**
+ * The four Claude Code events the bridge registers for. One script is installed
+ * under all of them; it dispatches internally on `hook_event_name`.
+ *
+ * A readonly tuple so `z.enum()` consumes it directly — the route's validation
+ * and the installer's registration can never drift apart. Adding a fifth event
+ * here without adding it to the hook script breaks the parity test.
+ */
+export const HOOK_EVENTS = ["SessionStart", "UserPromptSubmit", "SessionEnd", "Stop"];
+/** Loopback only: `arcs web` refuses to bind anything else. */
+export const DEFAULT_WEB_HOST = "127.0.0.1";
+/** Default `arcs web` port, and therefore the port every hook is installed with. */
+export const DEFAULT_WEB_PORT = 4173;
+/**
+ * Where an installed hook posts when `--url` was not given.
+ *
+ * Baked into the settings.json command string at install time, so changing it
+ * only affects hooks installed afterwards — an already-installed hook keeps
+ * posting to the URL it was written with.
+ */
+export const DEFAULT_SERVER_URL = `http://${DEFAULT_WEB_HOST}:${DEFAULT_WEB_PORT}`;
+//# sourceMappingURL=hook-contract.js.map

package/dist/utils/hook-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-contract.js","sourceRoot":"","sources":["../../src/utils/hook-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,cAAc,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,CAAU,CAAC;AAI/F,+DAA+D;AAC/D,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAE5C,oFAAoF;AACpF,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,gBAAgB,IAAI,gBAAgB,EAAE,CAAC"}

package/dist/utils/hook-token-store.d.ts

@@ -2,9 +2,11 @@
  * Per-project auth token for the Claude Code session-bridge hook endpoint.
  *
  * Loopback-only is not enough on its own: every process on the machine shares
- * localhost, so any local program could otherwise register sessions or drain a
- * project's message queue. The token proves the caller is the hook script that
- * `arcs hooks install-claude-code` provisioned for this project.
+ * localhost, so any local program could otherwise register sessions, write
+ * checkpoints, and hit the SessionStart path — whose answer is injected into a
+ * live agent session as `additionalContext`. The token proves the caller is
+ * the hook script that `arcs hooks install-claude-code` provisioned for this
+ * project.
  *
  * Intentionally not a CRUD store — one token per project, rotated by rerunning
  * the install command. No index, no markdown mirror, no lock (a rotation races
@@ -12,6 +14,45 @@
  */
 export declare function hookTokenPath(projectDir: string): string;
 export declare function readHookToken(projectDir: string): Promise<string | undefined>;
+/**
+ * Rotates the on-disk token, owner-only.
+ *
+ * Unlike the web token there is no in-memory copy to verify against — the hook
+ * subprocess re-reads this file at every checkpoint, so the FILE is the
+ * credential and its mode is the whole control. `writeJson` stages a temp file
+ * and renames it into place with no mode argument, so the token lands 0644
+ * (world-readable) on a default umask — and it lands that way on EVERY write,
+ * not just the first: the rename swaps in the freshly created temp inode, whose
+ * mode came from the umask, and the previous file's mode is discarded with the
+ * inode it belonged to. (A mode passed at open() would in fact have covered this
+ * writer, precisely because every write creates the destination inode; the
+ * "applies only at create" caveat bites a direct non-atomic open(path,"w",mode)
+ * over an existing file, which is not this path.) The chmod is nonetheless
+ * unconditional rather than conditional on the mode read back, so the 0600
+ * guarantee survives a future switch away from the atomic writer.
+ *
+ * The directory is narrowed too: the staged temp file is a fresh inode born
+ * under the umask, so it is briefly world-readable between write and rename.
+ * 0o700 on the enclosing directory — which holds nothing but this token —
+ * denies another account the traversal needed to reach that window at all.
+ *
+ * What this buys, stated honestly: 0o600 is a cross-user control. It keeps
+ * other UNIX accounts out; it is NOT a defense against a process running as
+ * THIS user, which can read the file at any mode. Nor is this the token's only
+ * copy — `arcs hooks install-claude-code --write` embeds the same value in the
+ * workspace's .claude/settings.local.json, which is now created 0o600 and
+ * chmodded 0o600 unconditionally too (claude-code-hook-install.ts), though that
+ * copy is inlined into the hook command string and so still leaks to `ps` on
+ * every hook fire. So this is a floor on ARCS's own copy, not a guarantee about
+ * the secret.
+ *
+ * A chmod failure propagates and fails the install command. That is
+ * deliberate — the caller (`arcs hooks install-claude-code`) has not printed
+ * the snippet yet, so the run fails closed and the user reruns to rotate,
+ * rather than silently installing a token this process could not protect. The
+ * hook's own read path (readHookToken/verifyHookToken) is untouched by this and
+ * still never throws.
+ */
 export declare function writeHookToken(projectDir: string, token: string): Promise<void>;
 /**
  * Constant-time token comparison. Returns false when the project has no token

package/dist/utils/hook-token-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook-token-store.d.ts","sourceRoot":"","sources":["../../src/utils/hook-token-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAGnF;AAED,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrF;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQ7F"}
+{"version":3,"file":"hook-token-store.d.ts","sourceRoot":"","sources":["../../src/utils/hook-token-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAaH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAGnF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrF;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQ7F"}

package/dist/utils/hook-token-store.js

@@ -2,16 +2,19 @@
  * Per-project auth token for the Claude Code session-bridge hook endpoint.
  *
  * Loopback-only is not enough on its own: every process on the machine shares
- * localhost, so any local program could otherwise register sessions or drain a
- * project's message queue. The token proves the caller is the hook script that
- * `arcs hooks install-claude-code` provisioned for this project.
+ * localhost, so any local program could otherwise register sessions, write
+ * checkpoints, and hit the SessionStart path — whose answer is injected into a
+ * live agent session as `additionalContext`. The token proves the caller is
+ * the hook script that `arcs hooks install-claude-code` provisioned for this
+ * project.
  *
  * Intentionally not a CRUD store — one token per project, rotated by rerunning
  * the install command. No index, no markdown mirror, no lock (a rotation races
  * only with itself, and the loser simply has to rerun install).
  */
 import { timingSafeEqual } from "node:crypto";
-import { join } from "node:path";
+import { chmod } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { readJsonSafe } from "./json.js";
 import { ensureDir, nowISO, writeJson } from "./storage-utils.js";
 export function hookTokenPath(projectDir) {
@@ -21,9 +24,51 @@ export async function readHookToken(projectDir) {
     const file = await readJsonSafe(hookTokenPath(projectDir));
     return typeof file?.token === "string" && file.token ? file.token : undefined;
 }
+/**
+ * Rotates the on-disk token, owner-only.
+ *
+ * Unlike the web token there is no in-memory copy to verify against — the hook
+ * subprocess re-reads this file at every checkpoint, so the FILE is the
+ * credential and its mode is the whole control. `writeJson` stages a temp file
+ * and renames it into place with no mode argument, so the token lands 0644
+ * (world-readable) on a default umask — and it lands that way on EVERY write,
+ * not just the first: the rename swaps in the freshly created temp inode, whose
+ * mode came from the umask, and the previous file's mode is discarded with the
+ * inode it belonged to. (A mode passed at open() would in fact have covered this
+ * writer, precisely because every write creates the destination inode; the
+ * "applies only at create" caveat bites a direct non-atomic open(path,"w",mode)
+ * over an existing file, which is not this path.) The chmod is nonetheless
+ * unconditional rather than conditional on the mode read back, so the 0600
+ * guarantee survives a future switch away from the atomic writer.
+ *
+ * The directory is narrowed too: the staged temp file is a fresh inode born
+ * under the umask, so it is briefly world-readable between write and rename.
+ * 0o700 on the enclosing directory — which holds nothing but this token —
+ * denies another account the traversal needed to reach that window at all.
+ *
+ * What this buys, stated honestly: 0o600 is a cross-user control. It keeps
+ * other UNIX accounts out; it is NOT a defense against a process running as
+ * THIS user, which can read the file at any mode. Nor is this the token's only
+ * copy — `arcs hooks install-claude-code --write` embeds the same value in the
+ * workspace's .claude/settings.local.json, which is now created 0o600 and
+ * chmodded 0o600 unconditionally too (claude-code-hook-install.ts), though that
+ * copy is inlined into the hook command string and so still leaks to `ps` on
+ * every hook fire. So this is a floor on ARCS's own copy, not a guarantee about
+ * the secret.
+ *
+ * A chmod failure propagates and fails the install command. That is
+ * deliberate — the caller (`arcs hooks install-claude-code`) has not printed
+ * the snippet yet, so the run fails closed and the user reruns to rotate,
+ * rather than silently installing a token this process could not protect. The
+ * hook's own read path (readHookToken/verifyHookToken) is untouched by this and
+ * still never throws.
+ */
 export async function writeHookToken(projectDir, token) {
-    await ensureDir(join(projectDir, "hooks"));
-    await writeJson(hookTokenPath(projectDir), { token, createdAt: nowISO() });
+    const path = hookTokenPath(projectDir);
+    await ensureDir(dirname(path));
+    await chmod(dirname(path), 0o700);
+    await writeJson(path, { token, createdAt: nowISO() });
+    await chmod(path, 0o600);
 }
 /**
  * Constant-time token comparison. Returns false when the project has no token

package/dist/utils/hook-token-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"hook-token-store.js","sourceRoot":"","sources":["../../src/utils/hook-token-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAOlE,MAAM,UAAU,aAAa,CAAC,UAAkB;IAC9C,OAAO,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,wBAAwB,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,UAAkB;IACpD,MAAM,IAAI,GAAG,MAAM,YAAY,CAAgB,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC;IAC1E,OAAO,OAAO,IAAI,EAAE,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAChF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,UAAkB,EAAE,KAAa;IACpE,MAAM,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3C,MAAM,SAAS,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,UAAkB,EAAE,SAAiB;IACzE,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,UAAU,CAAC,CAAC;IAC9C,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAEvC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC/C,IAAI,QAAQ,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACpD,OAAO,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC"}
+{"version":3,"file":"hook-token-store.js","sourceRoot":"","sources":["../../src/utils/hook-token-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAOlE,MAAM,UAAU,aAAa,CAAC,UAAkB;IAC9C,OAAO,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,wBAAwB,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,UAAkB;IACpD,MAAM,IAAI,GAAG,MAAM,YAAY,CAAgB,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC;IAC1E,OAAO,OAAO,IAAI,EAAE,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,UAAkB,EAAE,KAAa;IACpE,MAAM,IAAI,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IACvC,MAAM,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/B,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;IAClC,MAAM,SAAS,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;IACtD,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,UAAkB,EAAE,SAAiB;IACzE,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,UAAU,CAAC,CAAC;IAC9C,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAEvC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC/C,IAAI,QAAQ,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACpD,OAAO,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC"}

package/dist/utils/session-store.d.ts

@@ -1,18 +1,40 @@
 /**
  * Session CRUD storage for ARCS projects.
  *
- * Tracks agent runtime sessions (opencode, claude-code) that are attached to a
- * project. Unlike tasks/plans/knowledge these records are volatile runtime
- * state: they carry no markdown mirror and never invalidate the graph cache.
+ * Tracks agent runtime sessions attached to a project. Unlike
+ * tasks/plans/knowledge these records are volatile runtime state: they carry no
+ * markdown mirror and never invalidate the graph cache.
  */
 export type { SessionLinkedNodeType, SessionRuntimeType, SessionStatus, } from "./storage-utils.js";
 export { SESSION_LINKED_NODE_TYPES, SESSION_RUNTIME_TYPES, SESSION_STATUSES, } from "./storage-utils.js";
+/**
+ * Where a session record came from — its provenance, not its state.
+ *
+ * - `observed` — a runtime session ARCS merely watches: a terminal `claude`
+ *   session announcing itself through the hook bridge. Something outside ARCS
+ *   drives it.
+ * - `arcs` — a record ARCS minted for itself (the headless oneshot/stable
+ *   threads). No terminal is attached; it is driven by headless runs only.
+ *
+ * Declared here rather than in storage-utils alongside the other session enums
+ * because origin is derived by this module (legacy promotion below) and every
+ * consumer already imports the session enums through this file.
+ */
+export declare const SESSION_ORIGINS: readonly ["observed", "arcs"];
+export type SessionOrigin = (typeof SESSION_ORIGINS)[number];
 export interface SessionMeta {
     id: string;
     normalizedId: string;
     runtimeType: import("./storage-utils.js").SessionRuntimeType;
-    /** Runtime-native session id, verbatim (e.g. opencode "ses_04f…"). */
+    /** Runtime-native session id, verbatim (e.g. a claude-code session uuid). */
     runtimeSessionId: string;
+    /**
+     * Provenance of the record. Persisted, never client-settable, and never
+     * rewritten by an upsert — whoever created the record fixed it. Always
+     * present on a value read through this module even when the stored record
+     * predates the field (see `withDerivedOrigin`).
+     */
+    origin: SessionOrigin;
     status: import("./storage-utils.js").SessionStatus;
     startedAt: string;
     lastMessageAt?: string;
@@ -26,11 +48,41 @@ export interface SessionMeta {
     /** Normalized task/plan id — never a diagram node id (T001…). */
     linkedNodeId?: string;
     /**
-     * Messages accepted from the web UI but not yet delivered. Only runtimes
-     * without a live channel (claude-code) ever populate this: the runtime drains
-     * the queue itself at its next checkpoint. Absent means "nothing pending".
+     * Id of the headless run currently claimed on this record — written when the
+     * run is spawned and cleared when it settles (`beginSessionRun` /
+     * `settleSessionRun`). Its presence IS the claim: a record carrying one is
+     * believed to have a live `claude` child behind it.
+     *
+     * Written for the runs ARCS drives itself, so in practice every `arcs`-origin
+     * thread; an `observed` record only carries one while a headless run targets
+     * it. Deliberately absent from `UpdateSessionInput`: a claim is a fact about
+     * a process, never something a caller hands in.
      */
-    messageQueue?: string[];
+    currentRunId?: string;
+    /**
+     * OS pid of the claimed run's child. Persisted because in-memory liveness
+     * dies with the server and the restart case is exactly the one that has to be
+     * recoverable — the startup sweep probes this pid to tell a live run from an
+     * orphaned claim.
+     */
+    currentRunPid?: number;
+    /**
+     * ISO-8601 proof of life for the claimed run. Same unit as every other
+     * top-level timestamp on this record; `metadata.run.*` keeps epoch ms and the
+     * two never mix.
+     *
+     * SHORTCUT: nothing refreshes this mid-run yet, so it equals the run's spawn
+     * time and RUN_HEARTBEAT_TTL_MS has to cover a whole run; upgrade to a
+     * periodic touch (and a far shorter TTL) when the runner grows a heartbeat.
+     */
+    heartbeatAt?: string;
+    /**
+     * ISO-8601 time of the last runtime checkpoint ARCS observed — Claude Code's
+     * `UserPromptSubmit` and `Stop` hooks. The only liveness evidence an
+     * `observed` session ever produces: nothing else reports that a terminal
+     * session is still working.
+     */
+    lastCheckpointAt?: string;
     metadata?: Record<string, unknown>;
 }
 export interface SessionIndex {
@@ -39,6 +91,13 @@ export interface SessionIndex {
 export interface CreateSessionInput {
     runtimeType: import("./storage-utils.js").SessionRuntimeType;
     runtimeSessionId: string;
+    /**
+     * Provenance, set once at creation and defaulting to `observed`. Only the
+     * ARCS-minted headless threads pass `arcs`. Deliberately absent from every
+     * request schema: provenance is a fact about who created the record, never
+     * something a client hands in.
+     */
+    origin?: SessionOrigin;
     status?: import("./storage-utils.js").SessionStatus;
     startedAt?: string;
     lastMessageAt?: string;
@@ -51,6 +110,12 @@ export interface UpdateSessionInput {
     status?: import("./storage-utils.js").SessionStatus;
     /** Pass `null` to clear; pass an ISO timestamp to set. */
     lastMessageAt?: string | null;
+    /**
+     * ISO timestamp of a runtime checkpoint just observed (`null` clears it).
+     * Settable here — unlike the run claim — because a checkpoint is a report the
+     * hook bridge relays, not a process ARCS owns.
+     */
+    lastCheckpointAt?: string | null;
     /** Pass `null` to clear; pass a string to set. */
     userEmail?: string | null;
     /** Pass `null` to clear; merged shallowly into the existing metadata. */
@@ -62,12 +127,6 @@ export interface UpdateSessionInput {
     linkedNodeType?: import("./storage-utils.js").SessionLinkedNodeType | null;
     /** Normalized task/plan id — validated against the task/plan store. */
     linkedNodeId?: string | null;
-    /**
-     * Whole-queue replacement (`null` clears it). Appending/draining goes through
-     * `enqueueSessionMessage`/`drainSessionMessageQueue` instead — a shallow merge
-     * cannot express those safely under concurrent access.
-     */
-    messageQueue?: string[] | null;
     now?: string;
 }
 export interface SessionFilters {
@@ -75,6 +134,78 @@ export interface SessionFilters {
     runtimeType?: import("./storage-utils.js").SessionRuntimeType;
 }
 export declare function readSessionIndex(projectDir: string): Promise<SessionIndex>;
+/**
+ * What a session is doing right now, as a reader of the UI would say it.
+ *
+ * DERIVED, never stored: there is no `phase` field on `SessionMeta` and no way
+ * to write one through this module. A stored phase is a second source of truth
+ * that goes stale the instant a process dies without telling anyone — which is
+ * precisely the "stuck on running forever" failure this replaces.
+ */
+export declare const SESSION_PHASES: readonly ["running", "idle", "failed", "ended"];
+export type SessionPhase = (typeof SESSION_PHASES)[number];
+/**
+ * Outcome vocabulary persisted on `metadata.run.outcome`. A superset of the
+ * runner's own `RunOutcome` ("success" | "error" | "timeout"): `interrupted` is
+ * never produced BY a run, it is written FOR a run whose process disappeared
+ * without ever settling — a restart's orphan. Declared here rather than
+ * imported from the web server because `utils/` must not depend on
+ * `web-server/`; claude-runner's union stays exactly what a child can return.
+ */
+export declare const SESSION_RUN_OUTCOMES: readonly ["success", "error", "timeout", "interrupted"];
+export type SessionRunOutcome = (typeof SESSION_RUN_OUTCOMES)[number];
+/**
+ * How long a run claim's heartbeat counts as proof of life. Sized to the
+ * runner's default 10-minute run ceiling because nothing refreshes the
+ * heartbeat mid-run yet (see `SessionMeta.heartbeatAt`) — a shorter window
+ * would demote a perfectly healthy long run to `idle`.
+ */
+export declare const RUN_HEARTBEAT_TTL_MS: number;
+/**
+ * How long a runtime checkpoint counts as proof of life for an observed
+ * session. Deliberately shorter than the run TTL: checkpoints arrive at every
+ * prompt and every turn end, so a terminal that has produced neither in five
+ * minutes is waiting on a human, not working.
+ */
+export declare const CHECKPOINT_TTL_MS: number;
+export interface SessionPhaseOptions {
+    /** Clock in epoch ms; defaults to `Date.now()`. */
+    now?: number;
+    heartbeatTtlMs?: number;
+    checkpointTtlMs?: number;
+}
+/**
+ * The record's run claim, or `undefined` when it holds none. Validated rather
+ * than trusted: a hand-edited index can carry anything under this key.
+ */
+export declare function sessionRunClaim(session: SessionMeta): string | undefined;
+/**
+ * Derives a session's phase from its own persisted evidence, in one place.
+ *
+ * Precedence, strongest first:
+ *  1. a terminal `status` — `failed` is `failed`, `completed`/`disconnected`
+ *     are `ended`. Nothing observed later reopens a session that is over.
+ *  2. a run claim (`currentRunId`) — ARCS spawned a child for this record, so
+ *     its `heartbeatAt` is the freshest evidence there is. Stale means the
+ *     claim outlived its proof of life, which reads `idle`, not `failed`: the
+ *     run is settled by the reconciler, not guessed at here.
+ *  3. `lastCheckpointAt` — the only signal an observed terminal session emits.
+ *
+ * `metadata.run.outcome` is deliberately NOT an input. That field is run-level
+ * history (rendered next to the run), while phase answers "is this session live
+ * right now" — a run that failed an hour ago leaves the session idle and ready
+ * for the next one, not permanently `failed`.
+ *
+ * Pure: a record plus a clock, no I/O, no process probing. Liveness that needs
+ * the world (a pid, `claude agents`) belongs to the reconciler, which starts
+ * from this value and can only ever demote it.
+ *
+ * SHORTCUT: checkpoint freshness cannot tell `UserPromptSubmit` (turn started)
+ * from `Stop` (turn ended), so a session reads `running` for the TTL after its
+ * last turn; upgrade to a persisted checkpoint kind when the panel needs
+ * turn-level precision.
+ */
+export declare function deriveSessionPhase(session: SessionMeta, options?: SessionPhaseOptions): SessionPhase;
 export declare function createSession(projectDir: string, input: CreateSessionInput): Promise<SessionMeta>;
 /**
  * Create-or-update by runtime session id. Used by runtime discovery bridges,
@@ -88,26 +219,73 @@ export declare function upsertSession(projectDir: string, input: CreateSessionIn
 export declare function listSessions(projectDir: string, filters?: SessionFilters): Promise<SessionMeta[]>;
 export declare function getSession(projectDir: string, sessionId: string): Promise<SessionMeta>;
 export declare function updateSession(projectDir: string, input: UpdateSessionInput): Promise<SessionMeta>;
+export interface BeginSessionRunInput {
+    /** Caller-minted id for this run — the claim's identity. */
+    runId: string;
+    /** OS pid of the spawned child; absent/`null` when the spawn produced none. */
+    pid?: number | null;
+    /** ISO override for the heartbeat and `updatedAt` stamps (tests). */
+    now?: string;
+}
+export interface SettleSessionRunInput {
+    /**
+     * Settles only when it matches the persisted claim. Omit to settle whatever
+     * claim is there (the startup sweep passes the id it read, so a run that
+     * started in between is never settled out from under itself).
+     */
+    runId?: string;
+    outcome: SessionRunOutcome;
+    error?: string;
+    /** Epoch ms for `metadata.run.endedAt` — defaults to now. */
+    endedAt?: number;
+    /**
+     * Extra `metadata.run` fields stamped in the SAME write as the outcome: what
+     * the RUNNER measured and no claim could have known at spawn (the pid and
+     * startedAt the child actually reported, the run's mode, the stream
+     * observations). Merged UNDER the settle's own fields, so `outcome`/`endedAt`/
+     * `error` can never be smuggled past the settle that owns them.
+     */
+    run?: Record<string, unknown>;
+    /**
+     * Sibling `metadata` keys written in the same read-modify-write, shallow
+     * merged as `updateSession` merges. The seed-decision repair rides here: a
+     * settle that released the claim in one write and repaired the record in a
+     * second is readable in between as "this run failed" while still carrying the
+     * seed state that failed it — and the second write can land AFTER a newer run
+     * has already claimed the record, clobbering its live `metadata.run`. Merged
+     * UNDER `run`, so `run` can never be rewritten through this door.
+     */
+    metadata?: Record<string, unknown>;
+    /** ISO override for `updatedAt` (tests). */
+    now?: string;
+}
 /**
- * Appends a message to a session's pending queue.
- *
- * Deliberately not part of `updateSession`: the generic path shallow-merges
- * whatever the caller passes, which would let two concurrent senders read the
- * same array and write back a queue missing one message. Append happens inside
- * the store lock, so the read-modify-write is atomic.
+ * Claims a session for a headless run: persists the run id, the child's pid and
+ * the first heartbeat, all of which survive the server process that made them.
  *
- * The message is stored verbatim — callers validate content (the route rejects
- * empty strings before it gets here).
+ * The claim is what makes a run recoverable. In-memory liveness (the runner's
+ * `liveRuns` map) dies with the server, so without a persisted claim a run
+ * interrupted by a restart would leave the session reading `running` forever
+ * with nothing left that could ever settle it.
  */
-export declare function enqueueSessionMessage(projectDir: string, sessionId: string, message: string): Promise<SessionMeta>;
+export declare function beginSessionRun(projectDir: string, sessionId: string, input: BeginSessionRunInput): Promise<SessionMeta>;
 /**
- * Reads and clears a session's pending queue in one lock acquisition.
+ * Releases a session's run claim, records how the run ended on `metadata.run`,
+ * and applies whatever the settle repaired — in ONE lock acquisition.
+ *
+ * Read-modify-write has to be atomic: `metadata.run` is replaced wholesale by
+ * every writer, so settling through the generic `updateSession` would race the
+ * route's own write-back and could drop the run's pid/startedAt.
  *
- * Read-then-clear must be atomic: a checkpoint that read the queue and cleared
- * it in two calls would drop any message enqueued in between. Delivery is
- * at-most-once — a consumer that crashes after draining loses the batch, which
- * is the accepted trade for never replaying a message twice into a session.
+ * Everything a settle concludes therefore goes in HERE rather than in a
+ * follow-up `updateSession`. The claim is the only thing serializing a run
+ * against the next one, and releasing it is the LAST thing this write does — so
+ * a conclusion left to a second write is both observable in the gap (the record
+ * reads settled while still carrying the state the run just disproved) and
+ * unguarded outside it: the `input.runId` check above holds only for the
+ * duration of this lock, and a newer run can claim the record the moment it is
+ * released.
  */
-export declare function drainSessionMessageQueue(projectDir: string, sessionId: string): Promise<string[]>;
+export declare function settleSessionRun(projectDir: string, sessionId: string, input: SettleSessionRunInput): Promise<SessionMeta>;
 export declare function deleteSession(projectDir: string, sessionId: string): Promise<void>;
 //# sourceMappingURL=session-store.d.ts.map