@mattstack/rt-client 0.10.1 → 0.11.1

package/src/commands.ts

@@ -4,7 +4,7 @@
  * its functions against this map so a new command only needs an entry here
  * plus one function, never a change to the transport itself.
  */
-import type { PullRequest, MRDetail } from "@mattstack/glance";
+import type { PullRequest, MRDetail, Pipeline } from "@mattstack/glance";
 
 export type Discussion = MRDetail["discussions"][number];
 
@@ -25,6 +25,10 @@ export interface ProjectMRsScope {
   sections?: string[];
   /** Demanded sections not yet swept for this client. */
   uncoveredSections?: string[];
+  /** Section headers in the default-branch CODEOWNERS at the last deep or
+      backfill. `[]` when the project has none. Absent from a pre-knownSections
+      daemon or before the first sweep that demanded a section. */
+  knownSections?: string[];
 }
 
 export interface ProjectMRsData {
@@ -108,6 +112,12 @@ export interface ChatMessage {
   postedAt: number;
 }
 
+/** `claimed` is the only outcome that woke anyone; `previousHolder` marks a takeover of an expired claim. */
+export type ChatClaimOutcome =
+  | { outcome: "claimed"; author: string; room: string; previousHolder?: string }
+  | { outcome: "held"; author: string; room: string }
+  | { outcome: "lost"; holder: string; claimedAt: number; expiresAt: number };
+
 export interface RoomSummary {
   room: string;
   memberCount: number;
@@ -226,6 +236,139 @@ export interface AgentRecord {
   createdAt: number; lastResumedAt?: number; finishedAt?: number;
 }
 
+// ─── The daemon's remaining out-of-process commands (R013/R016) ──
+// rt CLI <-> daemon, tray <-> daemon, and VS Code extension <-> daemon are
+// all separate OS processes, so any command reachable from one counts as
+// "external" here even when the only known caller today is rt's own CLI.
+
+/** Duplicated shape on purpose (see EventsBusEvent above): mirrors lib/daemon/health.ts's HealthSnapshot. */
+export type HealthLevel = "ok" | "degraded" | "unhealthy";
+export interface HealthMetrics { rss: number; heapUsed: number; external: number; uptimeMs: number; wsClients: number; watchers: number }
+export interface HealthEventLoop { maxLagMs: number; lastStallAt: number | null; lastStallCmd: string | null; stalls: number }
+export interface DaemonIdentity { flavor: "dev" | "prod"; version: string; sourceRev: string | null; startedAt: number }
+
+export interface PingData extends DaemonIdentity {
+  uptime: number;
+  pid: number;
+  health: HealthLevel;
+  eventLoop: HealthEventLoop;
+  heartbeatSeq: number;
+  supervision: { bootAttempts: number; lastReadyAt: number | null; recentFailures: unknown[]; lastExit: unknown };
+}
+
+export interface StatusData {
+  pid: number; uptime: number; watchedRepos: number; cacheEntries: number;
+  portsCached: number; portCacheAge: number | null;
+  freshness: unknown; identity: DaemonIdentity;
+  health: { level: HealthLevel; reasons: string[] }; metrics: HealthMetrics; eventLoop: HealthEventLoop;
+  worktreePool: { dormant: true; repos: string[]; message: string } | { dormant: false };
+}
+
+/** Duplicated shape on purpose: mirrors lib/worktree/ready-held.ts's ReadyHeldRepo. */
+export interface ReadyHeldRepo {
+  /** Serialized repo identity. A key, never displayed. */
+  repo: string;
+  /** Decoded display name. Never sent back as a key. */
+  label: string;
+  hash: string;
+  approveCommand: string;
+}
+
+export interface TrayStatusData {
+  pid: number; uptime: number; memoryUsage: number; watchedRepos: number; cacheEntries: number;
+  portsCached: number; portCacheAge: number | null; lastRefresh: number | null;
+  portsByRepo: Record<string, number>; pendingNotifications: number;
+  health: { level: HealthLevel; reasons: string[] }; metrics: HealthMetrics; eventLoop: HealthEventLoop;
+  /** Optional because a daemon older than RT-98 does not send it. */
+  worktreeReadyHeld?: ReadyHeldRepo[];
+}
+
+/** Duplicated shape on purpose: mirrors lib/port-scanner.ts's PortEntry. */
+export interface PortEntry {
+  port: number; pid: number; command: string; cwd: string;
+  repo: string | null; worktree: string | null; branch: string | null;
+  relativeDir: string; uptime: string;
+}
+
+export interface PortsData {
+  ports: PortEntry[];
+  grouped: Record<string, Record<string, PortEntry[]>>;
+  updatedAt: number;
+  age: number | null;
+}
+
+/** Duplicated shape on purpose: mirrors lib/state/notifier-store.ts's NotificationEvent. */
+export interface RtNotificationEvent {
+  id: string; title: string; message: string; url?: string;
+  category: string; timestamp: number; pids?: number[];
+}
+
+export interface ReposData {
+  repos: Record<string, { path: string; worktrees: Array<{ path: string; branch: string }> }>;
+  watched: string[];
+}
+
+export interface TccCheckData {
+  blocked: Array<{ name: string; path: string; error: string }>;
+  accessible: string[];
+  totalRepos: number;
+  daemonPid: number;
+}
+
+export interface WorktreeTreeRow {
+  name: string; kind: string; state: string; path: string; branch: string | null;
+  repoName: string; mr: { iid: number; state: string; title: string } | null;
+  duplicateBranch?: true;
+  [extra: string]: unknown;
+}
+export interface WorktreeListData {
+  trees: WorktreeTreeRow[];
+  dormant?: true; dormantRepos?: string[]; message?: string;
+  readyHeld?: true; readyHeldRepos?: string[];
+}
+export interface WorktreeProvisionData {
+  tree: string; path: string; branch: string; wasOnDeck: boolean;
+  readyAt: string | null; branchState: "new" | "tracking-remote" | "existing-clean" | "diverged" | "behind";
+  readyFailed?: true; failedStep?: string;
+}
+export interface WorktreeCreateData { tree: string; path: string }
+export interface WorktreeDisposeData {
+  disposed: string[];
+  refused: Array<{ tree: string; reason: string }>;
+  recoverable: Array<{ tree: string; path: string; until: string }>;
+}
+export interface WorktreeRestoreData {
+  restored: true; path: string; tree: string; readyFailed?: true; failedStep?: string;
+}
+export interface WorktreeFreshenData { ran: string[] }
+export interface WorktreeAdoptData {
+  main: string; claimed: string[]; unmanaged: string[]; disposed: string[];
+  refused: Array<{ tree: string; reason: string }>;
+}
+
+/** Duplicated shape on purpose: mirrors lib/endpoint/store.ts's EndpointClaim. */
+export interface EndpointClaim { worktree: string; role: string; port: number; ts: number }
+export interface EndpointRoleRef { port: number; url: string; running: boolean }
+export interface EndpointClaimData { role: string; port: number; url: string; refs: Record<string, EndpointRoleRef> }
+export interface EndpointLookupData { claimed: boolean; port: number | null; url: string | null; running: boolean }
+export interface EndpointReleaseData { released: number }
+export interface EndpointStatusData { repos: Record<string, Array<EndpointClaim & { running: boolean }>> }
+
+/**
+ * Duplicated shape on purpose: mirrors @mattstack/glance's `JobDetail`
+ * (types.ts), which the package does not re-export from its index.
+ */
+export type MrJobDetail = { type: "trace"; content: string } | { type: "bridge"; downstreamPipeline: Pipeline };
+
+export interface DiscussionsWriteData { discussions: Discussion[]; fetchedAt: number }
+export interface DiscussionsDiffsData { diffs: Array<{ newPath: string; diff: string }>; truncated: boolean }
+
+export type MRActionName =
+  | "merge" | "rebase" | "approve" | "unapprove"
+  | "setAutoMerge" | "cancelAutoMerge"
+  | "retryJob" | "retryPipeline"
+  | "toggleDraft" | "requestReReview";
+
 export interface Commands {
   "project-mrs:read": { payload: { repoName: string; maxAgeMs?: number; demand?: DemandDecl }; data: ProjectMRsData };
   "discussions:read": { payload: { repoName: string; iid: number }; data: DiscussionsData };
@@ -284,7 +427,11 @@ export interface Commands {
   "runs:abandon": { payload: { runId: string; repo?: string; reason?: string }; data: { ok: boolean } };
   "chat:join": { payload: { room: string; handle: string; wakeOn?: WakeMode; cwd?: string; pane?: string }; data: { handle: string; memberCount: number; unread: number } };
   "chat:leave": { payload: { room: string; handle: string }; data: Record<string, never> };
-  "chat:post": { payload: { room: string; handle: string; body: string; mentions?: string[] }; data: { id: number; recipients: string[] } };
+  /** `others` counts the room's members besides the author, so a caller can tell "woke nobody of 7" from "nobody else is here". */
+  "chat:post": { payload: { room: string; handle: string; body: string; mentions?: string[]; quiet?: boolean }; data: { id: number; recipients: string[]; others: number } };
+  "chat:ack": { payload: { id: number; handle: string }; data: { author: string; room: string; already: boolean } };
+  "chat:claim": { payload: { id: number; handle: string }; data: ChatClaimOutcome };
+  "chat:release": { payload: { id: number; handle: string }; data: { holder: string } };
   "chat:read": { payload: { handle: string; room?: string; limit?: number; sinceMs?: number }; data: { rooms: { room: string; messages: ChatMessage[] }[] } };
   "chat:rooms": { payload: { handle: string; includeArchived?: boolean }; data: { rooms: RoomSummary[] } };
   "chat:who": { payload: { room: string }; data: { members: ChatMember[] } };
@@ -355,6 +502,60 @@ export interface Commands {
   };
   "pane:send": { payload: { paneId: string; text: string; callerPane?: string }; data: PaneSendResult };
   "pane:focus": { payload: { paneId: string }; data: PaneFocusResult };
+
+  // ─── R013/R016 ────────────────────────────────────────────────
+  "cache:read": { payload: { branches?: string[]; maxAgeMs?: number; repoIdentity?: string }; data: Record<string, BranchEnrichment> };
+  /** `source` ("cache"|"fresh"|"empty") rides alongside `data` on the wire, not nested under it. */
+  "branch:enrich": { payload: { branch: string; repoPath?: string; remoteUrl?: string; repoIdentity?: string }; data: BranchEnrichment | null };
+  /** Fire-and-forget kickoff; wire reply is `{ok, message}`, not `{ok,data}`. */
+  "cache:refresh": { payload: Record<string, never>; data: { message: string } };
+  "daemon:log-level": { payload: { level?: "trace" | "debug" | "info" | "warn" | "error" }; data: { level: string } };
+  "ping": { payload: Record<string, never>; data: PingData };
+  "status": { payload: Record<string, never>; data: StatusData };
+  "tray:status": { payload: Record<string, never>; data: TrayStatusData };
+  "tcc:check": { payload: Record<string, never>; data: TccCheckData };
+  "repos": { payload: Record<string, never>; data: ReposData };
+  "ports": { payload: { repo?: string; refresh?: boolean }; data: PortsData };
+  "notifications": { payload: Record<string, never>; data: RtNotificationEvent[] };
+
+  "discussions:refresh": { payload: { repoName: string; iid: number }; data: DiscussionsWriteData };
+  "discussions:resolve": { payload: { repoName: string; iid: number; discussionId: string; resolved?: boolean }; data: DiscussionsWriteData };
+  "discussions:reply": { payload: { repoName: string; iid: number; discussionId: string; body: string }; data: DiscussionsWriteData };
+  "discussions:diffs": { payload: { repoName: string; iid: number }; data: DiscussionsDiffsData };
+
+  /** Wire reply is `{ok:true}` on success (no `data`); a failure is `{ok:false,error}`. */
+  "mr:action": { payload: { repoName: string; iid: number; action: MRActionName; args?: unknown[] }; data: Record<string, never> };
+  "mr:fetch-job-detail": { payload: { repoName: string; iid: number; jobId: number; pipelineId?: number }; data: MrJobDetail };
+  "mr:fetch-job-trace": { payload: { repoName: string; iid: number; jobId: number }; data: string };
+
+  "endpoint:claim": { payload: { repo: string; worktree: string; role: string; pid?: number }; data: EndpointClaimData };
+  "endpoint:lookup": { payload: { repo: string; worktree: string; role: string }; data: EndpointLookupData };
+  "endpoint:release": { payload: { repo: string; worktree: string; role?: string }; data: EndpointReleaseData };
+  "endpoint:status": { payload: { repo?: string }; data: EndpointStatusData };
+
+  "repos:locate": { payload: { newPath: string; repo?: string; dryRun?: boolean }; data: unknown };
+  "freshness:reconcile": { payload: Record<string, never>; data: unknown };
+
+  /** Wire reply on success is always `{ok:true, repaired}` (no `data`
+   *  wrapper) — `data` here documents the extra field the same way PingData
+   *  does for `ping`, not the literal wire nesting (R3). */
+  "hooks:repair": { payload: { repo: string }; data: { repaired: boolean } };
+  "hooks:watch": { payload: { repo: string }; data: Record<string, never> };
+
+  "sdm:catalog": { payload: { refresh?: boolean }; data: unknown };
+  "sdm:snapshot": { payload: { force?: boolean }; data: unknown };
+  "sdm:recents": { payload: Record<string, never>; data: unknown };
+  "sdm:reconnect": { payload: { key: string }; data: unknown };
+
+  "system-processes": { payload: Record<string, never>; data: unknown };
+
+  "worktree:provision": { payload: { repoName: string; branch?: string; ticket?: string; ticketTitle?: string; disposal?: "job" | "merge"; owner?: string }; data: WorktreeProvisionData };
+  "worktree:create": { payload: { repoName: string; onDeck?: boolean }; data: WorktreeCreateData };
+  "worktree:dispose": { payload: { repoName?: string; owner?: string; tree?: string; force?: boolean; callerPid?: number }; data: WorktreeDisposeData };
+  "worktree:list": { payload: { repoName?: string }; data: WorktreeListData };
+  "worktree:restore": { payload: { repoName: string; tree: string }; data: WorktreeRestoreData };
+  "worktree:freshen": { payload: { repoName?: string; tree?: string }; data: WorktreeFreshenData };
+  "worktree:adopt": { payload: { repoName: string; claim?: boolean }; data: WorktreeAdoptData };
 }
 
 export type CommandName = keyof Commands;
@@ -372,6 +573,9 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "runs:list",
   "runs:get",
   "runs:abandon",
+  "chat:ack",
+  "chat:claim",
+  "chat:release",
   "chat:join",
   "chat:leave",
   "chat:post",
@@ -400,4 +604,44 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "pane:spawn",
   "pane:send",
   "pane:focus",
+
+  // ─── R013/R016 ────────────────────────────────────────────────
+  "cache:read",
+  "branch:enrich",
+  "cache:refresh",
+  "daemon:log-level",
+  "ping",
+  "status",
+  "tray:status",
+  "tcc:check",
+  "repos",
+  "ports",
+  "notifications",
+  "discussions:refresh",
+  "discussions:resolve",
+  "discussions:reply",
+  "discussions:diffs",
+  "mr:action",
+  "mr:fetch-job-detail",
+  "mr:fetch-job-trace",
+  "endpoint:claim",
+  "endpoint:lookup",
+  "endpoint:release",
+  "endpoint:status",
+  "repos:locate",
+  "freshness:reconcile",
+  "hooks:repair",
+  "hooks:watch",
+  "sdm:catalog",
+  "sdm:snapshot",
+  "sdm:recents",
+  "sdm:reconnect",
+  "system-processes",
+  "worktree:provision",
+  "worktree:create",
+  "worktree:dispose",
+  "worktree:list",
+  "worktree:restore",
+  "worktree:freshen",
+  "worktree:adopt",
 ];

package/src/index.ts

@@ -12,6 +12,9 @@ export {
   abandonRun,
   chatJoin,
   chatLeave,
+  chatAck,
+  chatClaim,
+  chatRelease,
   chatPost,
   chatRead,
   chatRooms,
@@ -64,6 +67,7 @@ export type {
   WakeMode,
   ChatMember,
   ChatMessage,
+  ChatClaimOutcome,
   RoomSummary,
   BuddyStatus,
   PresenceRow,
@@ -86,9 +90,12 @@ export { daemonHealth } from "./health.ts";
 
 export { repoNameForPath } from "./repos.ts";
 
+export { decidePlacement, openSmartPane } from "./smart-pane.ts";
+export type { Placement, PlacementOpts, HerdrCall } from "./smart-pane.ts";
+
 // ─── Settings (RT-50) ────────────────────────────────────────────────────────
 
-export { getSetting, listSettings, explainSetting, expandVariables, SCOPE_ORDER } from "./settings/resolve.ts";
+export { getSetting, listSettings, explainSetting, expandVariables, SCOPE_ORDER, setSettingsWarnSink } from "./settings/resolve.ts";
 export type {
   Scope,
   Provenance,

package/src/settings/exec.ts

@@ -12,6 +12,8 @@ export interface RunResult {
   stdout: string;
   stderr: string;
   exitCode: number;
+  /** Set true only when the deadline fired before the child settled. */
+  timedOut?: boolean;
 }
 
 /**
@@ -47,21 +49,53 @@ export async function runCapture(
     return { stdout: "", stderr: "", exitCode: -1 };
   }
 
-  const timer = setTimeout(() => {
-    try { proc.kill(); } catch { /* already exited */ }
-  }, opts.timeoutMs ?? 10_000);
+  const timeoutMs = opts.timeoutMs ?? 10_000;
+  // SIGTERM at the deadline, SIGKILL a short grace later. A child that ignores
+  // SIGTERM (or a D-state descendant) cannot be reaped in-band, so the read is
+  // raced against the deadline below rather than awaited unconditionally: that
+  // is what lets runCapture settle while a grandchild still holds the pipe.
+  let killTimer: ReturnType<typeof setTimeout> | undefined;
+  const term = setTimeout(() => {
+    try { proc.kill("SIGTERM"); } catch { /* already exited */ }
+    killTimer = setTimeout(() => {
+      try { proc.kill("SIGKILL"); } catch { /* already exited */ }
+    }, 2000);
+    // unref: a short-lived CLI process must not be held open by a timed-out
+    // call waiting on this timer; the daemon stays alive regardless, so its
+    // SIGKILL still fires.
+    killTimer.unref?.();
+  }, timeoutMs);
+
+  const captured: Promise<RunResult> = (async () => {
+    try {
+      const stdoutPromise = new Response(proc.stdout as ReadableStream).text();
+      const stderrPromise = captureStderr
+        ? new Response(proc.stderr as ReadableStream).text()
+        : Promise.resolve("");
+      const [stdout, stderr, exitCode] = await Promise.all([
+        stdoutPromise,
+        stderrPromise,
+        proc.exited,
+      ]);
+      return { stdout, stderr, exitCode };
+    } catch {
+      return { stdout: "", stderr: "", exitCode: -1 };
+    }
+  })();
+
+  let deadlineTimer: ReturnType<typeof setTimeout>;
+  const deadline: Promise<RunResult> = new Promise((resolve) => {
+    deadlineTimer = setTimeout(() => resolve({ stdout: "", stderr: "", exitCode: -1, timedOut: true }), timeoutMs);
+  });
 
   try {
-    const stdoutPromise = new Response(proc.stdout as ReadableStream).text();
-    const stderrPromise = captureStderr
-      ? new Response(proc.stderr as ReadableStream).text()
-      : Promise.resolve("");
-    const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
-    const exitCode = await proc.exited;
-    return { stdout, stderr, exitCode };
-  } catch {
-    return { stdout: "", stderr: "", exitCode: -1 };
+    return await Promise.race([captured, deadline]);
   } finally {
-    clearTimeout(timer);
+    clearTimeout(term);
+    clearTimeout(deadlineTimer!);
+    // killTimer intentionally NOT cleared here: on the timeout path it must
+    // survive this finally to fire SIGKILL against a child that ignored
+    // SIGTERM. proc.kill is already try/catch guarded, so it is a harmless
+    // no-op if the child exited before the 2s grace elapses.
   }
 }

package/src/settings/registry-defs.ts

@@ -44,6 +44,15 @@ export const REGISTRY: readonly SettingDef[] = [
     migrated: true,
     description: "Per-repo worktree pool config (onDeck size, ready steps, name pool); root/branchFormat/ready computed-or-empty in the reader.",
   },
+  {
+    key: "rt.worktreeReadyApproval",
+    type: "string",
+    scopes: ALL_SCOPES,
+    merge: "replace",
+    repoScoped: true,
+    migrated: true,
+    description: "Per-repo user approval of a team-authored `ready` shell ladder, as its content hash (RT-89). The reader trusts only user/machine scopes so a team store can never approve its own shell; a hash mismatch after a team edit re-holds the ladder until `rt worktree ready-approve` records the new one.",
+  },
   {
     key: "rt.repoIdentityOverrides",
     type: "object",
@@ -196,6 +205,24 @@ export const REGISTRY: readonly SettingDef[] = [
     migrated: true,
     description: "Age floor in days for the log janitor pruning every surface's rotated log files under ~/.mattstack/rt/logs (default 14). A fresh key, not an ownership-latch port, so a default is fine here.",
   },
+  {
+    key: "rt.logLevel",
+    type: "string",
+    scopes: ["machine", "user"],
+    default: "info",
+    merge: "replace",
+    migrated: true,
+    description: "Daemon log level (trace|debug|info|warn|error). RT_LOG_LEVEL env wins, then this setting, then info (lib/daemon-logger.ts resolveDaemonLogLevel). A fresh key, not an ownership-latch port, so a default is fine here.",
+  },
+  {
+    key: "rt.apiPort",
+    type: "number",
+    scopes: ["machine", "user"],
+    default: 9401,
+    merge: "replace",
+    migrated: true,
+    description: "TCP port for the daemon's local HTTP/WS API. Escape hatch when 9401 is held: RT_API_PORT env wins, then this setting, then 9401 (lib/daemon-config.ts resolveApiPort(), read at bind time by lib/daemon/api-server.ts).",
+  },
   {
     key: "rt.hooks",
     type: "object",
@@ -205,6 +232,22 @@ export const REGISTRY: readonly SettingDef[] = [
     migrated: true,
     description: "Per-repo git hook enable/disable state ({enabled, hooks: {<hookName>: boolean}}); ownership-latch port of repos/<repo>/hooks.json, store wins per field once it owns the key — including per-hook-name entries inside the nested hooks map, each defaulting to enabled when absent. The installed git-hook shim still greps repos/<repo>/hooks.json with zero process spawns (a hook fires on every git operation); that file is now a DERIVED CACHE this key writes through, kept current by commands/hooks.ts's regenerateHooksCache at every write seam.",
   },
+  {
+    key: "rt.daemonPath",
+    type: "string",
+    scopes: ["machine"],
+    merge: "replace",
+    description:
+      "Absolute colon-separated PATH the daemon uses for every child it spawns, instead of probing your login shell. Set this when the daemon can't find node/git/bun/pnpm (e.g. a fish shell, a blocking .zshrc, or PATH exports that live only in .zshrc). Machine-scoped: it never travels to another machine.",
+  },
+  {
+    key: "rt.trustedBrowserOrigins",
+    type: "array",
+    scopes: ["user", "machine"],
+    default: [],
+    merge: "replace",
+    description: "Browser Origins (scheme://host:port, exact string match) trusted to read the :9401 daemon API and subscribe to /ws without presenting the local api-token -- e.g. a locally-hosted console or chat-viewer dev server. Empty by default: every current mattstack consumer (the CLI, the Swift tray, rt-client from Bun/Node processes, the VS Code extension) is a non-browser client (sends no Origin header at all) and is unaffected either way.",
+  },
 
   // --- mattstack (installer-lane) -----------------------------------------
   {

package/src/settings/resolve.ts

@@ -487,8 +487,29 @@ function expandCtxFrom(opts: ResolveOpts): ExpandCtx {
   };
 }
 
+let warnSink: ((msg: string) => void) | null = null;
+const warnedOnce = new Set<string>();
+
+/** The daemon binds a deduped log.warn here so a hot-path getSetting on a
+ *  disallowed-scope key warns once, not every tick. Default: console.warn
+ *  (CLI/test behavior unchanged). null restores the default. */
+export function setSettingsWarnSink(sink: ((msg: string) => void) | null): void {
+  warnSink = sink;
+  warnedOnce.clear();
+}
+
+export function emitSettingsWarning(msg: string): void {
+  if (warnSink) {
+    if (warnedOnce.has(msg)) return;
+    warnedOnce.add(msg);
+    warnSink(msg);
+    return;
+  }
+  console.warn(msg);
+}
+
 function warnInvalid(key: string, entry: InvalidScope): void {
-  console.warn(
+  emitSettingsWarning(
     `rt: ignoring "${key}" from the ${entry.scope} scope (${entry.file ?? "no file"}): ${entry.reason}`,
   );
 }
@@ -543,7 +564,7 @@ export function listSettings(opts: ResolveOpts = {}): ListedSetting[] {
         listed.value = expandVariables(resolution.value, ctx);
       } catch (err) {
         listed.expandError = (err as Error).message;
-        console.warn(`rt: showing "${def.key}" unexpanded — ${listed.expandError}`);
+        emitSettingsWarning(`rt: showing "${def.key}" unexpanded — ${listed.expandError}`);
       }
     }
 
@@ -583,7 +604,7 @@ function listUnregistered(stores: StoreBundle, opts: ResolveOpts): ListedSetting
   return [...found.entries()]
     .sort(([a], [b]) => a.localeCompare(b))
     .map(([key, hit]) => {
-      console.warn(
+      emitSettingsWarning(
         `rt: unregistered setting "${key}" in ${hit.file} — ignoring it (this rt may be older than the store)`,
       );
       return {

package/src/smart-pane.ts

@@ -0,0 +1,94 @@
+/**
+ * Layout-smart herdr pane placement. `decidePlacement` is pure (geometry ->
+ * where a new pane should go); `openSmartPane` reads an anchor pane's real
+ * rect, decides, and performs the herdr call through an injected caller so it
+ * works over any transport (socket API or a CLI adapter).
+ */
+
+export type Placement =
+  | { kind: "split"; direction: "right" | "down" }
+  | { kind: "tab" };
+
+export interface PlacementOpts {
+  minCols?: number;
+  minRows?: number;
+}
+
+export interface HerdrCall {
+  (method: string, params: Record<string, unknown>): Promise<
+    { ok: true; result: any } | { ok: false; code: string; message: string }
+  >;
+}
+
+// A child below these is not worth splitting into; spill to a new tab instead.
+const DEFAULT_MIN_COLS = 50;
+const DEFAULT_MIN_ROWS = 14;
+
+/**
+ * Where to put a new pane relative to an anchor whose rect (in cells) is given.
+ * Cells are ~2:1 (height:width in px), so a pane is visually wider than tall
+ * when width > 2*height; split the longer visual axis so both halves stay
+ * usable. A null/degenerate rect falls back to a right split (old behavior).
+ */
+export function decidePlacement(
+  rect: { width: number; height: number } | null,
+  opts: PlacementOpts = {},
+): Placement {
+  const minCols = opts.minCols ?? DEFAULT_MIN_COLS;
+  const minRows = opts.minRows ?? DEFAULT_MIN_ROWS;
+  if (!rect || rect.width <= 0 || rect.height <= 0) return { kind: "split", direction: "right" };
+  const canRight = rect.width >= 2 * minCols;
+  const canDown = rect.height >= 2 * minRows;
+  if (!canRight && !canDown) return { kind: "tab" };
+  if (canRight && canDown) {
+    return rect.width > 2 * rect.height
+      ? { kind: "split", direction: "right" }
+      : { kind: "split", direction: "down" };
+  }
+  return canRight ? { kind: "split", direction: "right" } : { kind: "split", direction: "down" };
+}
+
+/** The anchor pane's rect from a herdr `pane.layout`, or null if unavailable. */
+async function anchorRect(
+  herdr: HerdrCall,
+  anchorPaneId: string,
+): Promise<{ width: number; height: number } | null> {
+  const r = await herdr("pane.layout", { pane_id: anchorPaneId });
+  if (!r.ok) return null;
+  const pane = (r.result?.layout?.panes ?? []).find((p: any) => p.pane_id === anchorPaneId);
+  return pane?.rect ? { width: pane.rect.width, height: pane.rect.height } : null;
+}
+
+/**
+ * Open a herdr pane placed intelligently next to `anchorPaneId` (split right or
+ * down, or a new tab when crowded). Optionally run `command` in it. Returns the
+ * new pane id and the placement chosen. Throws on a herdr failure.
+ */
+export async function openSmartPane(
+  herdr: HerdrCall,
+  anchorPaneId: string,
+  opts: { command?: string; focus?: boolean } & PlacementOpts = {},
+): Promise<{ paneId: string; placement: Placement }> {
+  const focus = opts.focus ?? true;
+  const placement = decidePlacement(await anchorRect(herdr, anchorPaneId), opts);
+
+  let paneId: string | undefined;
+  if (placement.kind === "split") {
+    const s = await herdr("pane.split", { pane_id: anchorPaneId, direction: placement.direction, focus });
+    if (!s.ok) throw new Error(`pane.split failed: ${s.message}`);
+    paneId = s.result?.pane?.pane_id;
+    if (!paneId) throw new Error("pane.split returned no pane_id");
+  } else {
+    const workspaceId = anchorPaneId.split(":")[0];
+    const t = await herdr("tab.create", { workspace_id: workspaceId, focus });
+    if (!t.ok) throw new Error(`tab.create failed: ${t.message}`);
+    paneId = t.result?.root_pane?.pane_id;
+    if (!paneId) throw new Error("tab.create returned no pane_id");
+  }
+
+  if (opts.command) {
+    await herdr("pane.send_text", { pane_id: paneId, text: opts.command });
+    await herdr("pane.send_keys", { pane_id: paneId, keys: ["enter"] });
+  }
+  return { paneId, placement };
+}

package/src/transport.ts

@@ -14,6 +14,10 @@ export interface RtResponse<T = unknown> {
   ok: boolean;
   data?: T;
   error?: string;
+  /** Structured form of `error` on a handler throw (R035): `code` defaults
+   *  to "handler-threw" when the thrown error carries none. Additive; older
+   *  daemons and the reject path never set this. */
+  failure?: { code: string; message: string };
 }
 
 export interface RtClientOptions {
@@ -57,7 +61,7 @@ export async function rtCommand<T = unknown>(
     const res = await fetch(`http://localhost/${cmd}`, {
       unix: sockPath,
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", "X-RT-Client": `rt-client/${process.pid}` },
       body: JSON.stringify(payload),
       signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
       // Bun's `unix` fetch option isn't in the standard RequestInit type.