@rryando/arcs 3.10.0 → 4.0.0

package/dist/shared/session-vocabulary.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Session-state vocabulary — the ONE derivation both sides of the wire read.
+ *
+ * A session carries two state fields: `status`, persisted by the store, and
+ * `phase`, derived per response and never persisted. The moment two call sites
+ * pick between them independently the product starts disagreeing with itself —
+ * a table badged `running` under an `active` chip, or a server refusing the
+ * resume the client just offered. Everything user-facing and every server gate
+ * goes through `sessionState()` here, so there is nothing to keep in sync.
+ *
+ * The predicates take the RECORD, never a pre-picked string, for the same
+ * reason the badge component does: handing the badge a record protects badge
+ * call sites only, and a counter or an affordance gate takes no badge prop.
+ *
+ * ---------------------------------------------------------------------------
+ * THIS MODULE MUST HAVE ZERO IMPORTS. Do not add one — not a type-only import,
+ * not a `import type { SessionMeta }` for the parameter shapes below.
+ *
+ * `web/` imports this file directly by relative path (there is no alias and no
+ * third package). Its being a LEAF — not the directory it sits in — is the
+ * entire guarantee that no server module graph is dragged into the client
+ * bundle. One import of anything under `src/utils/` or `src/web-server/` and
+ * the CLI's transitive graph starts resolving inside `vite build`.
+ *
+ * The corollary of that reach: this file is typechecked under BOTH tsconfigs,
+ * and `web/tsconfig.json` sets `noUncheckedIndexedAccess` and
+ * `verbatimModuleSyntax` where the root tsconfig sets neither. A root-legal
+ * edit here can fail `npm --workspace @arcs/web run typecheck`. Run both.
+ * ---------------------------------------------------------------------------
+ */
+/**
+ * The two fields a session's state is read from — all this module ever needs of
+ * a record, so a store record, a reconciled server view and a wire-shaped
+ * client record can all be filtered, gated and badged through one derivation.
+ *
+ * Typed as plain strings rather than the `SessionStatus`/`SessionPhase` literal
+ * unions on purpose. Pinning those here would mean either an import (forbidden
+ * above) or a third hand-written copy of the wire vocabulary that the server
+ * store and `web/src/api/client.ts` already mirror deliberately. What is shared
+ * across the boundary is the DERIVATION, not the wire types; every caller keeps
+ * passing its own precisely-typed record, which is assignable to this.
+ */
+export interface SessionStateSource {
+    status: string;
+    phase?: string;
+}
+/**
+ * The state a session is in, as the UI states it everywhere and as the server
+ * decides from: the derived phase — the only signal reflecting whether the
+ * session is live right now — falling back to the record's own status for a
+ * record that reached a decision site without one (the record echoed by
+ * `POST /run` carries no phase, and neither does a pre-phase endpoint).
+ *
+ * This is the single derivation site. `status` is still readable on the row
+ * (the status cell's tooltip), but nothing decides anything from it alone.
+ */
+export declare function sessionState(session: SessionStateSource): string;
+/**
+ * Is this a session a human could still reach — as the badge beside it reads?
+ *
+ * What the sessions header counts as "N live". Takes the record so the count is
+ * computed from the same field the badge one row below renders, rather than
+ * from whichever of the two a call site happened to reach for.
+ *
+ * This is the SAFE half of the pair: across the reachable pairs above, `status`
+ * and `phase` never disagree about liveness. A record stored `active` whose
+ * process is gone derives `idle`, and `idle` is live — the record is not over —
+ * so the count is right read either way. That is a property of today's
+ * derivation, not a guarantee; reading the record keeps the count correct if it
+ * stops holding. `isSessionAttached` below is where the two genuinely disagree.
+ */
+export declare function isSessionLive(session: SessionStateSource): boolean;
+/**
+ * Is a process driving this session right now?
+ *
+ * The gate on affordances that need the session's runtime thread free — today
+ * the composer's headless resume and the server route behind it, neither of
+ * which can attach to a session a terminal is already driving. Reading the
+ * persisted status here is wrong in BOTH directions, and both are reachable
+ * pairs: a record stored `active` whose process is gone derives `idle` — no
+ * fresh evidence of attachment — and would be refused the resume it is the
+ * perfect candidate for (`active`/`idle`), while a live `running` session
+ * stored `idle` would be offered one that cannot work (`idle`/`running`).
+ * `idle` is the state the whole affordance turns on; it is never `ended`, which
+ * only a terminal status produces.
+ */
+export declare function isSessionAttached(session: SessionStateSource): boolean;
+//# sourceMappingURL=session-vocabulary.d.ts.map

