ccdeck 3.43.4 → 3.44.0

package/src/server/deck-client.mjs

@@ -0,0 +1,112 @@
+// How a command typed in a terminal talks to the deck already running (#2183).
+//
+// `ccdeck accounts` and `ccdeck switch` are asked over SSH as often as at the
+// desk, by somebody who has no tab open and no wish to forward one. The deck
+// already answers everything they need — the roster, the switch, the sessions
+// it is watching — so the command is a client of it rather than a second
+// implementation beside it.
+//
+// AND IT HAS TO BE. The account store's mutex is in the deck's own process
+// (store-lock.mjs, "not defence against another process"), so a terminal that
+// ran `cswap switch` itself while a deck was up would race the Accounts panel,
+// the auto-switch tick and a sign-in in flight — the race #1039 closed inside
+// the deck. Through the deck, the switch takes that lock, invalidates the
+// roster and the quota the panel is showing, and lands in the swap log, exactly
+// as a click does.
+//
+// THE SAME DOOR `--stop` USES. The registry record (0600, this user's) holds
+// the deck's port and token; a request on 127.0.0.1 with `x-ccdeck-token` and
+// no browser headers is what request-gates.mjs admits for a guarded read and a
+// mutation alike. The token is read again on every call, because a deck that
+// restarted has a new one.
+//
+// A leaf, like stop-deck.mjs: node:http and running-deck.mjs, and nothing that
+// starts a server or arms a timer.
+import { request as httpRequest } from "node:http";
+import { liveDecks } from "./running-deck.mjs";
+
+/** Long enough for a roster read, which can wait on claude-swap's store; short
+ *  enough that a wedged deck does not hold the terminal. A switch passes its
+ *  own, since `cswap switch` is given thirty seconds inside the deck. */
+export const ASK_MS = 10_000;
+
+/**
+ * The deck a command talks to, or null when none is running.
+ *
+ * `--port` names one. Otherwise there is meant to be exactly one — a start
+ * keeps at most one per Claude config directory (running-deck.mjs) — and when a
+ * leftover from before that rule is still up, the newest version wins, then the
+ * lowest port, so the answer is the same every time it is asked.
+ */
+export async function findDeck({ port = null, live = liveDecks } = {}) {
+  const decks = await live().catch(() => []);
+  if (port != null) return decks.find(d => d.port === Number(port)) ?? null;
+  if (!decks.length) return null;
+  return [...decks].sort((a, b) => newer(b.version, a.version) || a.port - b.port)[0];
+}
+
+/** Positive when `a` is a newer x.y.z than `b`. A missing version is oldest. */
+function newer(a, b) {
+  const parts = (v) => String(v ?? "").split(".").map(n => Number.parseInt(n, 10) || 0);
+  const [x, y] = [parts(a), parts(b)];
+  for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0);
+  return 0;
+}
+
+/**
+ * One request to a deck, answered as `{ ok, status, body }`.
+ *
+ * Never rejects, for the reason askDeckToStop gives: every failure is a verdict
+ * the caller has something to say about. `ok` is the HTTP status, and `body` the
+ * parsed JSON or null — the deck's own `{ ok: false, reason }` arrives with a
+ * 400 and is worth more to the reader than the status alone, so it is kept.
+ */
+export function askDeck(rec, { method = "GET", path, body = undefined, timeoutMs = ASK_MS, request = httpRequest } = {}) {
+  return new Promise(resolve => {
+    let settled = false;
+    const finish = (v) => { if (!settled) { settled = true; resolve(v); } };
+    const payload = body === undefined ? null : JSON.stringify(body);
+    let req;
+    try {
+      req = request({
+        hostname: "127.0.0.1",
+        port: rec.port,
+        path,
+        method,
+        timeout: timeoutMs,
+        headers: {
+          // The token, and nothing a browser would send: a request that carried
+          // an Origin or Sec-Fetch-Site would be judged as a page's, and a page
+          // is not who this is.
+          "x-ccdeck-token": String(rec.token ?? ""),
+          ...(payload === null
+            ? { "content-length": "0" }
+            : { "content-type": "application/json", "content-length": String(Buffer.byteLength(payload)) }),
+        },
+      }, res => {
+        let text = "";
+        res.setEncoding("utf8");
+        res.on("data", d => { text += d; });
+        res.on("end", () => {
+          let parsed = null;
+          try { parsed = JSON.parse(text); } catch { /* not JSON: the status speaks */ }
+          const status = res.statusCode ?? 0;
+          finish({ ok: status >= 200 && status < 300, status, body: parsed });
+        });
+        // A reply cut off half way — the deck stopped, or its socket did —
+        // ends with neither `end` nor a request error, and a promise left
+        // waiting for one is a command that never returns.
+        res.on("error", () => {});
+        res.on("close", () => {
+          if (!res.complete) finish({ ok: false, status: res.statusCode ?? 0, body: null, reason: "cut_off" });
+        });
+      });
+    } catch (err) {
+      return finish({ ok: false, status: 0, body: null, reason: err?.code ?? "request_failed" });
+    }
+    req.on("error", err => finish({ ok: false, status: 0, body: null, reason: err?.code ?? "unreachable" }));
+    req.on("timeout", () => { req.destroy(); finish({ ok: false, status: 0, body: null, reason: "timeout" }); });
+    if (payload !== null) req.write(payload);
+    req.end();
+  });
+}

