@mattstack/rt-client 0.23.0 → 0.25.0

package/dist/commands.d.ts

@@ -123,8 +123,10 @@ export interface GateQuestion {
     multi: boolean;
     options: GateOption[];
 }
-export declare function gateOptionValue(o: GateOption): string;
-export declare function gateOptionLabel(o: GateOption): string;
+/** Implementations live in gate-options.ts (the browser-safe ./gate
+    subpath); re-exported here so existing commands.ts/index.ts consumers
+    are unaffected. */
+export { gateOptionValue, gateOptionLabel } from "./gate-options.ts";
 /** `session` is the answering surface's own session id, recorded so the
     push facility can tell a self-answer from a remote one and skip the
     doorbell it would otherwise send back to the writer. Optional: a caller

package/dist/gate-options.d.ts

@@ -6,6 +6,8 @@ export interface GateOptionObject {
     value: string;
     label: string;
 }
+export declare function gateOptionValue(o: GateOption): string;
+export declare function gateOptionLabel(o: GateOption): string;
 /** Bare string s becomes {value: s, label: s}; a well-formed {value,label}
     object passes through untouched. Total over whatever actually arrives
     on the wire, not just the declared GateOption union: a partial object

package/dist/gate.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Browser-safe entry point (the "./gate" subpath export): the pure gate
+ * helpers only, so a browser bundle (mattstack-apps gate-kit) never drags in
+ * commands.ts's Node-only neighbors the way importing from "." would.
+ */
+export * from "./gate-answers.ts";
+export * from "./gate-options.ts";
+export * from "./gate-presentation.ts";
+export type { GateOption, GateQuestion, GateAnswer } from "./commands.ts";

package/dist/gate.js

@@ -0,0 +1,103 @@
+// src/gate-options.ts
+function gateOptionValue(o) {
+  return typeof o === "string" ? o : o.value;
+}
+function gateOptionLabel(o) {
+  return typeof o === "string" ? o : o.label || o.value;
+}
+var RECOMMENDED_SUFFIX = " (Recommended)";
+var HAS_RECOMMENDED_SUFFIX = /\(\s*recommended\s*\)\s*$/i;
+function isWordLikeLabel(label) {
+  return /^[a-z][^A-Z0-9/:\\@]*$/.test(label);
+}
+function capitalize(label) {
+  return isWordLikeLabel(label) ? label[0].toUpperCase() + label.slice(1) : label;
+}
+function normalizeGateOptions(options) {
+  return options.map((o) => {
+    const recommended = o !== null && typeof o === "object" && o.recommended === true;
+    let value;
+    let label;
+    if (typeof o === "string") {
+      value = o;
+      label = o;
+    } else if (o !== null && typeof o === "object") {
+      const v = typeof o.value === "string" ? o.value : undefined;
+      const l = typeof o.label === "string" ? o.label : undefined;
+      value = v ?? l ?? String(o);
+      label = l ?? v ?? String(o);
+    } else {
+      value = String(o);
+      label = String(o);
+    }
+    label = capitalize(label);
+    if (recommended && label && !HAS_RECOMMENDED_SUFFIX.test(label))
+      label += RECOMMENDED_SUFFIX;
+    return { value, label };
+  });
+}
+function normalizeGateQuestions(questions) {
+  return questions.map((q) => ({ ...q, options: normalizeGateOptions(q.options) }));
+}
+
+// src/gate-answers.ts
+function unwrapGateAnswerValue(raw) {
+  if (raw && typeof raw === "object" && !Array.isArray(raw) && "value" in raw) {
+    return raw.value;
+  }
+  return raw;
+}
+function wrapperNoteIsValid(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw) || !("value" in raw)) {
+    return true;
+  }
+  const note = raw.note;
+  return note === undefined || typeof note === "string";
+}
+function validateGateAnswers(questions, answers) {
+  const byId = new Map(questions.map((q) => [q.id, q]));
+  for (const [qid, raw] of Object.entries(answers)) {
+    const question = byId.get(qid);
+    if (!question)
+      return `unknown question id: ${qid}`;
+    if (!wrapperNoteIsValid(raw))
+      return `question ${qid} note must be a string`;
+    const value = unwrapGateAnswerValue(raw);
+    const isArray = Array.isArray(value);
+    if (question.multi && !isArray)
+      return `question ${qid} expects an array (multi)`;
+    if (!question.multi && isArray)
+      return `question ${qid} expects a single value`;
+    const values = isArray ? value : [value];
+    if (!values.every((v) => typeof v === "string"))
+      return `question ${qid} value must be a string`;
+    if (question.options.length > 0) {
+      const members = question.options.map(gateOptionValue);
+      for (const v of values) {
+        if (!members.includes(v))
+          return `answer for "${qid}" is not one of its options: "${v}"`;
+      }
+    }
+  }
+  const missing = questions.map((q) => q.id).filter((id) => !Object.prototype.hasOwnProperty.call(answers, id));
+  if (missing.length > 0)
+    return `missing answer(s) for: ${missing.join(", ")}`;
+  return null;
+}
+// src/gate-presentation.ts
+var GATE_FORM_OPTION_CAP = 4;
+function gatePresentation(args) {
+  if (!args.paneId || !args.sessionId)
+    return "wait";
+  return args.questions.every((q) => q.options.length <= GATE_FORM_OPTION_CAP) ? "form" : "wait";
+}
+export {
+  validateGateAnswers,
+  unwrapGateAnswerValue,
+  normalizeGateQuestions,
+  normalizeGateOptions,
+  gatePresentation,
+  gateOptionValue,
+  gateOptionLabel,
+  GATE_FORM_OPTION_CAP
+};

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { rtCommand, DEFAULT_SOCK } from "./transport.ts";
 export type { RtResponse, RtClientOptions } from "./transport.ts";