package/dist/shared/session-vocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-vocabulary.d.ts","sourceRoot":"","sources":["../../src/shared/session-vocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAEhE;AAwCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAElE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAEtE"}

package/dist/shared/session-vocabulary.js

@@ -0,0 +1,114 @@
+/**
+ * Session-state vocabulary — the ONE derivation both sides of the wire read.
+ *
+ * A session carries two state fields: `status`, persisted by the store, and
+ * `phase`, derived per response and never persisted. The moment two call sites
+ * pick between them independently the product starts disagreeing with itself —
+ * a table badged `running` under an `active` chip, or a server refusing the
+ * resume the client just offered. Everything user-facing and every server gate
+ * goes through `sessionState()` here, so there is nothing to keep in sync.
+ *
+ * The predicates take the RECORD, never a pre-picked string, for the same
+ * reason the badge component does: handing the badge a record protects badge
+ * call sites only, and a counter or an affordance gate takes no badge prop.
+ *
+ * ---------------------------------------------------------------------------
+ * THIS MODULE MUST HAVE ZERO IMPORTS. Do not add one — not a type-only import,
+ * not a `import type { SessionMeta }` for the parameter shapes below.
+ *
+ * `web/` imports this file directly by relative path (there is no alias and no
+ * third package). Its being a LEAF — not the directory it sits in — is the
+ * entire guarantee that no server module graph is dragged into the client
+ * bundle. One import of anything under `src/utils/` or `src/web-server/` and
+ * the CLI's transitive graph starts resolving inside `vite build`.
+ *
+ * The corollary of that reach: this file is typechecked under BOTH tsconfigs,
+ * and `web/tsconfig.json` sets `noUncheckedIndexedAccess` and
+ * `verbatimModuleSyntax` where the root tsconfig sets neither. A root-legal
+ * edit here can fail `npm --workspace @arcs/web run typecheck`. Run both.
+ * ---------------------------------------------------------------------------
+ */
+/**
+ * The state a session is in, as the UI states it everywhere and as the server
+ * decides from: the derived phase — the only signal reflecting whether the
+ * session is live right now — falling back to the record's own status for a
+ * record that reached a decision site without one (the record echoed by
+ * `POST /run` carries no phase, and neither does a pre-phase endpoint).
+ *
+ * This is the single derivation site. `status` is still readable on the row
+ * (the status cell's tooltip), but nothing decides anything from it alone.
+ */
+export function sessionState(session) {
+    return session.phase ?? session.status;
+}
+/** States meaning "this session is not over": the live phases, plus the raw
+ *  `active`/`idle` a record that arrived without a phase is badged with. */
+const LIVE_STATES = new Set(["running", "idle", "active"]);
+/**
+ * States meaning "a process is driving this session right now".
+ *
+ * Deliberately NARROWER than `LIVE_STATES`, and the reason both sets are
+ * private to this module rather than living at their call sites: `idle` is live
+ * — the record is not over and the session list counts it — but nothing holds
+ * its runtime thread, which is exactly the session a headless resume works on.
+ * One shared "live" set would silently conflate "not over" with "attached" and
+ * take the resume affordance away from every session that can actually use it.
+ *
+ * REACHABLE PAIRS. The server's derivation (`deriveSessionPhase` →
+ * `reconcilePhase` → `runDeadlinePhase`, all composed in `withPhases`) can only
+ * ever produce these (`status`, `phase`) pairs, exhaustively:
+ *
+ *   active/idle · active/running · completed/ended · disconnected/ended ·
+ *   failed/failed · idle/idle · idle/running
+ *
+ * So `ended` comes ONLY from a terminal status (`completed`/`disconnected`):
+ * the derivation returns it before looking at any liveness evidence, the
+ * reconciler early-returns on every non-`running` derivation, and both probes
+ * can only demote `running` to `idle`. A record stored `active` whose process
+ * is gone therefore derives `idle` — "no fresh evidence of attachment" — and
+ * never `ended`. Both sit outside this set, so this predicate answers the same
+ * either way; the pair that carries the meaning is `active`/`idle`, because
+ * that is what "the process is gone" actually looks like on the wire.
+ *
+ * `active` itself is a persisted status, reachable only through
+ * `sessionState`'s fallback for a record handed to a predicate without a
+ * derived phase. Server call sites go through `withPhases` first, so the phase
+ * decides in practice; the fallback is the conservative answer for anything
+ * that does not — treat as attached and refuse, rather than silently accept.
+ */
+const ATTACHED_STATES = new Set(["running", "active"]);
+/**
+ * Is this a session a human could still reach — as the badge beside it reads?
+ *
+ * What the sessions header counts as "N live". Takes the record so the count is
+ * computed from the same field the badge one row below renders, rather than
+ * from whichever of the two a call site happened to reach for.
+ *
+ * This is the SAFE half of the pair: across the reachable pairs above, `status`
+ * and `phase` never disagree about liveness. A record stored `active` whose
+ * process is gone derives `idle`, and `idle` is live — the record is not over —
+ * so the count is right read either way. That is a property of today's
+ * derivation, not a guarantee; reading the record keeps the count correct if it
+ * stops holding. `isSessionAttached` below is where the two genuinely disagree.
+ */
+export function isSessionLive(session) {
+    return LIVE_STATES.has(sessionState(session));
+}
+/**
+ * Is a process driving this session right now?
+ *
+ * The gate on affordances that need the session's runtime thread free — today
+ * the composer's headless resume and the server route behind it, neither of
+ * which can attach to a session a terminal is already driving. Reading the
+ * persisted status here is wrong in BOTH directions, and both are reachable
+ * pairs: a record stored `active` whose process is gone derives `idle` — no
+ * fresh evidence of attachment — and would be refused the resume it is the
+ * perfect candidate for (`active`/`idle`), while a live `running` session
+ * stored `idle` would be offered one that cannot work (`idle`/`running`).
+ * `idle` is the state the whole affordance turns on; it is never `ended`, which
+ * only a terminal status produces.
+ */
+export function isSessionAttached(session) {
+    return ATTACHED_STATES.has(sessionState(session));
+}
+//# sourceMappingURL=session-vocabulary.js.map

