acbridge 0.0.1 → 1.0.1

package/plugin/plugins/alexa/scripts/signal.mjs

@@ -0,0 +1,503 @@
+#!/usr/bin/env node
+// Session-state SIGNAL hook for the Alexa voice-bridge plugin (Profiles — docs/CLAUDE-SIGNALS.md).
+//
+// Goal: turn Claude Code's session lifecycle into a smart-home scene. One script, registered against
+// every state-bearing hook (see hooks.json). It maps the firing hook (+ its payload) onto ONE wire state
+// and POSTs a lightweight signal to the LOCAL hub's loopback control API (POST /local/session/state);
+// a SUCCESSFUL PostToolUse instead posts a state-less context TICK (POST /local/session/context). The
+// hub's RulesEngine fires the matching Profile rule locally (sub-second, never via the relay) — e.g.
+// "lamp blue on working, green on finished". The relay only receives the signal afterwards for read-back.
+// Every POST carries a `context` reading (the transcript-tail usage) feeding the hub's threshold
+// synthesizer (contextLow / contextCritical — the user's per-profile fire-at sliders).
+//
+//   state              native hook            note
+//   ─────────────────  ─────────────────────  ────────────────────────────────────────────────────────
+//   started            SessionStart           source startup/clear; source=compact is SILENT (PostCompact
+//                                             owns compaction — was a spurious `started` pre-expansion)
+//   resumed            SessionStart           source=resume
+//   ended              SessionEnd
+//   working            UserPromptSubmit       + PostToolUse[Failure] on AskUserQuestion/ExitPlanMode —
+//                                             answering/deciding resumes the turn (a plan REJECTION is
+//                                             error-shaped by design and must NOT read as an error)
+//   finished           Stop                   fires at the end of EVERY turn → the hub debounces (gotcha #1)
+//   needsInput         PreToolUse             tool_name=AskUserQuestion (Claude asked YOU a question);
+//                                             also Notification agent_needs_input / elicitation_dialog
+//   planReady          PreToolUse             tool_name=ExitPlanMode (a plan awaits your approval)
+//   idle               Notification           idle_prompt (typed) or the text fallback  ┐ typed
+//   needs_permission   Notification           permission_prompt or the text fallback    ┘ preferred
+//   rateLimited        Notification/StopFail  rate_limit_warning / error_type=rate_limit
+//   error              StopFailure (non-rate-limit) + PostToolUseFailure + Notification mcp_server_error
+//                      + legacy best-effort: PostToolUse whose tool_response signals a hard failure
+//   subagentStart      SubagentStart          ┐
+//   subagentFinished   SubagentStop           │ lifecycle
+//   compacting         PreCompact             │
+//   compactDone        PostCompact            │
+//   permissionDenied   PermissionDenied       │ a tool call auto-blocked without asking
+//   taskCompleted      TaskCompleted          ┘ + Notification agent_completed
+//   workflowStarted    PreToolUse             tool_name=Workflow (multi-agent orchestration kicked off)
+//   contextLow/…       (hub-synthesized)      the SessionContextTracker, from the context readings here
+//   modePlan/modeAuto/… (hub-synthesized)     Claude Code has NO hook/statusline field for a permission-
+//   modeNormal/modeBypass                     mode or model switch, so every POST below FERRIES the raw
+//   modelChanged                              `permissionMode` (payload if present, else the transcript's
+//                                             last `permission-mode` record) + the last assistant model id;
+//                                             the hub diffs them per session (baseline-quiet).
+//
+// ACTIVATION (gotcha #3): resolve this run's hub coordinates from (1) the BRIDGE_* env (the `acbridge run`
+// launch env, which hooks DO inherit — unlike the sanitized MCP env), (2) the per-session handshake file
+// keyed by Claude's own session_id (written by `acbridge run` OR self-written by the channel on a bare
+// `claude --channels …`), or (3) AUTO-PROFILES: if neither exists but the hub is set up on this machine (a
+// hub-token file is present) and auto-profiles is on (default), SELF-DERIVE the id (project@machine). That
+// is what makes lights react on ANY session while the hub daemon runs — the hub only actuates repos BOUND
+// to a Profile, so unbound repos no-op. No hub configured on this machine (no token) ⇒ exit 0, POST nothing.
+// Off-switch: BRIDGE_AUTO_PROFILES=0 or `"autoProfiles": false` in config.json. Voice stays flag-gated
+// (the channel MCP server only boots under `--channels`); only the lights path auto-activates.
+//
+// FAIL-SAFE: any parse/IO/network error ⇒ exit 0. A hook must NEVER block Claude; a dead hub, a missing
+// token, or an unclassifiable event all degrade to a silent no-op. The POST is bounded by a short timeout.
+//
+// Contract: read the hook event JSON on stdin; optionally POST; always exit 0.
+
+import { closeSync, fstatSync, openSync, readFileSync, readSync, writeFileSync } from "node:fs";
+import { request } from "node:http";
+import os from "node:os";
+import path from "node:path";
+import {
+  cleanupPlainSessionHandshake,
+  readActiveUserSub,
+  resolveBridgeHome,
+  resolveHubTokenFile,
+  writePlainSessionHandshakeIfAbsent,
+} from "./scope.mjs";
+
+const DEFAULT_HUB_PORT = 8790; // mirrors @bridge/node-core HUB_PORT — the plugin can't import the workspace
+// WHICH `.claude-bridge` home this run should read (scope.mjs Part C). Usually this process's own — but a
+// session running in WSL while the hub runs on Windows (or vice versa) shares the box's loopback and NOT
+// its home dir, so the token/active-user/sessions files it needs live on the other side. Resolving the
+// home is what makes Profiles fire for a session started ANYWHERE on the machine; without it the hooks
+// silently 401 and then get dropped as account-scope "absent".
+const BRIDGE_HOME = resolveBridgeHome();
+const SECRET_DIR = BRIDGE_HOME.dir;
+/** THIS environment's own home — where a diagnostic breadcrumb belongs (a peer home is read-only to us). */
+const LOCAL_SECRET_DIR = process.env.BRIDGE_SECRET_DIR || path.join(os.homedir(), ".claude-bridge");
+
+/** Exit 0 no matter what — a hook that throws would block the session; we only ever no-op or POST. */
+function done() {
+  process.exit(0);
+}
+
+let event;
+try {
+  event = JSON.parse(readFileSync(0, "utf8") || "{}");
+} catch {
+  done(); // unreadable event → no-op
+}
+if (event === null || typeof event !== "object") done(); // non-object JSON (e.g. `null`, `42`) → nothing to classify
+
+// ── Dormancy gate: resolve THIS run's hub coordinates, exactly like channel/src/index.ts. ────────────
+const isPlaceholder = (v) => Boolean(v) && /^\$\{.*\}$/.test(v); // sanitized-env literal `${BRIDGE_*}`
+const envVar = (v) => (v && !isPlaceholder(v) ? v : undefined);
+
+function resolveHandshake(sessionId) {
+  // Dev / direct path: explicit BRIDGE_* env (Claude launched by `acbridge run`, or any launcher that exports them) wins.
+  const envId = envVar(process.env.BRIDGE_SESSION_ID);
+  if (envId) {
+    return {
+      id: envId,
+      hubPort: Number(envVar(process.env.BRIDGE_HUB_PORT)) || DEFAULT_HUB_PORT,
+      // AS-T9f Part A: env wins; else the scoped step (users/<seg>/hub-token) → machine-global fallback.
+      hubTokenFile: resolveHubTokenFile(SECRET_DIR, envVar(process.env.BRIDGE_HUB_TOKEN_FILE)),
+    };
+  }
+  // Plugin path: correlate via Claude's session id → the per-session handshake file `acbridge run` wrote.
+  if (!sessionId) return null;
+  try {
+    const h = JSON.parse(readFileSync(path.join(SECRET_DIR, "sessions", `${sessionId}.json`), "utf8"));
+    if (!h || !h.id) return null;
+    return {
+      id: h.id,
+      hubPort: Number(h.hubPort) || DEFAULT_HUB_PORT,
+      // AS-T9f Part A: the file's hubTokenFile (scoped, stamped by run.ts/9d) is authoritative; a legacy
+      // file lacking it falls to the scoped step → machine-global.
+      hubTokenFile: resolveHubTokenFile(SECRET_DIR, h.hubTokenFile),
+    };
+  } catch {
+    return null; // ordinary session — no handshake ⇒ dormant
+  }
+}
+
+// Mirror @bridge/node-core machineLabel() + cli loadConfig() inline — the plugin can't import the workspace.
+function readCliConfig() {
+  let file = {};
+  try {
+    file = JSON.parse(readFileSync(path.join(SECRET_DIR, "config.json"), "utf8")) || {};
+  } catch {
+    /* no config file → env + hostname defaults */
+  }
+  return {
+    machine: envVar(process.env.BRIDGE_MACHINE) || file.machine || os.hostname().split(".")[0] || "node",
+    // The resolved home's beacon knows the port the hub ACTUALLY bound, which beats assuming the default
+    // (and is the only source of truth when the hub lives in a peer home whose config.json we don't own).
+    hubPort: Number(envVar(process.env.BRIDGE_HUB_PORT) || BRIDGE_HOME.beacon?.port || file.hubPort || DEFAULT_HUB_PORT),
+    autoProfiles: file.autoProfiles,
+  };
+}
+
+// Auto-profiles is ON by default. Off-switch: BRIDGE_AUTO_PROFILES=0/false, or `"autoProfiles": false`.
+function autoProfilesEnabled(cfg) {
+  const env = process.env.BRIDGE_AUTO_PROFILES;
+  if (env === "0" || env === "false") return false;
+  return cfg.autoProfiles !== false;
+}
+
+// No per-session handshake, but this machine HAS a hub configured (a hub-token file exists). Derive the
+// SAME id acbridge run / the channel would (project@machine) so the hub keys the session identically, and
+// point at the fixed hub coords. Returns null when the bridge was never set up here (no token) ⇒ dormant.
+function selfDeriveHandshake(ev, cfg) {
+  // AS-T9f Part A: scoped-first hub-token (users/<seg>/hub-token) → machine-global. The dormancy gate now
+  // reads whichever the chain resolves — a pinned hub that wrote ONLY a scoped token is still "set up here."
+  const hubTokenFile = resolveHubTokenFile(SECRET_DIR, undefined);
+  try {
+    if (!readFileSync(hubTokenFile, "utf8").trim()) return null;
+  } catch {
+    return null; // no hub token (scoped or machine-global) → bridge not set up on this machine → stay silent
+  }
+  const cwd = typeof ev.cwd === "string" && ev.cwd ? ev.cwd : process.cwd();
+  const project = path.basename(cwd) || "session";
+  const id = `${project}@${cfg.machine}`;
+  // AS-T9f Part B (owner-approved restore): a plain `claude` (no --channels) has NO handshake file, so
+  // AS-T8b's adoption gate classifies its signals "absent" under a pinned hub and DROPS them → auto-profiles
+  // stopped firing. Stamp one ourselves, keyed by Claude's real session id, so the hub adopts it under the
+  // SIGNED-IN account (sub === pinned scope). No account ⇒ nothing written ⇒ unattributable ⇒ still refused;
+  // an acbridge run / channel file is never overwritten; the selfWritten marker keeps gate.mjs dev-freedom.
+  //
+  // RACE-SAFETY — never write at SessionStart: SessionStart hooks are DOCUMENTED to fire BEFORE plugin MCP
+  // servers finish connecting (code.claude.com/docs/en/hooks). So on a bare `claude --channels` VOICE session
+  // the channel hasn't written its (non-selfWritten) handshake yet at SessionStart; writing a selfWritten file
+  // here would let the channel adopt it verbatim ("prefer it verbatim, never overwrite") and gate.mjs would
+  // then treat the VOICE session as plain and drop its credential-read guard. By any LATER hook a voice
+  // session's channel file already exists → resolveHandshake returns it → this self-derive path isn't reached.
+  // A plain session just picks up its handshake (and profiles) from its first post-start activity instead of
+  // the started scene — a small, deliberate cost to keep the voice guard sound.
+  if (String(ev.hook_event_name ?? "") !== "SessionStart") {
+    writePlainSessionHandshakeIfAbsent({
+      secretDir: SECRET_DIR,
+      id,
+      hubPort: cfg.hubPort,
+      hubTokenFile,
+      cwd,
+      claudeSessionId: typeof ev.session_id === "string" ? ev.session_id : undefined,
+      sub: readActiveUserSub(SECRET_DIR),
+    });
+  }
+  return { id, hubPort: cfg.hubPort, hubTokenFile };
+}
+
+const cfg = readCliConfig();
+let handshake = resolveHandshake(typeof event.session_id === "string" ? event.session_id : undefined);
+if (!handshake && autoProfilesEnabled(cfg)) handshake = selfDeriveHandshake(event, cfg);
+if (!handshake) done(); // no bridge session AND no hub configured (or auto-profiles off) — stay silent
+
+// ── Map the firing hook (+ payload) → one wire state, {tick:true} for a context tick, or null. ───────
+const msgExtra = (ev) => (typeof ev.message === "string" && ev.message ? { message: ev.message.slice(0, 120) } : undefined);
+
+function classify(ev) {
+  const name = String(ev.hook_event_name ?? "");
+  switch (name) {
+    case "SessionStart": {
+      const source = String(ev.source ?? "");
+      // A compact "restart" is the SAME session continuing — PostCompact owns compaction (firing
+      // `started` here re-ran the start scene after every auto-compact, the pre-expansion bug).
+      if (source === "compact") return null;
+      return { state: source === "resume" ? "resumed" : "started" };
+    }
+    case "SessionEnd":
+      return { state: "ended" };
+    case "SubagentStart":
+      return { state: "subagentStart", extra: ev.agent_type ? { agent: String(ev.agent_type) } : undefined };
+    case "SubagentStop":
+      return { state: "subagentFinished" };
+    case "PreCompact":
+      return { state: "compacting" };
+    case "PostCompact":
+      // Also what re-arms the hub's context latches (with started/resumed) — see SessionContextTracker.
+      return { state: "compactDone", extra: ev.trigger || ev.compaction_type ? { trigger: String(ev.trigger ?? ev.compaction_type) } : undefined };
+    case "UserPromptSubmit":
+      return { state: "working" };
+    case "Stop":
+      // Fires at the END OF EVERY assistant turn, not once per task (gotcha #1). The hub debounces
+      // per-(session,state); a per-profile finishOn:"idle" refinement lands in P4.
+      return { state: "finished" };
+    case "StopFailure": {
+      // The turn died on an API error. Rate limits get their own state (a very different human action —
+      // stop and wait); everything else (overloaded/auth/billing/server/…) is the error scene.
+      const errorType = String(ev.error_type ?? "");
+      const extra = {
+        ...(errorType ? { errorType } : {}),
+        ...(typeof ev.error_message === "string" && ev.error_message ? { message: ev.error_message.slice(0, 120) } : {}),
+      };
+      return { state: errorType === "rate_limit" ? "rateLimited" : "error", extra: Object.keys(extra).length ? extra : undefined };
+    }
+    case "PreToolUse": {
+      // Registered under the "AskUserQuestion|ExitPlanMode|Workflow" matcher (hooks.json) — double-guarded
+      // here. The first two BLOCK on the human (the question/plan is on screen the moment PreToolUse
+      // fires); Workflow is the multi-agent orchestration kick-off (expect a subagent burst until done).
+      const tool = String(ev.tool_name ?? "");
+      if (tool === "AskUserQuestion") return { state: "needsInput", extra: { tool } };
+      if (tool === "ExitPlanMode") return { state: "planReady", extra: { tool } };
+      if (tool === "Workflow") return { state: "workflowStarted", extra: { tool } };
+      return null;
+    }
+    case "PostToolUse":
+    case "PostToolUseFailure": {
+      const tool = String(ev.tool_name ?? "");
+      // Answering the question / deciding the plan resumes the turn — unconditionally `working`: a plan
+      // REJECTION returns an error-shaped tool_response by design and must NOT flash the error scene.
+      if (tool === "AskUserQuestion" || tool === "ExitPlanMode") return { state: "working", extra: { tool } };
+      if (name === "PostToolUseFailure") {
+        return {
+          state: "error",
+          extra: {
+            ...(tool ? { tool } : {}),
+            ...(typeof ev.error_message === "string" && ev.error_message ? { message: ev.error_message.slice(0, 120) } : {}),
+          },
+        };
+      }
+      // Legacy best-effort error detection (older Claude Code without PostToolUseFailure): fire only when
+      // the tool response explicitly signals a hard failure — biased to UNDER-fire (a failed grep / non-
+      // zero exit the runtime doesn't flag stays silent) so a normal session never flashes the error scene.
+      const resp = ev.tool_response;
+      const isError =
+        resp &&
+        typeof resp === "object" &&
+        (resp.is_error === true ||
+          resp.isError === true ||
+          (typeof resp.error === "string" && resp.error.length > 0));
+      if (isError) return { state: "error", extra: tool ? { tool } : undefined };
+      // A successful tool → a state-less context TICK — the per-tool cadence is what keeps the hub's
+      // context meter fresh during a long working stretch (the threshold sliders' data feed).
+      return { tick: true };
+    }
+    case "PermissionDenied":
+      return { state: "permissionDenied", extra: ev.tool_name ? { tool: String(ev.tool_name) } : undefined };
+    case "TaskCompleted":
+      return { state: "taskCompleted" };
+    case "Notification": {
+      // Prefer the TYPED notification_type (locale-proof); fall back to the message-text regex on older
+      // Claude Code (gotcha #2 — English default, unrecognized degrades to the benign `idle`).
+      const type = String(ev.notification_type ?? "");
+      if (type) {
+        switch (type) {
+          case "permission_prompt":
+            return { state: "needs_permission", extra: msgExtra(ev) };
+          case "idle_prompt":
+            return { state: "idle" };
+          case "agent_needs_input":
+          case "elicitation_dialog":
+            return { state: "needsInput", extra: msgExtra(ev) };
+          case "agent_completed":
+            return { state: "taskCompleted" };
+          case "rate_limit_warning":
+            return { state: "rateLimited", extra: msgExtra(ev) };
+          case "mcp_server_error":
+            return { state: "error", extra: msgExtra(ev) };
+          default:
+            // context_low stays UNMAPPED on purpose — the hub's SessionContextTracker owns the context
+            // states at the USER'S per-profile threshold, not Claude's fixed one. auth_success /
+            // elicitation_* / future types are not device states.
+            return null;
+        }
+      }
+      const msg = String(ev.message ?? "").toLowerCase();
+      const needsPermission = /permission|approve|wants to|needs your/.test(msg);
+      return {
+        state: needsPermission ? "needs_permission" : "idle",
+        extra: msg ? { message: msg.slice(0, 120) } : undefined,
+      };
+    }
+    default:
+      return null; // an unregistered event reached us → nothing to report
+  }
+}
+
+// ── Transcript-tail read: context reading + the mode/model FERRY (states + mode/model expansions). ───
+// Positioned read of the last 64 KB only — transcripts reach tens of MB and this runs per tool call.
+// One backward walk gathers three things:
+//   context — the last MAIN-CHAIN assistant usage (sidechain lines carry a SUBAGENT's usage → skipped);
+//             window: 1M for [1m] model ids, 200k otherwise (the statusline used_percentage formula).
+//   model   — that assistant line's raw model id (the hub diffs it → modelChanged).
+//   mode    — the last `permission-mode` record's raw permissionMode (the hub diffs it → mode states);
+//             the ONLY machine-readable mode source: no hook or statusline field exists (July 2026).
+// Any error → whatever was gathered (usually nothing); the signal still POSTs, just without a reading.
+function readTail(ev) {
+  const out = { context: null, mode: undefined, model: undefined };
+  try {
+    if (typeof ev.transcript_path !== "string" || !ev.transcript_path) return out;
+    const fd = openSync(ev.transcript_path, "r");
+    let text, torn;
+    try {
+      const size = fstatSync(fd).size;
+      const len = Math.min(size, 65536);
+      if (len === 0) return out;
+      const buf = Buffer.alloc(len);
+      readSync(fd, buf, 0, len, size - len);
+      text = buf.toString("utf8");
+      torn = size > len; // the window may open mid-line → the first fragment isn't trustworthy JSON
+    } finally {
+      closeSync(fd);
+    }
+    const lines = text.split("\n");
+    for (let i = lines.length - 1; i >= (torn ? 1 : 0); i--) {
+      const line = lines[i];
+      if (!line || line.charCodeAt(0) !== 123 /* "{" */) continue;
+      let rec;
+      try {
+        rec = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (out.mode === undefined && rec.type === "permission-mode" && typeof rec.permissionMode === "string" && rec.permissionMode) {
+        out.mode = rec.permissionMode; // walking backwards ⇒ the first hit is the LAST record (current mode)
+      }
+      if (out.context) {
+        if (out.mode !== undefined) break; // everything gathered
+        continue;
+      }
+      if (rec.type !== "assistant" || rec.isSidechain === true) continue;
+      const model = rec.message && typeof rec.message.model === "string" && rec.message.model ? rec.message.model : undefined;
+      if (model && out.model === undefined) out.model = model; // newest assistant = the current model
+      const usage = rec.message && rec.message.usage;
+      if (!usage || typeof usage !== "object") continue;
+      const used = (usage.input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0);
+      if (!(used > 0)) continue;
+      // The window CANNOT be read from the transcript: its assistant model id never carries the `[1m]`
+      // context-tier suffix (only the statusline's snap.model.id does — the same asymmetry the hub's
+      // canonicalModelId exists for). Testing for it here was therefore always false, so every
+      // 1M-context session was scored against 200k: a real session at 346,881 tokens reported pct 100
+      // instead of 34.7 and held contextLow + contextCritical tripped for its whole life.
+      //
+      // So ALSO infer the floor from the reading itself — a 200k window cannot hold more than 200k
+      // tokens. The suffix test is kept (it costs nothing and is right whenever an id does carry it);
+      // the token floor is what actually rescues the real transcripts. Both are a FALLBACK for a setup
+      // with no statusline tee — when the tee is installed (the default) it reports the true window and
+      // the hub's resolveContextPct overrides whatever is guessed here.
+      const windowTokens = String(rec.message.model ?? "").includes("[1m]") || used > 200_000 ? 1_000_000 : 200_000;
+      out.context = { pct: Math.min(100, Math.round((used / windowTokens) * 1000) / 10), usedTokens: used, windowTokens };
+      if (out.mode !== undefined) break;
+    }
+    return out;
+  } catch {
+    return out; // unreadable/garbled transcript → whatever was gathered, never a failure
+  }
+}
+
+const mapped = classify(event);
+if (!mapped) done(); // this event carries no state and no tick → no-op
+
+// The session's live context reading + the raw mode/model ferry — attached to every POST. A hook payload's
+// own permission_mode/model_id (if Claude Code ever ships them) beats the transcript-derived values.
+const tail = readTail(event);
+const context = tail.context;
+const mode = typeof event.permission_mode === "string" && event.permission_mode ? event.permission_mode : tail.mode;
+const model = typeof event.model_id === "string" && event.model_id ? event.model_id : tail.model;
+if (mapped.tick && !context && !mode && !model) done(); // a tick with nothing to report → no-op
+
+// ── POST the signal to the local hub, behind the loopback token guard (no Origin ⇒ passes). ──────────
+let token;
+try {
+  token = readFileSync(handshake.hubTokenFile, "utf8").trim();
+} catch {
+  done(); // no token file (hub not up on this machine) → no-op
+}
+if (!token) done();
+
+const ids = {
+  sessionId: handshake.id, // the canonical bridge id (project@machine) the hub registry keys on
+  claudeSessionId: typeof event.session_id === "string" ? event.session_id : undefined,
+  ts: Date.now(),
+  // Carry this run's cwd so the hub can match the profile's repo even if the channel hasn't registered
+  // yet (the started-on-launch race) — the fix that makes EVERY state fire reliably, not just mid-session.
+  ...(typeof event.cwd === "string" ? { cwd: event.cwd } : {}),
+};
+// A tick (successful tool) targets the state-less context route; everything else is a state signal.
+const apiPath = mapped.tick ? "/local/session/context" : "/local/session/state";
+const ferry = { ...(mode ? { mode } : {}), ...(model ? { model } : {}) };
+const payload = JSON.stringify(
+  mapped.tick
+    ? { ...ids, ...(context ? { context } : {}), ...ferry }
+    : {
+        ...ids,
+        state: mapped.state,
+        event: String(event.hook_event_name ?? ""),
+        ...(mapped.extra ? { extra: mapped.extra } : {}),
+        ...(context ? { context } : {}),
+        ...ferry,
+      },
+);
+
+// node:http (not fetch) for zero deps + guaranteed NO Origin header (the guard 403s any Origin) + a hard
+/** One bounded breadcrumb for a REJECTED signal (see the call site). Written to the LOCAL home even when
+ *  the hub lives in a peer one: a peer home is read-only to us by design, and doctor asks about THIS
+ *  environment. Best-effort and silent — a hook must never fail because it could not complain. */
+function recordHookRejection(status) {
+  try {
+    writeFileSync(
+      path.join(LOCAL_SECRET_DIR, "hooks-last-error.json"),
+      JSON.stringify({
+        ts: Date.now(),
+        status,
+        home: BRIDGE_HOME.dir,
+        homeSource: BRIDGE_HOME.source,
+        hubPort: handshake.hubPort,
+        hint:
+          status === 401
+            ? "the hub rejected this machine's hub-token — the hook is reading a stale or foreign one"
+            : "the hub refused the signal",
+      }),
+      { mode: 0o600 },
+    );
+  } catch {
+    /* unwritable home → nothing to do; the signal already failed */
+  }
+}
+
+// timeout. The hub route answers 200 the instant it queues the signal (actuation is fire-and-forget on
+// its side), so this returns in well under the hook budget; the timeout only guards against a dead hub.
+const req = request(
+  {
+    host: "127.0.0.1",
+    port: handshake.hubPort,
+    path: apiPath,
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "content-length": Buffer.byteLength(payload),
+      "x-bridge-hub-token": token,
+    },
+    timeout: 2000,
+  },
+  (res) => {
+    res.on("data", () => {}); // drain
+    res.on("end", () => {
+      // A REJECTED signal used to vanish without trace: the hub answered 401/4xx, this hook exited 0 by
+      // contract, and nothing anywhere recorded that Profiles had stopped working (that is how a stale
+      // hub-token went unnoticed for a whole day). Leave one bounded breadcrumb — in THIS environment's
+      // own home, never the peer's, which we only ever read — for `acbridge doctor` to surface.
+      if ((res.statusCode ?? 0) >= 400) recordHookRejection(res.statusCode ?? 0);
+      // AS-T9f Part B lifecycle: a plain session ENDING. The hub classifies + ingests this "ended" signal
+      // synchronously before answering 200, so by now it has fired the ended scene — safe to reap the
+      // handshake WE self-wrote (cleanupPlainSessionHandshake gates on selfWritten, so a voice writer's
+      // file is never touched). A crash that skips SessionEnd just leaves a harmless stale file (its UUID
+      // sid never recurs → never re-adopted) for a future sessions-dir sweep.
+      if (String(event.hook_event_name ?? "") === "SessionEnd" && typeof event.session_id === "string") {
+        cleanupPlainSessionHandshake(SECRET_DIR, event.session_id);
+      }
+      done();
+    });
+  },
+);
+req.on("timeout", () => {
+  req.destroy();
+  done();
+});
+req.on("error", done); // hub down / connection refused → silent no-op
+req.end(payload);