+export { guardTestDaemonEnv } from "./test-isolation.ts";
 export { readProjectMRs, readDiscussions, readMrsByBranch, readBranchCache, resolveForgeToken, listRuns, getRun, abandonRun, chatJoin, chatLeave, chatAck, chatClaim, chatRelease, chatPost, chatRead, chatRooms, chatWho, chatMark, chatMessages, chatSignIn, chatSignOut, chatAway, chatBack, chatBuddies, chatDm, chatArchive, chatDmOpen, eventsHead, eventsEmit, eventsWait, eventsList, agentStart, agentResume, agentGet, agentList, paneList, panePeek, paneSpawn, paneAccounts, paneDirectories, chatInvite, paneSend, paneFocus, reconcilerStatus, reconcilerClear, gateOpen, gateAsk, gateAnswer, gateWait, gateList, gatePark, gateClose, gateSubscribe, gateUnsubscribe, gateSubscriptions, herdStart, herdSpawn, herdAsk, herdMilestone, herdAnswer, herdReport, herdGates, herdStatus, herdList, herdResume, herdClose, herdAttend, herdWrapUp, herdStopHidden, bgEnsure, bgStatus, bgStop, bgRelease, } from "./client.ts";
 export { COMMAND_NAMES, GATE_BY_PANE, gateOptionValue, gateOptionLabel } from "./commands.ts";
 export { GATE_FORM_OPTION_CAP, gatePresentation } from "./gate-presentation.ts";

package/dist/index.js

@@ -2,14 +2,52 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/transport.ts
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+
+// src/test-isolation.ts
 import { homedir } from "os";
 import { join } from "path";
+function parseForbidSocks(raw) {
+  const parsed = JSON.parse(raw);
+  if (!Array.isArray(parsed) || parsed.some((path) => typeof path !== "string")) {
+    throw new Error("rt-client: RT_TEST_FORBID_SOCKS must be a JSON string array of socket paths");
+  }
+  return parsed;
+}
+function guardTestDaemonEnv(env = process.env) {
+  const forbidden = new Set;
+  if (env.RT_TEST_FORBID_SOCKS) {
+    for (const path of parseForbidSocks(env.RT_TEST_FORBID_SOCKS))
+      forbidden.add(path);
+  }
+  if (env.RT_DAEMON_SOCK)
+    forbidden.add(env.RT_DAEMON_SOCK);
+  if (env.RT_APP_SOCKET)
+    forbidden.add(env.RT_APP_SOCKET);
+  forbidden.add(join(env.HOME ?? homedir(), ".mattstack", "rt", "rt.sock"));
+  delete env.RT_DAEMON_SOCK;
+  delete env.RT_APP_SOCKET;
+  env.RT_TEST_FORBID_SOCKS = JSON.stringify([...forbidden]);
+}
+
+// src/transport.ts
 function defaultSock() {
-  return process.env.RT_DAEMON_SOCK || join(process.env.HOME ?? homedir(), ".mattstack", "rt", "rt.sock");
+  return process.env.RT_DAEMON_SOCK || join2(process.env.HOME ?? homedir2(), ".mattstack", "rt", "rt.sock");
 }
 var DEFAULT_SOCK = defaultSock();