package/dist/shared/session-vocabulary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-vocabulary.js","sourceRoot":"","sources":["../../src/shared/session-vocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAmBH;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,OAA2B;IACtD,OAAO,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;AACzC,CAAC;AAED;4EAC4E;AAC5E,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,OAA2B;IACvD,OAAO,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA2B;IAC3D,OAAO,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;AACpD,CAAC"}

package/dist/utils/claude-code-hook-install.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Consent-gated writer for the Claude Code session-bridge hook.
+ *
+ * `arcs hooks install-claude-code` deliberately never edits agent configuration
+ * — it prints a snippet. This module is the opt-in counterpart: when the user
+ * explicitly confirms during `arcs project init`, it merges the same hook entry
+ * into the workspace's `.claude/settings.local.json` (local-only: the token is a
+ * secret and `settings.local.json` is the git-ignored variant).
+ *
+ * Two rules the merge must never break:
+ *   1. A malformed existing file ABORTS the write. Silently coalescing an
+ *      unparseable settings file to `{}` would destroy a user's `permissions`
+ *      block over a stray comma, so parse errors are surfaced, not swallowed.
+ *   2. Replacement is keyed on the absolute hook script path, not the project
+ *      slug. A workspace can be reassigned between ARCS projects, so matching on
+ *      the script path leaves exactly one current ARCS entry per event instead
+ *      of accumulating stale ones. Entries belonging to other tools are kept
+ *      untouched, in place.
+ */
+interface HookCommandEntry {
+    type?: string;
+    command?: string;
+    [key: string]: unknown;
+}
+interface HookMatcherEntry {
+    hooks?: HookCommandEntry[];
+    [key: string]: unknown;
+}
+export interface ClaudeSettings {
+    hooks?: Record<string, HookMatcherEntry[]>;
+    [key: string]: unknown;
+}
+export interface ClaudeCodeHookInstallResult {
+    settingsPath: string;
+    token: string;
+    hookScriptPath: string;
+    serverUrl: string;
+    events: string[];
+}
+/** The only file this module ever writes — never `~/.claude/settings.json`. */
+export declare function claudeSettingsLocalPath(workspacePath: string): string;
+/**
+ * Returns a copy of `settings` with the ARCS hook entry registered under every
+ * hook event, replacing any prior entry that runs the same `hookScriptPath`.
+ * Pure — no I/O, so the merge rules are directly testable.
+ */
+export declare function mergeHookIntoSettings(settings: ClaudeSettings, hook: {
+    command: string;
+    hookScriptPath: string;
+}): ClaudeSettings;
+/**
+ * Reads the workspace's `.claude/settings.local.json` (if any), merges in a
+ * freshly provisioned hook, and writes it back owner-only.
+ *
+ * Throws when the existing file is present but unparseable — nothing is written
+ * in that case, so a hand-edited settings file is never clobbered.
+ */
+export declare function installClaudeCodeHook(options: {
+    workspacePath: string;
+    projectDir: string;
+    slug: string;
+    serverUrl?: string;
+}): Promise<ClaudeCodeHookInstallResult>;
+/**
+ * Interactively offers the hook install during `arcs project init`.
+ *
+ * Mirrors `promptAndInstallCodegraph`: a note explaining the offer, a confirm
+ * defaulting to "no", and a manual-fallback hint when declined. Returns the
+ * install result only when a write actually happened; returns `null` on
+ * decline, cancel, or failure. Never throws — `arcs project init` succeeding
+ * matters more than this offer succeeding.
+ */
+export declare function promptAndInstallClaudeCodeHook(options: {
+    workspacePath: string;
+    projectDir: string;
+    slug: string;
+    serverUrl?: string;
+}): Promise<ClaudeCodeHookInstallResult | null>;
+export {};
+//# sourceMappingURL=claude-code-hook-install.d.ts.map

