@mattstack/rt-client 0.24.0 → 0.26.0

package/dist/commands.d.ts

@@ -171,14 +171,13 @@ export interface GateRow {
         at: number;
     } | null;
     released: boolean;
-    /** Set once the nudged pane has provably read the answer: either it
-        self-answered (stamped in the same transaction as the answer) or a
-        later `markConsumed` call recorded that it acted on a push. `null`
-        until then, so a sweep can tell an answered-but-unread row from a
-        settled one. Currently only stamped for herd-subject gates (the
-        self-answer path and `rt herd answer`'s nudged-session read); a
-        non-herd gate with a nudge stays `null` even after its pane
-        reconciles. */
+    /** Set once the nudged pane has provably read the answer: it self-answered
+        or lost the CAS to one (both stamped in the answer's own transaction),
+        or a later `markConsumed` call recorded that it acted on a push
+        (`rt herd answer` and `rt gate wait`, each on the nudged session's own
+        read). `null` until then, so a sweep can tell an answered-but-unread row
+        from a settled one. Every nudge-bearing subject has a stamping read;
+        a gate with no nudge never carries one, having no pane to read it. */
     consumedAt: number | null;
     owner: string | null;
     escalatedAt: number | null;
@@ -228,19 +227,20 @@ export interface HerdJobInfo {
     agentSession: string | null;
     agentId: string | null;
     handle: string;
-    status: "spawning" | "active" | "at-gate" | "at-milestone" | "done" | "closed" | "crashed";
+    status: "spawning" | "active" | "at-gate" | "at-milestone" | "done" | "closed" | "crashed" | "stuck-at-modal";
     disposable: boolean;
     lastGate: string | null;
     lastReport: number | null;
     createdAt: number;
     updatedAt: number;
 }