+function assertSockNotForbidden(cmd, sockPath) {
+  const raw = process.env.RT_TEST_FORBID_SOCKS;
+  if (!raw)
+    return;
+  const forbidden = parseForbidSocks(raw);
+  if (forbidden.includes(sockPath)) {
+    throw new Error(`rt-client: refusing "${cmd}" at forbidden socket ${sockPath}: RT_TEST_FORBID_SOCKS marks it as a live daemon socket, so this dispatch would have escaped test isolation`);
+  }
+}
 async function rtCommand(cmd, payload, opts = {}) {
   const sockPath = opts.sockPath ?? defaultSock();
+  assertSockNotForbidden(cmd, sockPath);
   try {
     const res = await fetch(`http://localhost/${cmd}`, {
       unix: sockPath,
@@ -418,14 +456,50 @@ function bgStop(o = {}) {
 function bgRelease(a, o = {}) {
   return rtCommand("bg:release", { claim: a.claim }, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 1e4 });
 }
-// src/commands.ts
-var GATE_BY_PANE = "pane";
+// src/gate-options.ts
 function gateOptionValue(o) {
   return typeof o === "string" ? o : o.value;
 }
 function gateOptionLabel(o) {
   return typeof o === "string" ? o : o.label || o.value;
 }
+var RECOMMENDED_SUFFIX = " (Recommended)";
+var HAS_RECOMMENDED_SUFFIX = /\(\s*recommended\s*\)\s*$/i;
+function isWordLikeLabel(label) {
+  return /^[a-z][^A-Z0-9/:\\@]*$/.test(label);
+}
+function capitalize(label) {
+  return isWordLikeLabel(label) ? label[0].toUpperCase() + label.slice(1) : label;
+}
+function normalizeGateOptions(options) {
+  return options.map((o) => {
+    const recommended = o !== null && typeof o === "object" && o.recommended === true;
+    let value;
+    let label;
+    if (typeof o === "string") {
+      value = o;
+      label = o;
+    } else if (o !== null && typeof o === "object") {
+      const v = typeof o.value === "string" ? o.value : undefined;
+      const l = typeof o.label === "string" ? o.label : undefined;
+      value = v ?? l ?? String(o);
+      label = l ?? v ?? String(o);
+    } else {
+      value = String(o);
+      label = String(o);
+    }
+    label = capitalize(label);
+    if (recommended && label && !HAS_RECOMMENDED_SUFFIX.test(label))
+      label += RECOMMENDED_SUFFIX;
+    return { value, label };
+  });
+}
+function normalizeGateQuestions(questions) {
+  return questions.map((q) => ({ ...q, options: normalizeGateOptions(q.options) }));
+}
+
+// src/commands.ts
+var GATE_BY_PANE = "pane";
 var COMMAND_NAMES = [
   "project-mrs:read",
   "discussions:read",
@@ -547,41 +621,6 @@ function gatePresentation(args) {
     return "wait";
   return args.questions.every((q) => q.options.length <= GATE_FORM_OPTION_CAP) ? "form" : "wait";
 }
-// src/gate-options.ts
-var RECOMMENDED_SUFFIX = " (Recommended)";
-var HAS_RECOMMENDED_SUFFIX = /\(\s*recommended\s*\)\s*$/i;
-function isWordLikeLabel(label) {
-  return /^[a-z][^A-Z0-9/:\\@]*$/.test(label);
-}
-function capitalize(label) {
-  return isWordLikeLabel(label) ? label[0].toUpperCase() + label.slice(1) : label;
-}
-function normalizeGateOptions(options) {
-  return options.map((o) => {
-    const recommended = o !== null && typeof o === "object" && o.recommended === true;
-    let value;
-    let label;
-    if (typeof o === "string") {
-      value = o;
-      label = o;
-    } else if (o !== null && typeof o === "object") {
-      const v = typeof o.value === "string" ? o.value : undefined;
-      const l = typeof o.label === "string" ? o.label : undefined;
-      value = v ?? l ?? String(o);
-      label = l ?? v ?? String(o);
-    } else {
-      value = String(o);
-      label = String(o);
-    }
-    label = capitalize(label);
-    if (recommended && label && !HAS_RECOMMENDED_SUFFIX.test(label))
-      label += RECOMMENDED_SUFFIX;
-    return { value, label };
-  });
-}
-function normalizeGateQuestions(questions) {
-  return questions.map((q) => ({ ...q, options: normalizeGateOptions(q.options) }));
-}
 // src/gate-answers.ts
 function unwrapGateAnswerValue(raw) {
   if (raw && typeof raw === "object" && !Array.isArray(raw) && "value" in raw) {
@@ -690,10 +729,10 @@ async function daemonHealth(opts = {}) {
 }
 // src/repos.ts
 import { existsSync, readFileSync } from "fs";
-import { homedir as homedir2 } from "os";
-import { dirname, join as join2 } from "path";
+import { homedir as homedir3 } from "os";
+import { dirname, join as join3 } from "path";
 function defaultReposJsonPath() {
-  return join2(homedir2(), ".mattstack", "rt", "repos.json");
+  return join3(homedir3(), ".mattstack", "rt", "repos.json");
 }
 function loadBunSqliteDatabase() {
   try {
@@ -745,7 +784,7 @@ function repoNameFromJson(repoPath, reposJsonPath) {
 }
 function repoNameForPath(repoPath, reposJsonPath) {
   const jsonPath = reposJsonPath ?? defaultReposJsonPath();
-  const dbPath = join2(dirname(jsonPath), "state.db");
+  const dbPath = join3(dirname(jsonPath), "state.db");
   const fromDb = repoNameFromStateDb(repoPath, dbPath);
   if (fromDb !== null)
     return fromDb;
@@ -825,33 +864,33 @@ function formatPaneRef(paneId, server) {
   return BG_PREFIX + paneId;
 }
 // src/settings/resolve.ts
-import { homedir as homedir4 } from "os";
-import { join as join5 } from "path";
+import { homedir as homedir5 } from "os";
+import { join as join6 } from "path";
 
 // src/settings/paths.ts
 import { readFileSync as readFileSync2 } from "fs";
-import { homedir as homedir3, hostname } from "os";
-import { join as join3 } from "path";
+import { homedir as homedir4, hostname } from "os";
+import { join as join4 } from "path";
 function home() {
-  return process.env.HOME ?? homedir3();
+  return process.env.HOME ?? homedir4();
 }
 function userSettingsPath() {
-  return join3(home(), ".mattstack", "user", "settings.user.jsonc");
+  return join4(home(), ".mattstack", "user", "settings.user.jsonc");
 }
 function teamSettingsPath(team) {
-  return join3(teamsDir(), team, "mattstack", "settings.team.jsonc");
+  return join4(teamsDir(), team, "mattstack", "settings.team.jsonc");
 }
 function teamLocalPath(team) {
-  return join3(home(), ".mattstack", "rt", "teams", `${team}.json`);
+  return join4(home(), ".mattstack", "rt", "teams", `${team}.json`);
 }
 function machineSettingsPath() {
-  return join3(home(), ".mattstack", "user", "local", machineKey(), "settings.local.jsonc");
+  return join4(home(), ".mattstack", "user", "local", machineKey(), "settings.local.jsonc");
 }
 function teamsDir() {
-  return join3(home(), ".mattstack", "teams");
+  return join4(home(), ".mattstack", "teams");
 }
 function machineKey() {
-  const override = join3(home(), ".mattstack", "machine-key");
+  const override = join4(home(), ".mattstack", "machine-key");
   try {
     const v = readFileSync2(override, "utf8").trim();
     if (isSafeMachineKeySegment(v))
@@ -1590,7 +1629,7 @@ function findPathGuardViolation(value, guardFields) {
 // src/settings/stores.ts
 import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync3, statSync } from "fs";
 import { parse } from "jsonc-parser";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 var EMPTY_STORE = (file, exists) => ({
   global: {},
   repos: {},
@@ -1637,13 +1676,13 @@ function listTeams() {
   const teams = [];
   for (const entry of entries) {
     try {
-      const isDir = entry.isDirectory() || entry.isSymbolicLink() && statSync(join4(dir, entry.name)).isDirectory();
+      const isDir = entry.isDirectory() || entry.isSymbolicLink() && statSync(join5(dir, entry.name)).isDirectory();
       if (!isDir)
         continue;
       if (existsSync2(teamSettingsPath(entry.name)))
         teams.push(entry.name);
     } catch (err) {
-      console.warn(`rt: skipping unreadable teams entry ${join4(dir, entry.name)}: ${err.message}`);
+      console.warn(`rt: skipping unreadable teams entry ${join5(dir, entry.name)}: ${err.message}`);
     }
   }
   return teams;
@@ -1692,7 +1731,7 @@ function teamPath(teamsDir2, name) {
   if (name.includes("/") || name.includes("\\") || name.includes("..")) {
     throw new Error(`rt: cannot expand \${team:${name}} — a team name must be a single directory segment (no "/", "\\" or "..")`);
   }
-  return join5(teamsDir2, name);
+  return join6(teamsDir2, name);
 }
 function required(value, name, needs) {
   if (value === undefined || value === "") {
@@ -1867,7 +1906,7 @@ function expandCtxFrom(opts) {
   return {
     repoRoot: opts.expandCtx?.repoRoot,
     worktree: opts.expandCtx?.worktree,
-    home: process.env.HOME ?? homedir4(),
+    home: process.env.HOME ?? homedir5(),
     teamsDir: teamsDir()
   };
 }
@@ -2408,6 +2447,7 @@ export {
   herdAttend,
   herdAsk,
   herdAnswer,
+  guardTestDaemonEnv,
   getSetting,
   getRun,
   getDef,

package/dist/test-isolation.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Strict by design: a JSON string is iterable and has .includes(), so an
+ * unvalidated parse would let a malformed value corrupt the merge here or
+ * silently disarm the transport guard. Anything but a string array throws.
+ */
+export declare function parseForbidSocks(raw: string): string[];
+export declare function guardTestDaemonEnv(env?: NodeJS.ProcessEnv): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattstack/rt-client",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "type": "module",
   "exports": {
     ".": {
@@ -15,6 +15,12 @@
       "import": "./dist/settings/identity-codec.js",
       "default": "./dist/settings/identity-codec.js"
     },
+    "./gate": {
+      "types": "./dist/gate.d.ts",
+      "bun": "./src/gate.ts",
+      "import": "./dist/gate.js",
+      "default": "./dist/gate.js"
+    },
     "./test/fake-daemon.ts": "./test/fake-daemon.ts"
   },
   "peerDependencies": {
@@ -45,7 +51,7 @@
     "bun": ">=1.0.0"
   },
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target node --format esm --packages external && bun build src/settings/identity-codec.ts --outfile dist/settings/identity-codec.js --target browser --format esm && tsc -p tsconfig.json",
+    "build": "bun build src/index.ts --outdir dist --target node --format esm --packages external && bun build src/settings/identity-codec.ts --outfile dist/settings/identity-codec.js --target browser --format esm && bun build src/gate.ts --outfile dist/gate.js --target browser --format esm && tsc -p tsconfig.json",
     "check-types": "tsc --noEmit -p tsconfig.json",
     "prepack": "bun run build"
   },

package/src/commands.ts

@@ -107,12 +107,10 @@ export interface GateOrigin {
   presentation?: "form" | "wait";
 }
 export interface GateQuestion { id: string; label: string; multi: boolean; options: GateOption[] }
-export function gateOptionValue(o: GateOption): string {
-  return typeof o === "string" ? o : o.value;
-}
-export function gateOptionLabel(o: GateOption): string {
-  return typeof o === "string" ? o : (o.label || o.value);
-}
+/** Implementations live in gate-options.ts (the browser-safe ./gate
+    subpath); re-exported here so existing commands.ts/index.ts consumers
+    are unaffected. */
+export { gateOptionValue, gateOptionLabel } from "./gate-options.ts";
 /** `session` is the answering surface's own session id, recorded so the
     push facility can tell a self-answer from a remote one and skip the
     doorbell it would otherwise send back to the writer. Optional: a caller

package/src/gate-answers.ts

@@ -1,5 +1,5 @@
 import type { GateQuestion, GateAnswer } from "./commands.ts";
-import { gateOptionValue } from "./commands.ts";
+import { gateOptionValue } from "./gate-options.ts";
 
 export type GateAnswerWire = GateAnswer["answers"][string];
 

package/src/gate-options.ts

@@ -8,6 +8,13 @@ export interface GateOptionObject {
   label: string;
 }
 
+export function gateOptionValue(o: GateOption): string {
+  return typeof o === "string" ? o : o.value;
+}
+export function gateOptionLabel(o: GateOption): string {
+  return typeof o === "string" ? o : (o.label || o.value);
+}
+
 /** Suffix gate-kit's stripRecommended (mattstack-apps repo,
     packages/gate-kit/src/options.ts) parses off a label to render its own
     "recommended" badge. This is the

package/src/gate.ts

@@ -0,0 +1,9 @@
+/**
+ * Browser-safe entry point (the "./gate" subpath export): the pure gate
+ * helpers only, so a browser bundle (mattstack-apps gate-kit) never drags in
+ * commands.ts's Node-only neighbors the way importing from "." would.
+ */
+export * from "./gate-answers.ts";
+export * from "./gate-options.ts";
+export * from "./gate-presentation.ts";
+export type { GateOption, GateQuestion, GateAnswer } from "./commands.ts";

package/src/index.ts

@@ -1,5 +1,6 @@
 export { rtCommand, DEFAULT_SOCK } from "./transport.ts";
 export type { RtResponse, RtClientOptions } from "./transport.ts";
+export { guardTestDaemonEnv } from "./test-isolation.ts";
 
 export {
   readProjectMRs,

package/src/test-isolation.ts

@@ -0,0 +1,36 @@
+/**
+ * Test-run isolation for suites that repoint HOME at a throwaway directory.
+ * An ambient RT_DAEMON_SOCK (herdr panes, agent shells) routes rtCommand at
+ * a live daemon over the top of the fake HOME, so a repointed HOME alone is
+ * not isolation. A test preload calls this BEFORE repointing HOME: it strips
+ * the live pointers from the env and arms RT_TEST_FORBID_SOCKS, the list of
+ * sockets rtCommand refuses to dispatch at (transport.ts).
+ */
+import { homedir } from "os";
+import { join } from "path";
+
+/**
+ * Strict by design: a JSON string is iterable and has .includes(), so an
+ * unvalidated parse would let a malformed value corrupt the merge here or
+ * silently disarm the transport guard. Anything but a string array throws.
+ */
+export function parseForbidSocks(raw: string): string[] {
+  const parsed: unknown = JSON.parse(raw);
+  if (!Array.isArray(parsed) || parsed.some((path) => typeof path !== "string")) {
+    throw new Error("rt-client: RT_TEST_FORBID_SOCKS must be a JSON string array of socket paths");
+  }
+  return parsed;
+}
+
+export function guardTestDaemonEnv(env: NodeJS.ProcessEnv = process.env): void {
+  const forbidden = new Set<string>();
+  if (env.RT_TEST_FORBID_SOCKS) {
+    for (const path of parseForbidSocks(env.RT_TEST_FORBID_SOCKS)) forbidden.add(path);
+  }
+  if (env.RT_DAEMON_SOCK) forbidden.add(env.RT_DAEMON_SOCK);
+  if (env.RT_APP_SOCKET) forbidden.add(env.RT_APP_SOCKET);
+  forbidden.add(join(env.HOME ?? homedir(), ".mattstack", "rt", "rt.sock"));
+  delete env.RT_DAEMON_SOCK;
+  delete env.RT_APP_SOCKET;
+  env.RT_TEST_FORBID_SOCKS = JSON.stringify([...forbidden]);
+}

package/src/transport.ts

@@ -9,6 +9,7 @@
  */
 import { homedir } from "os";
 import { join } from "path";
+import { parseForbidSocks } from "./test-isolation.ts";
 
 export interface RtResponse<T = unknown> {
   ok: boolean;
@@ -56,12 +57,31 @@ function defaultSock(): string {
  */
 export const DEFAULT_SOCK = defaultSock();
 
+/**
+ * The one exception to the never-throws contract below: when a test preload
+ * has armed RT_TEST_FORBID_SOCKS (see test-isolation.ts), dispatching at a
+ * listed socket throws instead of degrading. A degrade envelope could be
+ * tolerated by the calling test; escaping isolation must fail the run loudly.
+ * A malformed list throws too rather than silently disarming the guard.
+ */
+function assertSockNotForbidden(cmd: string, sockPath: string): void {
+  const raw = process.env.RT_TEST_FORBID_SOCKS;
+  if (!raw) return;
+  const forbidden = parseForbidSocks(raw);
+  if (forbidden.includes(sockPath)) {
+    throw new Error(
+      `rt-client: refusing "${cmd}" at forbidden socket ${sockPath}: RT_TEST_FORBID_SOCKS marks it as a live daemon socket, so this dispatch would have escaped test isolation`,
+    );
+  }
+}
+
 export async function rtCommand<T = unknown>(
   cmd: string,
   payload: Record<string, unknown>,
   opts: { sockPath?: string; timeoutMs?: number } = {},
 ): Promise<RtResponse<T>> {
   const sockPath = opts.sockPath ?? defaultSock();
+  assertSockNotForbidden(cmd, sockPath);
   try {
     const res = await fetch(`http://localhost/${cmd}`, {
       unix: sockPath,