package/dist/utils/claude-code-hook-install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code-hook-install.d.ts","sourceRoot":"","sources":["../../src/utils/claude-code-hook-install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,UAAU,gBAAgB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAC3C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAErE;AAoBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAChD,cAAc,CA2BhB;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CA8FvC;AAED;;;;;;;;GAQG;AACH,wBAAsB,8BAA8B,CAAC,OAAO,EAAE;IAC5D,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,2BAA2B,GAAG,IAAI,CAAC,CAyC9C"}

package/dist/utils/claude-code-hook-install.js

@@ -0,0 +1,211 @@
+/**
+ * Consent-gated writer for the Claude Code session-bridge hook.
+ *
+ * `arcs hooks install-claude-code` deliberately never edits agent configuration
+ * — it prints a snippet. This module is the opt-in counterpart: when the user
+ * explicitly confirms during `arcs project init`, it merges the same hook entry
+ * into the workspace's `.claude/settings.local.json` (local-only: the token is a
+ * secret and `settings.local.json` is the git-ignored variant).
+ *
+ * Two rules the merge must never break:
+ *   1. A malformed existing file ABORTS the write. Silently coalescing an
+ *      unparseable settings file to `{}` would destroy a user's `permissions`
+ *      block over a stray comma, so parse errors are surfaced, not swallowed.
+ *   2. Replacement is keyed on the absolute hook script path, not the project
+ *      slug. A workspace can be reassigned between ARCS projects, so matching on
+ *      the script path leaves exactly one current ARCS entry per event instead
+ *      of accumulating stale ones. Entries belonging to other tools are kept
+ *      untouched, in place.
+ */
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import * as p from "@clack/prompts";
+import color from "picocolors";
+import { HOOK_EVENTS, provisionHookCommand } from "../cli/commands/hooks.js";
+/** The only file this module ever writes — never `~/.claude/settings.json`. */
+export function claudeSettingsLocalPath(workspacePath) {
+    return join(workspacePath, ".claude", "settings.local.json");
+}
+/**
+ * `chmod` that tolerates an absent file and nothing else.
+ *
+ * Used to narrow a settings file BEFORE it is rewritten, where "there is no
+ * file yet" is the ordinary fresh-install outcome and not a failure — the
+ * write's own `mode` covers that path. Every other errno (EPERM on a file this
+ * user does not own, EROFS) means the mode of a token-bearing file is not ours
+ * to set, so it propagates and fails the install closed, exactly as the
+ * trailing chmod does.
+ */
+async function chmodIfPresent(path, mode) {
+    try {
+        await chmod(path, mode);
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT")
+            throw err;
+    }
+}
+/**
+ * Returns a copy of `settings` with the ARCS hook entry registered under every
+ * hook event, replacing any prior entry that runs the same `hookScriptPath`.
+ * Pure — no I/O, so the merge rules are directly testable.
+ */
+export function mergeHookIntoSettings(settings, hook) {
+    const hooks = { ...(settings.hooks ?? {}) };
+    for (const event of HOOK_EVENTS) {
+        const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
+        const preserved = [];
+        for (const entry of existing) {
+            if (!entry || typeof entry !== "object" || !Array.isArray(entry.hooks)) {
+                // Not a shape we understand — leave it exactly as found.
+                preserved.push(entry);
+                continue;
+            }
+            // Strip only OUR command, at the inner level: a matcher entry may mix an
+            // ARCS hook with another tool's, and that other tool must survive.
+            const kept = entry.hooks.filter((h) => !(typeof h?.command === "string" && h.command.includes(hook.hookScriptPath)));
+            if (kept.length === 0)
+                continue;
+            preserved.push({ ...entry, hooks: kept });
+        }
+        preserved.push({ hooks: [{ type: "command", command: hook.command }] });
+        hooks[event] = preserved;
+    }
+    return { ...settings, hooks };
+}
+/**
+ * Reads the workspace's `.claude/settings.local.json` (if any), merges in a
+ * freshly provisioned hook, and writes it back owner-only.
+ *
+ * Throws when the existing file is present but unparseable — nothing is written
+ * in that case, so a hand-edited settings file is never clobbered.
+ */
+export async function installClaudeCodeHook(options) {
+    const settingsPath = claudeSettingsLocalPath(options.workspacePath);
+    let raw;
+    try {
+        raw = await readFile(settingsPath, "utf-8");
+    }
+    catch {
+        // Absent file — start from an empty settings object.
+    }
+    let settings = {};
+    if (raw !== undefined && raw.trim().length > 0) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`${settingsPath} exists but is not valid JSON — fix it manually or delete it, ` +
+                `then re-run \`arcs hooks install-claude-code ${options.slug}\`. Nothing was written.`);
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error(`${settingsPath} is valid JSON but not an object — fix it manually or delete it, ` +
+                `then re-run \`arcs hooks install-claude-code ${options.slug}\`. Nothing was written.`);
+        }
+        settings = parsed;
+    }
+    const provisioned = await provisionHookCommand({
+        projectDir: options.projectDir,
+        slug: options.slug,
+        serverUrl: options.serverUrl,
+    });
+    const merged = mergeHookIntoSettings(settings, provisioned);
+    await mkdir(dirname(settingsPath), { recursive: true });
+    // The merged command embeds `ARCS_HOOK_TOKEN=<value>`, so this file is a
+    // SECOND cleartext copy of the hook token — this one in the user's repo
+    // rather than under ARCS's own data dir. It is narrowed in three steps
+    // because no one of them covers both the fresh and the repair path:
+    //
+    //   1. chmod BEFORE the write, best-effort. `writeFile` is a direct,
+    //      non-atomic open(path, "w", mode): when the file already exists the
+    //      `mode` argument is a no-op and the open merely truncates the inode
+    //      that is there, so without this step the freshly minted token would be
+    //      written into a still-0644 inode and sit world-readable for the write
+    //      plus an await hop. ENOENT is ignored (see chmodIfPresent) because on a
+    //      fresh install there is nothing to narrow yet. This runs AFTER the
+    //      strict parse above, so a file that aborts the install keeps its mode
+    //      as well as its bytes.
+    //   2. `mode` on the write itself. It applies only when the open CREATES the
+    //      inode — which is precisely the fresh path, where it means the inode is
+    //      0600 before the token's first byte reaches it and step 1 had nothing
+    //      to do. (That create-only caveat is exactly the one that does NOT apply
+    //      to the token store's temp+rename writer, where every write installs a
+    //      fresh inode — it bites squarely here.)
+    //   3. chmod after the write, unconditional. Steps 1 and 2 are each a claim
+    //      about how THIS writer behaves — one assumes the inode survives the
+    //      write, the other that the write creates it. Step 3 assumes nothing, so
+    //      "0600 when this function returns" is a postcondition rather than an
+    //      inference from the writer's syscalls.
+    //
+    // What this buys, stated honestly: 0o600 is a cross-user control. It does
+    // nothing against a process running as THIS user, and it does not hide the
+    // token from `ps` — the value is inlined in the hook command string, so every
+    // hook fire still exposes it in the process table. Handing the hook a path
+    // (`ARCS_HOOK_TOKEN_FILE=<path>`) instead of the value would close that; the
+    // mode only closes the on-disk half. Nor can any mode revoke a descriptor
+    // another account already opened on a 0644 file: the write edits that same
+    // inode in place, so such a reader follows the file into the new token. All
+    // three steps are a floor from this point forward, not a retraction of what
+    // was reachable before.
+    //
+    // The `.claude` DIRECTORY is deliberately left exactly as found. Unlike the
+    // hooks dir under ARCS's data dir, which holds nothing but the token, this
+    // one holds the user's other Claude Code files, and narrowing it would be a
+    // hostile surprise in a directory ARCS does not own.
+    await chmodIfPresent(settingsPath, 0o600);
+    await writeFile(settingsPath, `${JSON.stringify(merged, null, 2)}\n`, {
+        encoding: "utf-8",
+        mode: 0o600,
+    });
+    await chmod(settingsPath, 0o600);
+    return {
+        settingsPath,
+        token: provisioned.token,
+        hookScriptPath: provisioned.hookScriptPath,
+        serverUrl: provisioned.serverUrl,
+        events: [...HOOK_EVENTS],
+    };
+}
+/**
+ * Interactively offers the hook install during `arcs project init`.
+ *
+ * Mirrors `promptAndInstallCodegraph`: a note explaining the offer, a confirm
+ * defaulting to "no", and a manual-fallback hint when declined. Returns the
+ * install result only when a write actually happened; returns `null` on
+ * decline, cancel, or failure. Never throws — `arcs project init` succeeding
+ * matters more than this offer succeeding.
+ */
+export async function promptAndInstallClaudeCodeHook(options) {
+    const settingsPath = claudeSettingsLocalPath(options.workspacePath);
+    p.note([
+        "The session-bridge hook lets the ARCS web UI see your Claude Code",
+        "sessions and queue messages for them (delivered at the next prompt).",
+        "",
+        `Writes ${color.cyan(settingsPath)} only — never your global config.`,
+    ].join("\n"), "Optional: Claude Code session bridge");
+    const shouldInstall = await p.confirm({
+        message: "Install the Claude Code session-bridge hook now?",
+        initialValue: false,
+    });
+    if (p.isCancel(shouldInstall) || !shouldInstall) {
+        p.log.info(color.dim(`Install later:  arcs hooks install-claude-code ${options.slug}`));
+        return null;
+    }
+    try {
+        const result = await installClaudeCodeHook(options);
+        p.log.success([
+            `${color.green("✔")} Hook installed → ${color.cyan(result.settingsPath)}`,
+            color.dim("Start a NEW Claude Code session to pick it up — running sessions won't."),
+        ].join("\n"));
+        return result;
+    }
+    catch (err) {
+        p.log.warn([
+            `${color.yellow("⚠")} Could not install the hook: ${err instanceof Error ? err.message : String(err)}`,
+            color.dim(`Install manually later:  arcs hooks install-claude-code ${options.slug}`),
+        ].join("\n"));
+        return null;
+    }
+}
+//# sourceMappingURL=claude-code-hook-install.js.map

package/dist/utils/claude-code-hook-install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code-hook-install.js","sourceRoot":"","sources":["../../src/utils/claude-code-hook-install.ts"],"names":[],"mappings":"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"}