package/plugin/plugins/alexa/scripts/statusline-guard.mjs

@@ -0,0 +1,75 @@
+// Self-defense for the statusline chain (statusline.mjs's renderChained). PURE + importable on purpose:
+// statusline.mjs reads stdin and process.exit()s at module scope, so it can never be imported by a test —
+// the predicates that decide whether to spawn anything live here instead, and are unit-tested in
+// node-core/test/statusline-guard.test.ts.
+//
+// WHY THIS EXISTS (2026-07-30, DESKTOP-NK51AQV): `~/.claude-bridge/config.json` held a `statusline.prev`
+// pointing at the bridge's OWN statusline script. Every Claude repaint ran statusline.mjs, which read
+// `prev` — itself — and spawned it; the child did the same, forever. DEADLINE_MS bounds each process to
+// ~1.5 s, so it never looked like a leak: it settled into a treadmill of ~372 node.exe (18.65 GB, 85% of
+// host RAM) plus a cmd.exe + conhost.exe per link, all under 2 s old. Killing them achieved nothing — the
+// chain regenerated within 1.5 s. Only breaking the chain fixed it.
+//
+// node-core/src/claude-setup/statusline.ts now (a) never stores our own command as `prev` and (b) heals a
+// config already poisoned. These guards are the independent second layer: they hold even for a poisoned
+// config whose installer never runs again, and for any future path that manages to write a bad `prev`.
+
+/** Set in a chained child's env. Present on entry ⇒ we ARE a chained child ⇒ never chain again, so the
+ *  chain depth can never exceed 1 no matter what `prev` says. */
+export const CHAIN_DEPTH_ENV = "BRIDGE_STATUSLINE_DEPTH";
+
+/** Our script path as it appears inside a built command, either separator (see statusline.ts's OURS_MARKER:
+ *  a `prev` can be the WINDOWS home's, read by a Linux process, when bridge homes are peers). */
+const MARKERS = ["plugins/alexa/scripts/statusline.mjs", "plugins\\alexa\\scripts\\statusline.mjs"];
+
+/** Roots/launchers only the bridge installs under — used to attribute a RELOCATED or renamed copy of our
+ *  script without also claiming a user's unrelated `statusline.mjs`. */
+const BRIDGE_OWNED = /\.claude-bridge|@bridgeapp|bridge-node|ac-bridge/;
+
+const norm = (s) => s.replace(/\\/g, "/").toLowerCase();
+
+/**
+ * Would chaining `cmd` re-enter this script? Three ways to be ours, cheapest first:
+ *   1. it contains our plugin script path (any install root, either separator) — the field case;
+ *   2. it names this exact file (`selfPath`, normally import.meta.url of statusline.mjs);
+ *   3. it names `statusline.mjs` under a bridge-owned root or launcher — a relocated/legacy copy.
+ * Deliberately NOT "any command mentioning statusline.mjs": that would silently swallow a user's own
+ * statusline script of the same name. Ours is always attributable by (1), (2) or (3).
+ */
+export function isSelfReferentialStatusline(cmd, selfPath) {
+  if (typeof cmd !== "string" || !cmd) return false;
+  const s = norm(cmd);
+  if (MARKERS.some((m) => s.includes(norm(m)))) return true;
+  if (typeof selfPath === "string" && selfPath && s.includes(norm(selfPath))) return true;
+  return s.includes("statusline.mjs") && BRIDGE_OWNED.test(s);
+}
+
+/** Should `prev` be spawned at all? Fail CLOSED: any doubt renders the default line instead, which is the
+ *  documented fallback (`else finish(defaultLine())`) and costs the user a cosmetic statusline at worst. */
+export function shouldChain(prev, { env = {}, selfPath } = {}) {
+  if (typeof prev !== "string" || !prev) return false;
+  if (env[CHAIN_DEPTH_ENV]) return false; // we are already a chained child
+  return !isSelfReferentialStatusline(prev, selfPath);
+}
+
+/** The env a chained child gets: everything we have, plus the fuse. */
+export function chainChildEnv(env = {}) {
+  return { ...env, [CHAIN_DEPTH_ENV]: "1" };
+}
+
+/**
+ * PURE: which `statusline.prev` this run may consider, given BOTH bridge homes' parsed configs.
+ *
+ * Only the LOCAL home's config may supply it. node-core writes `prev` to THIS machine's own
+ * ~/.claude-bridge (its SECRET_DIR is never peer-resolved), whereas the RESOLVED hub home is the peer's
+ * across a WSL↔Windows boundary whenever the live hub sits on the other side (scope.mjs Part C). A peer's
+ * `prev` is a command string for the OTHER OS's shell — handing `node "C:\…"` to /bin/sh fails, silently
+ * shadowing the user's real statusline with our default line, and a poisoned peer value would be a
+ * cross-boundary self-reference. Encoded as a function so the choice is pinned by a test instead of
+ * living implicitly in one call site.
+ */
+export function selectStatuslinePrev({ local, resolved } = {}) {
+  void resolved; // accepted to make the contract explicit, and deliberately never read
+  const sl = local && typeof local === "object" ? local.statusline : undefined;
+  return sl && typeof sl.prev === "string" && sl.prev ? sl.prev : null;
+}