-/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: an `answered` gate whose delivery is `dead-pane` is the "answered, worker not woken" case the shepherd must act on. `lastGateConsumed` is `null` when there is nothing to consume (no last gate, not answered, or not nudged), and otherwise reports whether the nudged pane has read its answer. */
+/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: a TERMINAL gate (answered or closed) whose delivery is `dead-pane` is the "worker not woken" case the shepherd must act on. `lastGateConsumed` is `null` when there is nothing to consume (no last gate, not answered, or not nudged), and otherwise reports whether the nudged pane has read its answer. */
 export interface HerdStatusData {
     herd: HerdInfo;
     jobs: Array<HerdJobInfo & {
         openGate: string | null;
-        paneStatus: string | null;
+        paneStatus: string | null; /** The worker session behind this job's pane is gone while the job still reads in-flight: herdr lists the pane but no claude is on it. Null when herdr does not list the pane at all (it closed, or herdr is unreachable), which proves nothing either way. */
+        sessionDead: boolean | null;
         lastGateStatus: GateStatus | null;
         lastGateDelivery: "delivered" | "dead-pane" | "confirmed" | "stuck" | null;
         lastGateConsumed: boolean | null;
@@ -507,6 +507,7 @@ export interface AgentRecord {
     extraArgs?: string;
     exitCode?: number;
     resultPath?: string;
+    yolo?: boolean;
     createdAt: number;
     lastResumedAt?: number;
     finishedAt?: number;
@@ -1141,6 +1142,7 @@ export interface Commands {
             cwd: string;
             prompt?: string;
             surface?: AgentSurface;
+            provider?: string;
             model?: string;
             effort?: string;
             account?: string;
@@ -1154,6 +1156,7 @@ export interface Commands {
             handle?: string;
             bg?: boolean;
             subject?: string;
+            yolo?: boolean;
         };
         data: AgentRecord;
     };
@@ -1503,11 +1506,15 @@ export interface Commands {
                 worktree?: string;
             };
         };
+        /** `contextOmitted` appears only when the caller's context exceeded the
+            8192-byte cap and was dropped: the gate still opened, but with none of
+            the material the reader needs. */
         data: {
             id: string;
             presentation: "form" | "wait";
             subject: string;
             supersededId: string | null;
+            contextOmitted?: true;
         };
     };
     /**
@@ -1538,10 +1545,14 @@ export interface Commands {
     };
     /** `ok:false "not-found"` on an unknown id is terminal; the CLI loop must not re-enter on it.
      *  `timeout` carries no row (nothing settled); `answered`/`closed` always carry the settled row. */
+    /** `sessionId` is the caller's own session: an answered result returned to
+     *  the gate's nudged session is a recorded read and stamps `consumedAt`.
+     *  Omitting it reads without consuming. */
     "gate:wait": {
         payload: {
             id: string;
             waitMs?: number;
+            sessionId?: string;
         };
         data: {
             status: "timeout";
@@ -1689,7 +1700,8 @@ export interface Commands {
             wasOnDeck: boolean | null;
             agentId: string;
             sessionId: string;
-            handle: string;
+            handle: string; /** What the folder-trust check established: no modal was up, one was accepted and verified gone, one is still up (the job reads `stuck-at-modal`), or herdr could not be read. */
+            trust: "none" | "accepted" | "stuck" | "unchecked";
         };
     };
     "herd:gates": {

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,
@@ -205,7 +243,7 @@ function eventsList(payload, o = {}) {
 }
 function agentStart(a, o = {}) {
   const payload = { repo: a.repo, cwd: a.cwd };
-  for (const k of ["prompt", "surface", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs", "env", "herdrSocket", "handle", "bg", "subject"]) {
+  for (const k of ["prompt", "surface", "provider", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs", "env", "herdrSocket", "handle", "bg", "subject", "yolo"]) {
     if (a[k] !== undefined)
       payload[k] = a[k];
   }
@@ -306,6 +344,8 @@ function gateWait(a, o = {}) {
   const payload = { id: a.id };
   if (a.waitMs !== undefined)
     payload.waitMs = a.waitMs;
+  if (a.sessionId !== undefined)
+    payload.sessionId = a.sessionId;
   return rtCommand("gate:wait", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 250000 });
 }
 function gateList(a, o = {}) {
@@ -691,10 +731,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 {
@@ -746,7 +786,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;
@@ -826,33 +866,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))
@@ -1481,32 +1521,75 @@ var REGISTRY = [
     description: "Destination (topic/URL/token) the configured chat.push.provider sends to."
   },
   {
-    key: "agent.model",
+    key: "agent.provider",
     type: "string",
     scopes: ["user", "machine"],
+    default: "claude",
     merge: "replace",
-    description: "Default --model for rt agent launches; unset omits the flag."
+    description: 'Which provider rt agent start uses when --provider is not given: "claude" or "codex".'
   },
   {
-    key: "agent.effort",
+    key: "agent.claude.model",
     type: "string",
     scopes: ["user", "machine"],
     merge: "replace",
-    description: "Default --effort for rt agent launches; unset omits the flag."
+    description: "Default --model for claude rt agent launches; unset omits the flag."
   },
   {
-    key: "agent.account",
+    key: "agent.claude.effort",
     type: "string",
     scopes: ["user", "machine"],
     merge: "replace",
-    description: "cswap account email rt agent launches under; unset uses the default claude profile."
+    description: "Default --effort for claude rt agent launches; unset omits the flag."
   },
   {
-    key: "agent.extraArgs",
+    key: "agent.claude.account",
     type: "string",
     scopes: ["user", "machine"],
     merge: "replace",
-    description: "Opaque extra claude arguments appended to every rt agent launch (escape hatch)."
+    description: "cswap account email claude rt agent launches under; unset uses the default claude profile."
+  },
+  {
+    key: "agent.claude.extraArgs",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Opaque extra claude arguments appended to every claude rt agent launch (escape hatch)."
+  },
+  {
+    key: "agent.claude.yolo",
+    type: "boolean",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --yolo (--dangerously-skip-permissions) for claude rt agent launches; unset behaves as false."
+  },
+  {
+    key: "agent.codex.model",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default -m/--model for codex rt agent launches; unset omits the flag."
+  },
+  {
+    key: "agent.codex.effort",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default reasoning effort for codex rt agent launches, passed as -c model_reasoning_effort=<value>; unset omits the override."
+  },
+  {
+    key: "agent.codex.extraArgs",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Opaque extra codex arguments appended to every codex rt agent launch (escape hatch)."
+  },
+  {
+    key: "agent.codex.yolo",
+    type: "boolean",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --yolo (--dangerously-bypass-approvals-and-sandbox) for codex rt agent launches; unset behaves as false. codex has no per-agent account setting (see spec's Non-goals)."
   },
   {
     key: "rt.gates.escalationTtlMinutes",
@@ -1591,7 +1674,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: {},
@@ -1638,13 +1721,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;
@@ -1693,7 +1776,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 === "") {
@@ -1868,7 +1951,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()
   };
 }
@@ -2409,6 +2492,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.24.0",
+  "version": "0.26.0",
   "type": "module",
   "exports": {
     ".": {

package/src/client.ts

@@ -356,7 +356,7 @@ export function agentStart(
   a: Commands["agent:start"]["payload"], o: RtClientOptions = {},
 ): Promise<RtResponse<AgentRecord>> {
   const payload: Record<string, unknown> = { repo: a.repo, cwd: a.cwd };
-  for (const k of ["prompt", "surface", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs", "env", "herdrSocket", "handle", "bg", "subject"] as const) {
+  for (const k of ["prompt", "surface", "provider", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs", "env", "herdrSocket", "handle", "bg", "subject", "yolo"] as const) {
     if (a[k] !== undefined) payload[k] = a[k];
   }
   return rtCommand<AgentRecord>("agent:start", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
@@ -499,6 +499,7 @@ export function gateWait(
 ): Promise<RtResponse<Commands["gate:wait"]["data"]>> {
   const payload: Record<string, unknown> = { id: a.id };
   if (a.waitMs !== undefined) payload.waitMs = a.waitMs;
+  if (a.sessionId !== undefined) payload.sessionId = a.sessionId;
   return rtCommand<Commands["gate:wait"]["data"]>("gate:wait", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 250_000 });
 }
 

package/src/commands.ts

@@ -134,14 +134,13 @@ export interface GateRow {
   nudge: { session: string } | null;
   delivery: { outcome: "delivered" | "dead-pane" | "confirmed" | "stuck"; at: number } | null;
   released: boolean;
-  /** Set once the nudged pane has provably read the answer: either it
-      self-answered (stamped in the same transaction as the answer) or a
-      later `markConsumed` call recorded that it acted on a push. `null`
-      until then, so a sweep can tell an answered-but-unread row from a
-      settled one. Currently only stamped for herd-subject gates (the
-      self-answer path and `rt herd answer`'s nudged-session read); a
-      non-herd gate with a nudge stays `null` even after its pane
-      reconciles. */
+  /** Set once the nudged pane has provably read the answer: it self-answered
+      or lost the CAS to one (both stamped in the answer's own transaction),
+      or a later `markConsumed` call recorded that it acted on a push
+      (`rt herd answer` and `rt gate wait`, each on the nudged session's own
+      read). `null` until then, so a sweep can tell an answered-but-unread row
+      from a settled one. Every nudge-bearing subject has a stamping read;
+      a gate with no nudge never carries one, having no pane to read it. */
   consumedAt: number | null;
   owner: string | null;
   escalatedAt: number | null;
@@ -166,11 +165,11 @@ export interface GateSubscription {
 export interface HerdInfo { id: string; repo: string; room: string; workspace: string; shepherdSession: string; shepherdHandle: string; herdrSocket: string | null; hidden: boolean; status: "active" | "wrapped"; createdAt: number; wrappedAt: number | null }
 /** A herd row as `herd:list` reports it: the registry row plus how many jobs hang off it. */
 export interface HerdListRow extends HerdInfo { jobs: number }
-export interface HerdJobInfo { herd: string; name: string; worktree: string; branch: string | null; tree: string | null; pane: string | null; agentSession: string | null; agentId: string | null; handle: string; status: "spawning" | "active" | "at-gate" | "at-milestone" | "done" | "closed" | "crashed"; disposable: boolean; lastGate: string | null; lastReport: number | null; createdAt: number; updatedAt: number }
-/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: an `answered` gate whose delivery is `dead-pane` is the "answered, worker not woken" case the shepherd must act on. `lastGateConsumed` is `null` when there is nothing to consume (no last gate, not answered, or not nudged), and otherwise reports whether the nudged pane has read its answer. */
+export interface HerdJobInfo { herd: string; name: string; worktree: string; branch: string | null; tree: string | null; pane: string | null; agentSession: string | null; agentId: string | null; handle: string; status: "spawning" | "active" | "at-gate" | "at-milestone" | "done" | "closed" | "crashed" | "stuck-at-modal"; disposable: boolean; lastGate: string | null; lastReport: number | null; createdAt: number; updatedAt: number }
+/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: a TERMINAL gate (answered or closed) whose delivery is `dead-pane` is the "worker not woken" case the shepherd must act on. `lastGateConsumed` is `null` when there is nothing to consume (no last gate, not answered, or not nudged), and otherwise reports whether the nudged pane has read its answer. */
 export interface HerdStatusData {
   herd: HerdInfo;
-  jobs: Array<HerdJobInfo & { openGate: string | null; paneStatus: string | null; lastGateStatus: GateStatus | null; lastGateDelivery: "delivered" | "dead-pane" | "confirmed" | "stuck" | null; lastGateConsumed: boolean | null }>;
+  jobs: Array<HerdJobInfo & { openGate: string | null; paneStatus: string | null; /** The worker session behind this job's pane is gone while the job still reads in-flight: herdr lists the pane but no claude is on it. Null when herdr does not list the pane at all (it closed, or herdr is unreachable), which proves nothing either way. */ sessionDead: boolean | null; lastGateStatus: GateStatus | null; lastGateDelivery: "delivered" | "dead-pane" | "confirmed" | "stuck" | null; lastGateConsumed: boolean | null }>;
   unread: number;
   lifecycleConnected: boolean;
   hiddenUp: boolean | null;
@@ -360,7 +359,7 @@ export interface AgentRecord {
       PreToolUse hook gets injected at all. */
   subject?: string;
   paneId?: string; tabId?: string; workspaceId?: string;
-  extraArgs?: string; exitCode?: number; resultPath?: string;
+  extraArgs?: string; exitCode?: number; resultPath?: string; yolo?: boolean;
   createdAt: number; lastResumedAt?: number; finishedAt?: number;
 }
 
@@ -617,7 +616,7 @@ export interface Commands {
   "chat:dm-open": { payload: { from: string; to: string; sessionId?: string }; data: { room: string; created: boolean } };
 
   // ─── Agent handoff (rt agent) ────────────────────────────────────────────
-  "agent:start": { payload: { repo: string; cwd: string; prompt?: string; surface?: AgentSurface; model?: string; effort?: string; account?: string; label?: string; caller?: string; workspace?: string; tab?: string; extraArgs?: string; env?: Record<string, string>; herdrSocket?: string; handle?: string; bg?: boolean; subject?: string }; data: AgentRecord };
+  "agent:start": { payload: { repo: string; cwd: string; prompt?: string; surface?: AgentSurface; provider?: string; model?: string; effort?: string; account?: string; label?: string; caller?: string; workspace?: string; tab?: string; extraArgs?: string; env?: Record<string, string>; herdrSocket?: string; handle?: string; bg?: boolean; subject?: string; yolo?: boolean }; data: AgentRecord };
   "agent:resume": { payload: { id: string; prompt?: string; surface?: AgentSurface; workspace?: string; tab?: string }; data: AgentRecord };
   "agent:get": { payload: { id: string }; data: AgentRecord };
   "agent:list": { payload: { repo?: string }; data: { agents: AgentRecord[] } };
@@ -712,7 +711,10 @@ export interface Commands {
       agent?: string;
       origin?: { surface?: string; tabId?: string; worktree?: string };
     };
-    data: { id: string; presentation: "form" | "wait"; subject: string; supersededId: string | null };
+    /** `contextOmitted` appears only when the caller's context exceeded the
+        8192-byte cap and was dropped: the gate still opened, but with none of
+        the material the reader needs. */
+    data: { id: string; presentation: "form" | "wait"; subject: string; supersededId: string | null; contextOmitted?: true };
   };
   /**
    * A CAS loss is a DEFINED OUTCOME, not an error: `ok:true` with
@@ -730,7 +732,10 @@ export interface Commands {
   "gate:answer": { payload: { id: string; answers: GateAnswer["answers"]; by: string; session?: string; override?: boolean }; data: { row: GateRow; conflict?: true } };
   /** `ok:false "not-found"` on an unknown id is terminal; the CLI loop must not re-enter on it.
    *  `timeout` carries no row (nothing settled); `answered`/`closed` always carry the settled row. */
-  "gate:wait": { payload: { id: string; waitMs?: number }; data: { status: "timeout" } | { status: "answered" | "closed"; row: GateRow } };
+  /** `sessionId` is the caller's own session: an answered result returned to
+   *  the gate's nudged session is a recorded read and stamps `consumedAt`.
+   *  Omitting it reads without consuming. */
+  "gate:wait": { payload: { id: string; waitMs?: number; sessionId?: string }; data: { status: "timeout" } | { status: "answered" | "closed"; row: GateRow } };
   /** Paged like events:list: an omitted `limit` clamps daemon-side rather than
    *  forcing a full-table read; `cursor` is the paging rowid to resume from. */
   "gate:list": { payload: { open?: boolean; subjectPrefix?: string; kind?: string; limit?: number; cursor?: number }; data: { gates: GateRow[]; cursor: number } };
@@ -750,7 +755,7 @@ export interface Commands {
   "herd:list":   { payload: { all?: boolean }; data: { herds: HerdListRow[] } };
   "herd:close":  { payload: { herd: string; job: string }; data: { job: string; status: "closed"; /** Advisory: a resumable run can still write into this job's worktree after close, so this warns rather than blocking. */ warning?: string } };
   /** `brief` is the brief TEXT, not a path: the CLI reads the file. It is stored at `<jobsRoot>/<herd>/<job>/job.md`, so a respawn with `dir` and no `brief` reads it back. */
-  "herd:spawn":  { payload: { herd: string; job: string; brief?: string; dir?: string; model?: string; effort?: string; account?: string; disposable?: boolean }; data: { herd: string; job: string; pane: string; worktree: string; branch: string | null; tree: string | null; /** null = no provisioning ran (--dir); false = cold create, worth announcing. */ wasOnDeck: boolean | null; agentId: string; sessionId: string; handle: string } };
+  "herd:spawn":  { payload: { herd: string; job: string; brief?: string; dir?: string; model?: string; effort?: string; account?: string; disposable?: boolean }; data: { herd: string; job: string; pane: string; worktree: string; branch: string | null; tree: string | null; /** null = no provisioning ran (--dir); false = cold create, worth announcing. */ wasOnDeck: boolean | null; agentId: string; sessionId: string; handle: string; /** What the folder-trust check established: no modal was up, one was accepted and verified gone, one is still up (the job reads `stuck-at-modal`), or herdr could not be read. */ trust: "none" | "accepted" | "stuck" | "unchecked" } };
   "herd:gates":  { payload: { herd: string }; data: { gates: GateRow[] } };
   "herd:ask":       { payload: { herd: string; job: string; session: string; pane?: string; questions: GateQuestion[]; context?: string }; data: { gate: string } };
   "herd:milestone": { payload: { herd: string; job: string; session: string; pane?: string; artifact: string; summary?: string }; data: { gate: string; message: number } };

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/settings/registry-defs.ts

@@ -666,35 +666,80 @@ export const REGISTRY: readonly SettingDef[] = [
   },
 
   // --- agent (rt agent handoff) --------------------------------------------
-  // No defaults by design: an unset key means the flag is omitted from the
-  // claude invocation entirely (spec "Settings").
+  // No defaults on any per-provider row, by design: an unset key means the
+  // flag is omitted from the launch entirely (spec "Settings"). agent.provider
+  // is the one exception -- it needs a concrete fallback to preserve
+  // claude-only behavior with zero code changes for callers who never set it.
   {
-    key: "agent.model",
+    key: "agent.provider",
     type: "string",
     scopes: ["user", "machine"],
+    default: "claude",
     merge: "replace",
-    description: "Default --model for rt agent launches; unset omits the flag.",
+    description: "Which provider rt agent start uses when --provider is not given: \"claude\" or \"codex\".",
   },
   {
-    key: "agent.effort",
+    key: "agent.claude.model",
     type: "string",
     scopes: ["user", "machine"],
     merge: "replace",
-    description: "Default --effort for rt agent launches; unset omits the flag.",
+    description: "Default --model for claude rt agent launches; unset omits the flag.",
   },
   {
-    key: "agent.account",
+    key: "agent.claude.effort",
     type: "string",
     scopes: ["user", "machine"],
     merge: "replace",
-    description: "cswap account email rt agent launches under; unset uses the default claude profile.",
+    description: "Default --effort for claude rt agent launches; unset omits the flag.",
   },
   {
-    key: "agent.extraArgs",
+    key: "agent.claude.account",
     type: "string",
     scopes: ["user", "machine"],
     merge: "replace",
-    description: "Opaque extra claude arguments appended to every rt agent launch (escape hatch).",
+    description: "cswap account email claude rt agent launches under; unset uses the default claude profile.",
+  },
+  {
+    key: "agent.claude.extraArgs",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Opaque extra claude arguments appended to every claude rt agent launch (escape hatch).",
+  },
+  {
+    key: "agent.claude.yolo",
+    type: "boolean",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --yolo (--dangerously-skip-permissions) for claude rt agent launches; unset behaves as false.",
+  },
+  {
+    key: "agent.codex.model",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default -m/--model for codex rt agent launches; unset omits the flag.",
+  },
+  {
+    key: "agent.codex.effort",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default reasoning effort for codex rt agent launches, passed as -c model_reasoning_effort=<value>; unset omits the override.",
+  },
+  {
+    key: "agent.codex.extraArgs",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Opaque extra codex arguments appended to every codex rt agent launch (escape hatch).",
+  },
+  {
+    key: "agent.codex.yolo",
+    type: "boolean",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --yolo (--dangerously-bypass-approvals-and-sandbox) for codex rt agent launches; unset behaves as false. codex has no per-agent account setting (see spec's Non-goals).",
   },
 
   // --- gates (escalation) ----------------------------------------------------

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,