package/src/server/deck-prefs.mjs

@@ -84,6 +84,15 @@ export const DEFAULTS = Object.freeze({
   notifySwap: true,
   notifyQuota: false,
   notifyReset: false,
+  // Sessions that stopped on an expired login or a usage limit, said once per
+  // incident (account-notify.mjs). ON for the swap's reason: it is rare, every
+  // running session is stopped when it happens, and nothing else says so.
+  notifyStopped: true,
+  // Continue a BACKGROUND session whose turn stopped on an expired login or a
+  // usage limit, once a working login with room is active again — once per
+  // stop (stop-continue.mjs, #2193). OFF: it stops and restarts a session's
+  // process on the user's behalf, and that is something a person turns on.
+  continueStopped: false,
   // The Electron window can open on a new localhost port after an update.
   // Its tour marker must outlive that origin; browser tabs still use their
   // own localStorage marker and never read this preference.
@@ -334,6 +343,8 @@ export function normalise(raw) {
     notifySwap: flagOr(src.notifySwap, DEFAULTS.notifySwap),
     notifyQuota: flagOr(src.notifyQuota, DEFAULTS.notifyQuota),
     notifyReset: flagOr(src.notifyReset, DEFAULTS.notifyReset),
+    notifyStopped: flagOr(src.notifyStopped, DEFAULTS.notifyStopped),
+    continueStopped: flagOr(src.continueStopped, DEFAULTS.continueStopped),
     tourSeen: flagOr(src.tourSeen, DEFAULTS.tourSeen),
     autoUpdate: flagOr(src.autoUpdate, DEFAULTS.autoUpdate),
     reports: flagOr(src.reports, DEFAULTS.reports),
@@ -718,7 +729,7 @@ export function publicPrefs(prefs) {
  * here — prefs-route-fields.test.ts lists them.
  */
 export const PAGE_FIELDS = Object.freeze({
-  top: Object.freeze(["notifications", "notifySwap", "notifyQuota", "notifyReset", "tourSeen", "autoUpdate", "recoverCodexSessions", "recoverClaudeSessions"]),
+  top: Object.freeze(["notifications", "notifySwap", "notifyQuota", "notifyReset", "notifyStopped", "continueStopped", "tourSeen", "autoUpdate", "recoverCodexSessions", "recoverClaudeSessions"]),
   lan: Object.freeze([
     "enabled", "name", "shared", "manual", "shareActive", "sendInUse", "pairingMode",
     "autoAsk", "autoAccept", "tailscale", "tailscaleAsk", "tailscaleAccept",
@@ -752,15 +763,15 @@ export function notificationsOn(prefs, env = process.env) {
 }
 
 /**
- * Which account notifications may go out right now: the three switches, each
- * on its own, and all three off when the machine vetoed notifications at
+ * Which account notifications may go out right now: the four switches, each
+ * on its own, and all four off when the machine vetoed notifications at
  * launch — AGENTS_DECK_NO_NOTIFY=1 keeps the deck off the desktop whatever
  * else it was told, and these are desktop notifications too.
  */
 export function accountNotifySettings(prefs, env = process.env) {
-  if (notificationsVetoed(env)) return { swap: false, quota: false, reset: false };
+  if (notificationsVetoed(env)) return { swap: false, quota: false, reset: false, stopped: false };
   const p = normalise(prefs);
-  return { swap: p.notifySwap, quota: p.notifyQuota, reset: p.notifyReset };
+  return { swap: p.notifySwap, quota: p.notifyQuota, reset: p.notifyReset, stopped: p.notifyStopped };
 }
 
 /**

package/src/server/event-pipeline.mjs

@@ -14,9 +14,13 @@ import { PRODUCT } from "./brand.mjs";
 import { createBlockNotifier } from "./block-notify.mjs";
 import { notify as osNotify } from "./browser-react.mjs";
 import { accountNotifySettings, notificationsOn } from "./deck-prefs.mjs";
-// The account notifier — a switch, a quota threshold, a reset — connected below
-// to the same OS call the block notifier uses.
-import { connectAccountNotify } from "./account-watch.mjs";
+// The account notifier — a switch, a quota threshold, a reset, sessions stopped
+// on a dead login — connected below to the same OS call the block notifier
+// uses, and the door a stopped turn is reported through.
+import { connectAccountNotify, noteHookStop } from "./account-watch.mjs";
+// The same stops, and what shows each session working again, for the Continue
+// action and the automatic continue of background sessions (#2193).
+import { noteStopContinue } from "./stop-continue.mjs";
 // The settings as this process holds them — see prefs-state.mjs.
 import { heldPrefs } from "./prefs-state.mjs";
 // The deck's own token, taken back out of every event before the ring, the
@@ -205,6 +209,15 @@ export function pushEvent(raw, source, opts = {}) {
   // know the other exists. block-notify.mjs holds the gates and the cooldown.
   blockNotifier.consider(raw, { clients: pageCount(), replay: !!opts.replay });
 
+  // A turn this machine's Claude Code ended on an expired login or a usage
+  // limit: one notification for the incident, and an auto-switch tick now
+  // rather than at the next interval (account-watch.mjs). A hook's own post
+  // only — a replay is history, and the scanners never send one.
+  if (source === "hook" && !opts.replay) {
+    noteHookStop(raw, evt.receivedAt);
+    noteStopContinue(raw, evt.receivedAt);
+  }
+
   // Persisted history is not current activity. Fresh recovery snapshots are
   // current evidence even though they bypass replayed-tool accounting.
   if (shouldTrackActivity(raw, opts)) activity.note(raw, evt.receivedAt);
@@ -241,6 +254,9 @@ export function pushEvent(raw, source, opts = {}) {
   // Provider gates the path: Claude reads transcript_path; Codex reads its
   // rollout JSONL under ~/.codex/sessions/. The Claude scanners short-circuit
   // when transcript_path is absent (always the case for Codex hooks).
+  if (source === "codex" && !opts.replay && raw?.hook_event_name === "UsageObserved") {
+    maybeResolveCodex(raw, { persist: opts.persist });
+  }
   if (source === "hook" && !opts.replay) {
     // A hook is somebody running the CLI, which is what the day's usage counts.
     usageDay.noteUse(raw);

package/src/server/event-routes.mjs

@@ -17,6 +17,7 @@ import { presentsDeckToken } from "./request-gates.mjs";
 import { SEQ_EPOCH, ringHoldsNewerThan, ringSnapshot } from "./event-ring.mjs";
 // The one door every event comes through — see event-pipeline.mjs.
 import { pushEvent } from "./event-pipeline.mjs";
+import { noteToolAudit } from "./tool-audit.mjs";
 import { noteLogWriter } from "./event-log.mjs";
 // Which CLIs this deck watches — see deck-scope.mjs.
 import { deckProviders } from "./deck-scope.mjs";
@@ -201,6 +202,20 @@ export function handleEventIngest(req, res, persist = true) {
     if (!deckProviders().claude && parsed?.provider === "claude") {
       return send(res, 409, { error: "this deck is not watching Claude" });
     }
+    // A slash command expanding into a prompt (UserPromptExpansion) is counted
+    // for Skill activity and goes no further. The prompt it becomes arrives on
+    // its own UserPromptSubmit, the canvas has nothing to draw for it, and the
+    // reducer would otherwise treat an event it does not know as session
+    // traffic. So it never reaches the ring, the pages or the log.
+    if (parsed?.hook_event_name === "UserPromptExpansion") {
+      try {
+        noteToolAudit(parsed, "hook", {});
+        send(res, 200, { ok: true });
+      } catch (err) {
+        sendInternalError(res, err);
+      }
+      return;
+    }
     // Everything past the parse is inside one net, because this listener is the
     // one place in the route table `guard` cannot reach. The route does wrap the
     // call — `guard(handleEventIngest(req, res, …), res)` — but this function

package/src/server/exec.mjs

@@ -96,8 +96,12 @@ const TIMEOUT_TAIL = 8 << 10;
  * `{...process.env, X: "1"}` to add to it. It exists because the quota probe
  * runs a whole Claude Code and has to mark the run as the deck's own, and that
  * marker is what stops every poll drawing itself onto the canvas.
+ *
+ * `cwd` is the child's working directory, and the deck's own when absent. It
+ * exists for `claude --resume <id> --bg` (stop-continue.mjs): Claude Code
+ * finds a conversation by the project it was started in, and resumes it there.
  */
-export function run(cmd, args, { timeout = 20_000, maxBuffer = 4 << 20, env } = {}) {
+export function run(cmd, args, { timeout = 20_000, maxBuffer = 4 << 20, env, cwd } = {}) {
   const tries = candidates(cmd);
   return new Promise((resolve) => {
     const attempt = (i) => {
@@ -166,7 +170,7 @@ export function run(cmd, args, { timeout = 20_000, maxBuffer = 4 << 20, env } =
         // process, so a shutdown that does not reap it leaves the child with
         // no deadline at all. See `live` in exec-children.mjs, and #1012.
         const cp = watchChild(execFile(file, argv,
-          { timeout: 0, shell: false, windowsHide: true, maxBuffer, ...(env ? { env } : {}), ...opts }, done));
+          { timeout: 0, shell: false, windowsHide: true, maxBuffer, ...(env ? { env } : {}), ...(cwd ? { cwd } : {}), ...opts }, done));
         // Give the child EOF on stdin straight away, which is what this
         // function's contract has always claimed ("run closes stdin", says
         // runInteractive's header) and what execFile does not do: it leaves the

package/src/server/index.mjs

@@ -29,6 +29,8 @@ export { MAX_BUFFER, MAX_BUFFER_CHARS, MAX_RING_ENTRIES, payloadChars } from "./
 // The ring itself — what it holds, how it numbers them, and the eviction that
 // keeps those bounds — private behind its operations. See event-ring.mjs.
 import { eventsSince } from "./event-ring.mjs";
+// The same ring folded to one row per session, for `ccdeck sessions` (#2183).
+import { summarizeSessions } from "./session-summary.mjs";
 // Exported from this file before they moved, and still.
 export { eventBufferStats, eventsSince } from "./event-ring.mjs";
 // The one door every event comes through, and what it does to each on the way
@@ -36,6 +38,7 @@ export { eventBufferStats, eventsSince } from "./event-ring.mjs";
 // routes below: it connects pushEvent to event-sink.mjs as it loads, and the
 // boot replay pushes through that sink before any route has run.
 import "./event-pipeline.mjs";
+import { stopCodexEnrichment } from "./codex-enrichment.mjs";
 // POST /api/event, GET /events and GET /api/events — see event-routes.mjs.
 import { handleEventIngest, handleSse, writeJsonArray } from "./event-routes.mjs";
 // Exported from this file before it moved, and still.
@@ -159,6 +162,7 @@ import { send, sendInternalError } from "./http-io.mjs";
 export { sendInternalError };
 // The accounts surface's routes — see account-routes.mjs. The boot wires the
 // stale-copy repair and starts auto-switch through the same module.
+import { handleStopContinue, handleStopContinueRead } from "./stop-continue.mjs";
 import { cswapAutoModule, getProjectRollup, handleAccountLoginState, handleAccountProjects, handleClaudeAccountAdmin, handleClaudeAccountSwitch, handleClaudeAccounts, handleCswapAuto, handleCswapAutoAction, wireAccountOrigins, wireStaleCopyRepair } from "./account-routes.mjs";
 // Browser Watch's three routes — see browser-watch-routes.mjs.
 import { handleBrowserWatch, handleBrowserWatchDismiss, handleBrowserWatchSettings } from "./browser-watch-routes.mjs";
@@ -389,6 +393,10 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     if (req.method === "POST" && url.pathname === "/api/claude-accounts/switch") return guard(handleClaudeAccountSwitch(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/claude-accounts/login")  return guard(handleAccountLoginState(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/claude-accounts/admin")  return guard(handleClaudeAccountAdmin(req, res), res);
+    // Continue a session whose turn stopped on a login or a usage limit (#2193):
+    // the gate's evidence and each session's outcome, and the press itself.
+    if (req.method === "GET"  && url.pathname === "/api/stop-continue") return guard(handleStopContinueRead(req, res), res);
+    if (req.method === "POST" && url.pathname === "/api/stop-continue") return guard(handleStopContinue(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/cswap-auto")  return guard(handleCswapAuto(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/cswap-auto")  return guard(handleCswapAutoAction(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/claude-fm")   return guard(handleClaudeFm(req, res), res);
@@ -408,6 +416,11 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     if (req.method === "GET" && url.pathname === "/api/events") {
       return guard(writeJsonArray(res, eventsSince(url.searchParams.get("since") ?? 0)), res);
     }
+    // GET /api/sessions — which sessions this deck is watching and which of
+    // them waits on a human, without the ring itself. See session-summary.mjs.
+    if (req.method === "GET" && url.pathname === "/api/sessions") {
+      return send(res, 200, { ok: true, now: Date.now(), sessions: summarizeSessions(eventsSince(0)) });
+    }
 
     // GET /api/clear — what a POST to this path would do, and to whose log.
     // See handleClearPreview.
@@ -514,7 +527,10 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
       void trafficCapture.resume(boundPort).catch(() => {});
       server.once("close", () => trafficCapture.dispose());
       // Codex has no working hooks on Windows — tail its rollout files instead.
-      if (codex) startCodexWatcher(workspace);
+      if (codex) {
+        startCodexWatcher(workspace);
+        server.once("close", stopCodexEnrichment);
+      }
       if (claude) {
         const recovery = createClaudeRecovery({ workspace });
         const recover = () => { void recovery.scan().catch(() => {}); };

package/src/server/installer.mjs

@@ -6,16 +6,21 @@
 // running server still sees both CLIs. Re-runs are safe; entries are tagged
 // with __agent-dag and de-duped.
 import { hookRuntime } from "./app-host.mjs";
-import { readFile, mkdir } from "node:fs/promises";
+import { readFile, mkdir, unlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { claudeConfigDir } from "./claude-dir.mjs";
+import { claudeCodeVersions, claudeConfigDir, claudeVersionAtLeast } from "./claude-dir.mjs";
+// The first Claude Code that knows StopFailure — see stop-failure.mjs.
+import { STOP_FAILURE, STOP_FAILURE_SINCE } from "./stop-failure.mjs";
 import { CODEX_HOME } from "./codex-dir.mjs";
 import { shellQuoteArg } from "./exec.mjs";
 // The read-before-rewrite and the atomic replace every settings writer goes
 // through — see atomic-write.mjs.
-import { readSettingsForWrite, writeFileAtomic } from "./atomic-write.mjs";
+import { readSettingsForWrite, writeFileAtomic, createTemp, renameWithRetry } from "./atomic-write.mjs";
+// Skill activity's typed-command entry, its opt-in and its version gate — see
+// skill-hook.mjs for why it is not in CLAUDE_EVENTS.
+import { USER_PROMPT_EXPANSION, skillHookDecision } from "./skill-hook.mjs";
 // The discovery dir every deck registers in and every hook reads — see
 // discovery.mjs, which keeps this deck's record there.
 import { AGENT_DAG_DIR } from "./discovery.mjs";
@@ -45,11 +50,46 @@ const CLAUDE_EVENTS = [
   "Notification",
 ];
 
+/**
+ * The events Claude Code added after the ones above, each beside the first
+ * version that knows it — added only where EVERY Claude Code the deck finds on
+ * the machine is at least that version.
+ *
+ * Not an event the older CLI would merely ignore. Until 2.1.101 an event name
+ * Claude Code did not recognise made it ignore the whole settings.json: the
+ * user's permissions, env and hooks, and every one of ours with them (Claude
+ * Code's changelog, 2.1.101). StopFailure arrived in 2.1.78, so a machine still
+ * on anything before that would lose its settings to the entry meant to tell it
+ * more.
+ *
+ * So the version is read off disk (claudeCodeVersions — never a `claude
+ * --version`, which is seconds at boot), and a machine where the deck can find
+ * no version gets none of these: the deck it had before, and a line in the
+ * README saying why. Every boot reinstalls, so a Claude Code updated past the
+ * gate picks the entry up on the deck's next start — and one rolled back below
+ * it has the entry taken back out, the same way.
+ */
+const VERSIONED_CLAUDE_EVENTS = [
+  { event: STOP_FAILURE, since: STOP_FAILURE_SINCE },
+];
+
+/** Which of `versioned` this machine's Claude Code knows: those whose `since`
+ *  every found version is at least, and none when no version was found. */
+function eventsKnownTo(versions, versioned = VERSIONED_CLAUDE_EVENTS) {
+  const found = Array.isArray(versions) ? versions : [];
+  if (found.length === 0) return [];
+  return versioned.filter(v => found.every(ver => claudeVersionAtLeast(ver, v.since))).map(v => v.event);
+}
+
 const PROVIDERS = {
   claude: {
     settingsPath: join(CLAUDE_DIR, "settings.json"),
     hookInstallDir: join(CLAUDE_DIR, "agent-dag"),
     events: CLAUDE_EVENTS,
+    versioned: VERSIONED_CLAUDE_EVENTS,
+    // UserPromptExpansion, for Skill activity (#2181): opt-in, and gated on
+    // every Claude Code found being 2.1.116 or newer (skill-hook.mjs).
+    skillHook: true,
     ensureDir: CLAUDE_DIR,
   },
   // Uninstall-only. Codex hooks do not fire reliably on Windows, so the deck
@@ -336,8 +376,82 @@ async function soundHookRetirement(provider, cfg, current) {
   return { retire, completeSoundHookRetirement };
 }
 
-/** Install hooks for a single provider. Returns {settingsPath, hookPath, events, changed}. */
-export async function installHooks({ provider = "claude", beforeWrite = null } = {}) {
+/**
+ * Where the settings.json bytes from before the UserPromptExpansion entry was
+ * first added are kept: beside hook.js, in the directory that is ours. Written
+ * once per enabling — the pass that adds the entry where none of ours was —
+ * with mode 0600, because settings.json can hold API keys in its `env`.
+ * `--uninstall` leaves it, as it leaves hook.js: it is the user's own data.
+ */
+export const SKILL_HOOK_BACKUP = "settings.before-skill-hook.json";
+
+/** Whether a group list holds a forwarder of ours. */
+function holdsOurs(groups) {
+  return Array.isArray(groups) && groups.some(isOurEntry);
+}
+
+/** Whether the entry can be added without guessing: `hooks` absent or a plain
+ *  object, and any UserPromptExpansion already there a list. Anything else is
+ *  a file shaped in a way this deck did not write and Claude Code may not read,
+ *  and adding to it is not a decision to take on the user's behalf. */
+function skillHookFits(settings) {
+  const hooks = settings.hooks;
+  if (hooks === undefined) return true;
+  if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) return false;
+  const now = hooks[USER_PROMPT_EXPANSION];
+  return now === undefined || Array.isArray(now);
+}
+
+/** The backup, through a temp file and a rename like every settings write,
+ *  created 0600 and kept 0600. */
+async function writeBackup(path, text) {
+  const { tmp, handle } = await createTemp(path, { mode: 0o600 });
+  try {
+    try {
+      await handle.writeFile(text, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await renameWithRetry(tmp, path);
+  } catch (err) {
+    await unlink(tmp).catch(() => {});
+    throw err;
+  }
+}
+
+/**
+ * Whether this pass adds Skill activity's entry: the gate's decision
+ * (skill-hook.mjs), then two refusals of the installer's own — a settings file
+ * whose hooks are not in a shape to add to, and a backup that could not be
+ * written. Either leaves the entry out; neither stops the rest of the install.
+ * `options` is the suite's: skillHookDecision's options, in place of this
+ * machine's environment and disk.
+ */
+async function decideSkillHook(options, settings, before, backupPath) {
+  const decision = await skillHookDecision(options ?? {});
+  if (!decision.install) return decision;
+  if (!skillHookFits(settings)) return { ...decision, install: false, state: "skipped", reason: "settings-shape" };
+  // The bytes the write is about to replace, kept before anything is changed,
+  // the first time the entry goes in. Nothing to keep when there was no file.
+  if (before !== null && !holdsOurs(settings.hooks?.[USER_PROMPT_EXPANSION])) {
+    try {
+      await writeBackup(backupPath, before);
+    } catch {
+      return { ...decision, install: false, state: "skipped", reason: "backup-failed" };
+    }
+    return { ...decision, backup: backupPath };
+  }
+  return decision;
+}
+
+/** Install hooks for a single provider. Returns {settingsPath, hookPath, events, changed}.
+ *  `claudeVersions` is the suite's: the Claude Code versions to gate the
+ *  versioned events on, in place of the ones on this machine's disk.
+ *  `skillHook` is the suite's too: skillHookDecision's options (the opt-in,
+ *  the installs found, the probe), in place of this machine's. The answer
+ *  carries the decision as `skillHook` for the claude provider. */
+export async function installHooks({ provider = "claude", beforeWrite = null, claudeVersions = null, skillHook = null } = {}) {
   const cfg = PROVIDERS[provider];
   if (!cfg) throw new Error(`unknown provider: ${provider}`);
   // An uninstall-only provider has no event list. Saying so beats the
@@ -357,13 +471,38 @@ export async function installHooks({ provider = "claude", beforeWrite = null } =
   // Discovery dir is shared across providers — always make sure it exists.
   await ensureDir(AGENT_DAG_DIR);
 
+  // Decided before `hooks` is touched, so the shape check sees the file as read.
+  const skill = cfg.skillHook
+    ? await decideSkillHook(skillHook, current, before, join(cfg.hookInstallDir, SKILL_HOOK_BACKUP))
+    : null;
+
   current.hooks = current.hooks ?? {};
 
-  for (const evt of cfg.events) {
+  const versioned = cfg.versioned ?? [];
+  const known = versioned.length ? eventsKnownTo(claudeVersions ?? claudeCodeVersions(), versioned) : [];
+  if (skill?.install) known.push(USER_PROMPT_EXPANSION);
+  // Every event whose entry is ours only while a gate says so.
+  const gated = [...versioned.map(v => v.event), ...(skill ? [USER_PROMPT_EXPANSION] : [])];
+  const events = [...cfg.events, ...known];
+  for (const evt of events) {
     const cleaned = dedupeOurEntries(current.hooks[evt]);
     cleaned.push(buildHookEntry(command));
     current.hooks[evt] = cleaned;
   }
+  // A gated event this machine's Claude Code does not know — or, for Skill
+  // activity's, one nobody asked for — loses our entry, and the key goes with
+  // it when nothing of the user's is left under it: that key is the thing an
+  // older Claude Code cannot read.
+  // A value under that key that is not a list, or a list with nothing of ours
+  // in it, is left exactly as it is: it is not this deck's to delete.
+  for (const event of gated) {
+    const was = current.hooks[event];
+    if (known.includes(event) || !Array.isArray(was)) continue;
+    const cleaned = dedupeOurEntries(was);
+    if (cleaned.length === was.length && cleaned.every((g, i) => g === was[i])) continue;
+    if (cleaned.length === 0) delete current.hooks[event];
+    else current.hooks[event] = cleaned;
+  }
 
   // Retiring the finish-sound hook rides in here, on this read and this write,
   // and this is the seam it needs rather than a convenient one. #704 moved the
@@ -421,8 +560,10 @@ export async function installHooks({ provider = "claude", beforeWrite = null } =
     // and from the park that was its only other copy.
     if (!(await unchangedSince(cfg.settingsPath, before))) {
       return {
-        settingsPath: cfg.settingsPath, hookPath, events: cfg.events, provider,
+        settingsPath: cfg.settingsPath, hookPath, events, provider,
         changed: false, raced: true, retire: { ...retire, pending: false },
+        // Nothing was written, so an entry decided on is not on disk.
+        ...(skill ? { skillHook: skill.install ? { ...skill, install: false, state: "skipped", reason: "raced" } : skill } : {}),
       };
     }
     await writeFileAtomic(cfg.settingsPath, next);
@@ -431,7 +572,7 @@ export async function installHooks({ provider = "claude", beforeWrite = null } =
   // is what a live session's cached command still names until the new entry is
   // on disk, and deleting it early turns a stale sound into a missing module.
   if (retire.pending) await completeSoundHookRetirement(retire, current);
-  return { settingsPath: cfg.settingsPath, hookPath, events: cfg.events, provider, changed, retire };
+  return { settingsPath: cfg.settingsPath, hookPath, events, provider, changed, retire, ...(skill ? { skillHook: skill } : {}) };
 }
 
 /**

package/src/server/lan-engine.mjs

@@ -107,7 +107,7 @@ export function defaultName() {
  *
  * It returned the first one, and that was wrong the first time somebody
  * checked: on this machine the first is 192.168.1.82 and the deck it needs to
- * reach is on Tailscale at 100.67.32.58, so the panel would have offered an
+ * reach is on Tailscale at 100.64.0.100, so the panel would have offered an
  * address that peer cannot route to and left them to work out why.
  *
  * WHICH ONE IS RIGHT DEPENDS ON WHERE THE PEER IS, which this side cannot
@@ -654,7 +654,7 @@ export function createEngine({
       // WHO IS ACTUALLY THERE. A typed address is a row that says `192.168.1.5:54340`
       // and nothing else until somebody answers it — and once one has, the deck
       // on the other end has told us what it calls itself. The row says that
-      // from then on, because "Constantin-PC" is what the person who typed the
+      // from then on, because "Consultant-PC" is what the person who typed the
       // address was trying to reach.
       //
       // A DIAL-BACK THAT ANSWERED IS AN ORDINARY PEER NOW. It was on trial only

package/src/server/lan-sync.mjs

@@ -288,8 +288,8 @@ function machineKey() {
  * The part of a hostname that names the machine, rather than the network it is
  * on at the moment.
  *
- * macOS answers `os.hostname()` with `Petrus-MacBook-Pro.local` at one moment
- * and `Petrus-MacBook-Pro` at another, and a DHCP server can hang its own
+ * macOS answers `os.hostname()` with `Oswald-MacBook-Pro.local` at one moment
+ * and `Oswald-MacBook-Pro` at another, and a DHCP server can hang its own
  * domain on the end — `.lan`, `.home`, `.fritz.box`. hostId hashed whatever it
  * was handed, so two decks on one computer started either side of such a change
  * disagreed about which machine they were on. Sharing a key, each read the other
@@ -418,7 +418,7 @@ export function beaconVerdict(beacon, { selfFp, selfInstance, selfHost, formerHo
     // taking a new key is the engine's to do.
     //
     // AND ONE MACHINE'S OWN TWIN IS NOT A CLASH, which is the whole of a defect
-    // reported as "Fiodor pressed yes ten times and it keeps asking". Several
+    // reported as "Elliot pressed yes ten times and it keeps asking". Several
     // decks on one computer share a config directory, so they start with one
     // key; each read the others' beacons as somebody wearing its name, each
     // took a fresh key, each wrote that key to the file the others read — and

package/src/server/lan-wire.mjs

@@ -397,9 +397,9 @@ export function credentialAad(fromFp, toFp, key) {
 // two engines of the version before this, the round that healed one account
 // and added another read, after `ok`:
 //
-//   {"t":"manifest","accounts":[{"key":"claude1@sapec.md@@org-1","email":"claude1@sapec.md","alive":true},…],"current":{"key":"claude1@sapec.md@@org-1"}}
-//   {"t":"want","key":"claude2@sapec.md@@org-2","nonce":"…","proof":"…"}
-//   {"t":"have","key":"claude2@sapec.md@@org-2","sealed":{…}}
+//   {"t":"manifest","accounts":[{"key":"alice@example.net@@org-1","email":"alice@example.net","alive":true},…],"current":{"key":"alice@example.net@@org-1"}}
+//   {"t":"want","key":"bob@example.net@@org-2","nonce":"…","proof":"…"}
+//   {"t":"have","key":"bob@example.net@@org-2","sealed":{…}}
 //
 // So anybody on the same network segment could read every address a deck
 // shares, which of its copies are broken, which one the machine is on, and