agent-relay-runner 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.8"
+    "agent-relay-sdk": "0.2.10"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapter.ts

@@ -1,4 +1,5 @@
 import type { AgentProfile, Message } from "agent-relay-sdk";
+import { isRecord } from "agent-relay-sdk";
 
 export type SemanticStatus = "idle" | "busy" | "offline" | "error";
 type ProviderWorkKind = "provider-turn" | "subagent";
@@ -160,10 +161,6 @@ export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a
 
 const PROVIDER_MESSAGE_BODY_PREVIEW_CHARS = 4000;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
 function attachmentRefs(message: Message): Record<string, unknown>[] {
   const payloadRefs = message.payload?.attachments;
   const topLevelRefs = (message as Message & { attachments?: unknown }).attachments;

package/src/adapters/claude-delivery.ts

@@ -1,4 +1,5 @@
 import type { Message } from "agent-relay-sdk";
+import { isRecord } from "agent-relay-sdk";
 import { providerAttachmentText } from "../adapter";
 
 const PROVIDER_MESSAGE_BODY_PREVIEW_CHARS = 4000;
@@ -30,10 +31,6 @@ function stripRelayScaffolding(body: string): string {
   return lines.join("\n");
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
 function isMemoryInjection(message: Message): boolean {
   return isRecord(message.payload) && message.payload.memoryInjection === true;
 }

package/src/adapters/claude.ts

@@ -2,6 +2,9 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import type { Message } from "agent-relay-sdk";
+import { shellEscape as shellQuote } from "agent-relay-sdk/shell-utils";
+import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import { profileAllowsRelayFeature, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderStatusUpdate, type RunnerSpawnConfig, type SemanticStatus, type SpawnArgs } from "../adapter";
 import { prepareClaudeProfileHome, profileUsesHostProviderGlobals } from "../profile-home";
 import { claudeProviderMessageText } from "./claude-delivery";
@@ -410,24 +413,16 @@ function hasSettingsArg(args: string[]): boolean {
 }
 
 export function tmuxSessionName(prefix: string, instanceId: string, label?: string): string {
-  if (label) return `${prefix}-${label.replace(/[^a-zA-Z0-9._-]/g, "-").toLowerCase()}`;
+  if (label) return `${prefix}-${sanitizeFsName(label, { replacement: "-", collapse: false, lowercase: true })}`;
   return `${prefix}-${instanceId.slice(0, 8)}`;
 }
 
 export function tmuxSocketName(sessionName: string): string {
-  return `agent-relay-${sessionName}`.replace(/[^a-zA-Z0-9._-]/g, "-").toLowerCase();
+  return sanitizeFsName(`agent-relay-${sessionName}`, { replacement: "-", collapse: false, lowercase: true });
 }
 
-function tmuxCommand(socketName: string | undefined, ...args: string[]): string[] {
-  return socketName ? ["tmux", "-L", socketName, ...args] : ["tmux", ...args];
-}
-
-export function tmuxHasSession(sessionName: string, socketName?: string): boolean {
-  const result = Bun.spawnSync(tmuxCommand(socketName, "has-session", "-t", sessionName), {
-    stdin: "ignore", stdout: "ignore", stderr: "ignore",
-  });
-  return result.exitCode === 0;
-}
+// Shared tmux helpers; tmuxHasSession re-exported for ./claude consumers + tests.
+export { tmuxHasSession };
 
 function captureTmuxPane(sessionName: string, socketName?: string): string {
   const result = Bun.spawnSync(tmuxCommand(socketName, "capture-pane", "-p", "-t", sessionName, "-S", "-80"), {
@@ -520,7 +515,7 @@ const LAUNCHER_DIR = join(tmpdir(), "agent-relay-launchers");
 
 function writeLauncherScript(sessionName: string, shellCmd: string): string {
   mkdirSync(LAUNCHER_DIR, { recursive: true });
-  const sanitized = sessionName.replace(/[^a-zA-Z0-9._-]/g, "-");
+  const sanitized = sanitizeFsName(sessionName, { replacement: "-", collapse: false });
   const scriptPath = join(LAUNCHER_DIR, `${sanitized}.sh`);
   writeFileSync(scriptPath, `#!/usr/bin/env bash\nexec ${shellCmd}\n`, { mode: 0o755 });
   return scriptPath;
@@ -539,11 +534,8 @@ export function tmuxEnvKeys(env: Record<string, string>, providerEnv: Record<str
   return [...keys].sort();
 }
 
-export function shellQuote(arg: string): string {
-  if (arg.length === 0) return "''";
-  if (/^[a-zA-Z0-9_./:@=+,-]+$/.test(arg)) return arg;
-  return `'${arg.replace(/'/g, "'\\''")}'`;
-}
+// Shared shell-quoting; re-exported so `./claude` consumers + tests resolve it.
+export { shellQuote };
 
 export function findClaudeRigRC(cwd: string): string | null {
   const home = homedir();

package/src/adapters/codex.ts

@@ -2,6 +2,8 @@ import { accessSync, constants, existsSync, readFileSync, realpathSync, readdirS
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import type { ContextState, Message } from "agent-relay-sdk";
+import { isRecord, stringValue } from "agent-relay-sdk";
+import { isPidAlive, killPid, waitForPidsExit } from "agent-relay-sdk/process-utils";
 import { profileAllowsRelayFeature, providerMessageText, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
 import { workspaceDepsNoteFromEnv } from "../relay-instructions";
 import { logger } from "../logger";
@@ -742,10 +744,6 @@ function activeFlags(value: unknown): string[] {
   return value.activeFlags.filter((flag): flag is string => typeof flag === "string" && flag.length > 0);
 }
 
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value ? value : undefined;
-}
-
 function numberValue(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
@@ -759,9 +757,6 @@ function isContextState(value: unknown): value is ContextState {
     typeof state.confidence === "string";
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 
 export function codexModelConfigArgs(model?: string, effort?: string): string[] {
   const args: string[] = [];
@@ -946,12 +941,6 @@ async function processTreePids(rootPids: number[]): Promise<number[]> {
   return processTreePidsFromTable(table, rootPids);
 }
 
-function killPid(pid: number, signal: "SIGTERM" | "SIGKILL"): void {
-  try {
-    process.kill(pid, signal);
-  } catch {}
-}
-
 function codexRelayContextEnabled(process: ManagedProcess): boolean {
   const config = process.meta?.config as RunnerSpawnConfig | undefined;
   return config ? profileAllowsRelayFeature(config, "context") : true;
@@ -968,21 +957,3 @@ function codexLaunchContext(process: ManagedProcess): string | undefined {
     text,
   ].join("\n");
 }
-
-function isPidAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function waitForPidsExit(pids: number[], timeoutMs: number): Promise<boolean> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (!pids.some(isPidAlive)) return true;
-    await Bun.sleep(100);
-  }
-  return !pids.some(isPidAlive);
-}

package/src/attachment-cache.ts

@@ -2,6 +2,8 @@ import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, write
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import type { Artifact, Message } from "agent-relay-sdk";
+import { errMessage, isRecord } from "agent-relay-sdk";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 
 const DEFAULT_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 
@@ -25,10 +27,6 @@ interface CachedAttachment {
   digest: string;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
 function attachmentRefs(message: Message): Record<string, unknown>[] {
   const payloadRefs = message.payload?.attachments;
   const topLevelRefs = (message as Message & { attachments?: unknown }).attachments;
@@ -75,7 +73,7 @@ async function messageWithCachedAttachments(
       nextRefs.push(withCacheMetadata(ref, cached));
       changed = true;
     } catch (error) {
-      options.onError?.(`attachment ${artifactId} cache failed: ${error instanceof Error ? error.message : String(error)}`);
+      options.onError?.(`attachment ${artifactId} cache failed: ${errMessage(error)}`);
       nextRefs.push(withCacheError(ref, error));
       changed = true;
     }
@@ -141,7 +139,7 @@ function withCacheError(ref: Record<string, unknown>, error: unknown): Record<st
       ...metadata,
       agentRelay: {
         ...agentRelay,
-        cacheError: error instanceof Error ? error.message : String(error),
+        cacheError: errMessage(error),
       },
     },
   };
@@ -186,5 +184,5 @@ function safeFilename(value: string): string {
 }
 
 function safePathPart(value: string): string {
-  return value.replace(/[^a-zA-Z0-9_.-]/g, "_").replace(/_+/g, "_").slice(0, 180);
+  return sanitizeFsName(value, { replacement: "_", collapseReplacement: true, maxLen: 180 });
 }

package/src/config.ts

@@ -1,6 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { join, resolve } from "node:path";
+import { stringValue } from "agent-relay-sdk";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import type { ProviderConfig } from "./adapter";
 
 interface GlobalRunnerConfig {
@@ -97,7 +99,7 @@ export function providerConfigPublic(config: LoadedProviderConfig): Record<strin
 
 export function runnerId(provider: string, cwd: string, label?: string): string {
   const project = cwd.split("/").filter(Boolean).at(-1) || "workspace";
-  const cleanLabel = (label || project).replace(/[^a-zA-Z0-9._-]+/g, "-").toLowerCase();
+  const cleanLabel = sanitizeFsName(label || project, { replacement: "-", lowercase: true });
   return `${hostname()}-${provider}-${cleanLabel}-${crypto.randomUUID().slice(0, 8)}`;
 }
 
@@ -115,10 +117,6 @@ function readJson(path: string): Record<string, unknown> {
   }
 }
 
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-
 function positiveInteger(value: unknown): number | undefined {
   return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
 }

package/src/control-server.ts

@@ -1,5 +1,6 @@
 import type { Server, ServerWebSocket } from "bun";
 import type { Message, ReplyObligation } from "agent-relay-sdk";
+import { errMessage, isRecord } from "agent-relay-sdk";
 import type { ProviderPermissionDecisionInput, ProviderStatusEvent, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { logger, parseLogLevel, LOG_LEVELS } from "./logger";
 
@@ -69,19 +70,19 @@ export function startControlServer(options: ControlServerOptions): ControlServer
         if (!options.onTerminalAttachSpec) return Response.json({ error: "terminal attach is unavailable" }, { status: 404 });
         return options.onTerminalAttachSpec()
           .then((spec) => Response.json(spec))
-          .catch((error) => Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 409 }));
+          .catch((error) => Response.json({ error: errMessage(error) }, { status: 409 }));
       }
       if (url.pathname === "/reply-obligations" && req.method === "GET") {
         if (!options.onReplyObligations) return Response.json({ pending: false, count: 0 });
         return options.onReplyObligations()
           .then((obligations) => Response.json(replyObligationSummary(obligations)))
-          .catch((error) => Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 503 }));
+          .catch((error) => Response.json({ error: errMessage(error) }, { status: 503 }));
       }
       if (url.pathname === "/reply-obligations/claude-stop" && req.method === "GET") {
         if (!options.onReplyObligations) return Response.json({});
         return options.onReplyObligations()
           .then((obligations) => Response.json(replyObligationStopDecision(obligations)))
-          .catch((error) => Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 503 }));
+          .catch((error) => Response.json({ error: errMessage(error) }, { status: 503 }));
       }
       if (url.pathname === "/permissions/request" && req.method === "POST") {
         return handlePermissionRequest(req, options, pendingPermissionRequests);
@@ -359,7 +360,7 @@ async function handleSessionTurn(req: Request, options: ControlServerOptions): P
     await options.onSessionTurn({ transcriptPath, lastAssistantMessage });
     return Response.json({ ok: true });
   } catch (error) {
-    return Response.json({ ok: false, reason: error instanceof Error ? error.message : String(error) }, { status: 500 });
+    return Response.json({ ok: false, reason: errMessage(error) }, { status: 500 });
   }
 }
 
@@ -453,7 +454,3 @@ function parseJson(raw: string | Buffer): Record<string, unknown> | null {
     return null;
   }
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}

package/src/index.ts

@@ -8,6 +8,7 @@ import { AgentRunner } from "./runner";
 import { loadGlobalConfig, loadProviderConfig, resolveCwd, runnerId } from "./config";
 import { VERSION } from "./version";
 import type { AgentProfile, WorkspaceMetadata } from "agent-relay-sdk";
+import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 
 interface CliOptions {
   provider: "claude" | "codex";
@@ -139,7 +140,7 @@ export async function resolveRunnerToken(input: {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "X-Agent-Relay-Token": input.token,
+        [RELAY_TOKEN_HEADER]: input.token,
       },
       body: JSON.stringify({
         provider: input.provider,
@@ -156,7 +157,7 @@ export async function resolveRunnerToken(input: {
     const detail = body?.error ? `: ${body.error}` : "";
     console.warn(`[agent-relay] interactive scoped-token exchange failed (${res.status}${detail}); continuing with existing token. Root-token runtime fallback is deprecated.`);
   } catch (error) {
-    console.warn(`[agent-relay] interactive scoped-token exchange failed (${error instanceof Error ? error.message : String(error)}); continuing with existing token. Root-token runtime fallback is deprecated.`);
+    console.warn(`[agent-relay] interactive scoped-token exchange failed (${errMessage(error)}); continuing with existing token. Root-token runtime fallback is deprecated.`);
   }
   return { token: input.token, rootFallback: true };
 }

package/src/logger.ts

@@ -1,5 +1,6 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 
 // Phase 1 observability (#198): one leveled, runtime-togglable logger for the
 // Runner and the provider adapters below it. Replaces the ad-hoc scatter of
@@ -26,10 +27,10 @@ export function parseLogLevel(value: string | undefined | null): LogLevel | unde
   return (LOG_LEVELS as string[]).includes(v) ? (v as LogLevel) : undefined;
 }
 
-// Matches the runner's safeLogName and the orchestrator's safeMirrorLogName so all
-// three resolve the identical filename for a given agent id.
+// Shared with the orchestrator (session-mirror reader) + runner outbox via the
+// SDK helper, so all sites resolve the identical filename for a given agent id.
 function safeLogName(value: string): string {
-  return value.replace(/[^a-zA-Z0-9_.-]+/g, "_").slice(0, 180);
+  return sanitizeFsName(value, { replacement: "_", maxLen: 180 });
 }
 
 export interface LoggerConfig {

package/src/outbox.ts

@@ -2,6 +2,8 @@ import { Database } from "bun:sqlite";
 import { mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import { errMessage } from "agent-relay-sdk";
 import { logger } from "./logger";
 
 // Phase 2 (#196) — the "nothing is ever lost" half. Runner→server events that used to be
@@ -230,7 +232,7 @@ export class Outbox {
         this.db.query("DELETE FROM outbox WHERE seq = ?").run(row.seq);
       } catch (error) {
         const attempts = row.attempts + 1;
-        const reason = error instanceof Error ? error.message : String(error);
+        const reason = errMessage(error);
         if (attempts >= this.maxAttempts) {
           this.db.query("UPDATE outbox SET attempts = ?, poisoned = 1 WHERE seq = ?").run(attempts, row.seq);
           logger.fatal("outbox", `event seq=${row.seq} kind=${row.kind} poisoned after ${attempts} attempts: ${reason}`);
@@ -284,7 +286,7 @@ export class Outbox {
 }
 
 function safeName(value: string): string {
-  return value.replace(/[^a-zA-Z0-9_.-]+/g, "_").slice(0, 180) || "agent";
+  return sanitizeFsName(value, { replacement: "_", maxLen: 180, fallback: "agent" });
 }
 
 function safeParse(json: string): unknown {

package/src/profile-home.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import { profileAllowsRelayFeature, type RunnerSpawnConfig } from "./adapter";
 import { CLAUDE_RELAY_MANUAL } from "./relay-instructions";
 
@@ -35,34 +36,41 @@ function profileRequiresIsolatedHome(config: RunnerSpawnConfig): boolean {
 // (claude-rig / host-base launches dodge all of this via onboarded host config +
 // --dangerously-skip-permissions; only isolated homes need the bootstrap.)
 
-export function prepareCodexProfileHome(config: RunnerSpawnConfig): ProviderHome | undefined {
+// Host auth items symlinked into a fresh isolated home so the provider is
+// launch-ready without a re-login. One list per provider — single source.
+const CODEX_AUTH_ITEMS = ["auth.json", "installation_id"];
+const CLAUDE_AUTH_ITEMS = [".credentials.json", "statsig"];
+
+// Shared skeleton for both providers: gate on isolated-profile, make the
+// instance-keyed home, run the provider-specific first-run bootstrap. The
+// bootstrap step is the only genuinely provider-specific part.
+export function prepareProviderHome(provider: "claude" | "codex", config: RunnerSpawnConfig): ProviderHome | undefined {
   if (!profileRequiresIsolatedHome(config)) return undefined;
-  const target = providerHomePath("codex", config);
+  const target = providerHomePath(provider, config);
   mkdirSync(target, { recursive: true });
-  return { path: target, authLinked: bootstrapCodexFirstRun(target, config) };
+  const authLinked = provider === "codex"
+    ? bootstrapCodexFirstRun(target, config)
+    : bootstrapClaudeFirstRun(target, config);
+  return { path: target, authLinked };
 }
 
+export const prepareCodexProfileHome = (config: RunnerSpawnConfig) => prepareProviderHome("codex", config);
+export const prepareClaudeProfileHome = (config: RunnerSpawnConfig) => prepareProviderHome("claude", config);
+
 function bootstrapCodexFirstRun(codexHome: string, config: RunnerSpawnConfig): string[] {
   trustWorkspaceForCodex(codexHome, config);
   const sourceHome = process.env.CODEX_HOME || join(homedir(), ".codex");
-  return linkExistingAuthItems(sourceHome, codexHome, ["auth.json", "installation_id"]);
+  return linkExistingAuthItems(sourceHome, codexHome, CODEX_AUTH_ITEMS);
 }
 
-export function prepareClaudeProfileHome(config: RunnerSpawnConfig): ProviderHome | undefined {
-  if (!profileRequiresIsolatedHome(config)) return undefined;
-  const target = providerHomePath("claude", config);
-  mkdirSync(target, { recursive: true });
+function bootstrapClaudeFirstRun(claudeHome: string, config: RunnerSpawnConfig): string[] {
   // Only inject the Relay usage manual when the profile actually wants a Relay
   // surface. An isolated-research profile (relay.context disabled) must not get
   // agent-relay communication instructions written into its config home.
-  if (profileAllowsRelayFeature(config, "context")) writeClaudeRelayManual(target);
-  return { path: target, authLinked: bootstrapClaudeFirstRun(target, config) };
-}
-
-function bootstrapClaudeFirstRun(claudeHome: string, config: RunnerSpawnConfig): string[] {
+  if (profileAllowsRelayFeature(config, "context")) writeClaudeRelayManual(claudeHome);
   seedClaudeConfigIfMissing(claudeHome, config);
   const sourceHome = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
-  return linkExistingAuthItems(sourceHome, claudeHome, [".credentials.json", "statsig"]);
+  return linkExistingAuthItems(sourceHome, claudeHome, CLAUDE_AUTH_ITEMS);
 }
 
 function seedClaudeConfigIfMissing(claudeHome: string, config: RunnerSpawnConfig): void {
@@ -104,7 +112,7 @@ function providerHomePath(provider: "claude" | "codex", config: RunnerSpawnConfi
 }
 
 function sanitizePathPart(value: string): string {
-  return value.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 120) || "profile";
+  return sanitizeFsName(value, { replacement: "-", collapse: false, maxLen: 120, fallback: "profile" });
 }
 
 function linkExistingAuthItems(sourceHome: string, targetHome: string, items: string[]): string[] {

package/src/relay-instructions.ts

@@ -37,7 +37,7 @@ export function workspaceDepsNote(input: { mode?: string | null; depsMode?: stri
   if (input.mode !== "isolated") return "";
   switch (input.depsMode) {
     case "symlink":
-      return "[agent-relay] Isolated workspace: this is a git worktree, and its node_modules are SYMLINKED from the main checkout — dependencies are already installed and ready to use. Do NOT run a clean dependency install (`bun install` / `npm install` / `pnpm install`): it writes through the symlink and mutates the main checkout's shared node_modules. Build caches written under node_modules are shared too. If you genuinely need to change dependencies in isolation, ask the host to spawn with AGENT_RELAY_WORKSPACE_DEPS=install.";
+      return "[agent-relay] Isolated workspace: this is a git worktree, and its node_modules are SYMLINKED from the main checkout — dependencies are already installed and ready to use. Do NOT run a clean dependency install (`bun install` / `npm install` / `pnpm install`): it writes through the symlink and mutates the main checkout's shared node_modules. Build caches written under node_modules are shared too. If typecheck/build fails on a missing module (a dependency added to the base AFTER this worktree was created), run `agent-relay workspace deps` — it re-provisions only the stale dirs with a real isolated install, safely, without touching the shared node_modules. If you genuinely need to change dependencies in isolation, ask the host to spawn with AGENT_RELAY_WORKSPACE_DEPS=install.";
     case "none":
       return "[agent-relay] Isolated workspace: dependencies were not provisioned (AGENT_RELAY_WORKSPACE_DEPS=none). You may need to install node_modules before typecheck/test/build work.";
     default:
@@ -45,6 +45,23 @@ export function workspaceDepsNote(input: { mode?: string | null; depsMode?: stri
   }
 }
 
+/**
+ * Lifecycle briefing for an agent spawned into an isolated workspace (#205).
+ * Tells it, in plain terms, that it is on an isolated branch off a base that
+ * other agents move in parallel, and how to hand off — so it doesn't re-derive
+ * "I seem to be in a clone, not on main" every session or hand-roll a rebase/push.
+ * Returns "" for shared workspaces. Branch/base come from the resolved metadata.
+ */
+export function workspaceLifecycleNote(input: { mode?: string | null; branch?: string | null; baseRef?: string | null }): string {
+  if (input.mode !== "isolated") return "";
+  const branch = input.branch ? `\`${input.branch}\`` : "an isolated agent branch";
+  const base = input.baseRef ? `\`${input.baseRef}\`` : "the base branch";
+  return [
+    `[agent-relay] Isolated workspace: you are in a git worktree on branch ${branch}, based on ${base} — NOT the main checkout. Other agents may work in parallel and land to ${base}, so ${base} will move under you. That is expected; don't fight it.`,
+    `Do NOT push this branch yourself — not with \`git push\`, not with \`tl push\` or any other push wrapper, and do not manually rebase or merge. A steward may be auto-rebasing this branch in the background; pushing concurrently races it and can leave the worktree mid-rebase. Just commit your work here. When the task is done, run \`agent-relay workspace ready\` — Relay rebases onto the latest ${base}, lands your work, and pushes for you. (\`agent-relay workspace status\` shows the current state.)`,
+  ].join("\n");
+}
+
 /**
  * Caveat for untracked paths symlinked from main into an isolated worktree
  * (WorkspaceConfig.symlinkPaths, e.g. AGENTS.md, .claude-rig). Edits to these
@@ -63,8 +80,9 @@ export function workspaceDepsNoteFromEnv(env: Record<string, string | undefined>
   const json = env.AGENT_RELAY_WORKSPACE_JSON;
   if (!json) return "";
   try {
-    const parsed = JSON.parse(json) as { mode?: string; deps?: { mode?: string }; symlinks?: { linked?: string[] } };
+    const parsed = JSON.parse(json) as { mode?: string; branch?: string; baseRef?: string; deps?: { mode?: string }; symlinks?: { linked?: string[] } };
     return [
+      workspaceLifecycleNote({ mode: parsed.mode ?? null, branch: parsed.branch ?? null, baseRef: parsed.baseRef ?? null }),
       workspaceDepsNote({ mode: parsed.mode ?? null, depsMode: parsed.deps?.mode ?? null }),
       parsed.mode === "isolated" ? workspaceSymlinksNote(parsed.symlinks?.linked ?? []) : "",
     ].filter(Boolean).join("\n\n");

package/src/reply-obligation-cache.ts

@@ -1,4 +1,5 @@
 import type { ReplyObligation } from "agent-relay-sdk";
+import { errMessage } from "agent-relay-sdk";
 import { logger } from "./logger";
 
 // Phase 2 (#196) — the crux. The Claude Stop hook used to ask the server, synchronously
@@ -103,7 +104,7 @@ export class ReplyObligationCache {
     } catch (error) {
       // Server-down is a non-event: keep serving the last snapshot. Debug, not error —
       // this is expected during outages and must not spam the log.
-      logger.debug("obligation-cache", `refresh failed, serving cached snapshot (${this.snapshot.length}): ${error instanceof Error ? error.message : String(error)}`);
+      logger.debug("obligation-cache", `refresh failed, serving cached snapshot (${this.snapshot.length}): ${errMessage(error)}`);
     }
   }
 }

package/src/runner.ts

@@ -3,7 +3,7 @@ import { closeSync, mkdirSync, openSync, readSync, statSync, writeFileSync } fro
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { AgentProfile, ContextState, Message, MessageSessionMeta, ProviderCapabilities, SendMessageInput, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
-import { RelayBusClient, RelayHttpClient } from "agent-relay-sdk";
+import { errMessage, RelayBusClient, RelayHttpClient } from "agent-relay-sdk";
 import { contextStateFromProbeMetrics, readContextProbeState } from "agent-relay-sdk/context-probe";
 import type { ManagedProcess, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderSessionEvent, ProviderStatusUpdate, RunnerSpawnConfig, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { messagesWithCachedAttachments } from "./attachment-cache";
@@ -574,7 +574,7 @@ export class AgentRunner {
         ...(providerResult ? { providerResult } : {}),
       });
     } catch (error) {
-      await this.updateCommand(commandId, "failed", undefined, error instanceof Error ? error.message : String(error)).catch(() => {});
+      await this.updateCommand(commandId, "failed", undefined, errMessage(error)).catch(() => {});
     } finally {
       this.claims.finishClaim("command", commandId);
       if (exitAfterCommand) {
@@ -1078,7 +1078,7 @@ export class AgentRunner {
         },
       });
     } catch (error) {
-      logger.error("outbox", `failed to queue hook-fatal report: ${error instanceof Error ? error.message : String(error)}`);
+      logger.error("outbox", `failed to queue hook-fatal report: ${errMessage(error)}`);
     }
   }
 
@@ -1474,7 +1474,7 @@ export class AgentRunner {
         fallbackBaseDir: process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR,
       });
     } catch (error) {
-      this.logRunnerDiagnostic(`session scratch setup failed: ${error instanceof Error ? error.message : String(error)}`);
+      this.logRunnerDiagnostic(`session scratch setup failed: ${errMessage(error)}`);
     }
   }
 
@@ -1873,7 +1873,7 @@ function commandTimeoutMs(params: Record<string, unknown>, fallback = 10_000): n
 }
 
 export function shouldLogDeliveryFailure(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error);
+  const message = errMessage(error);
   return message !== "no Claude monitor connected";
 }
 

package/src/version.ts

@@ -1,14 +1,16 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONTRACT_VERSIONS } from "agent-relay-sdk";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8")) as { name?: string; version?: string };
 
 export const PACKAGE_NAME = pkg.name || "agent-relay-runner";
 export const VERSION = pkg.version || "0.0.0";
-export const RUNNER_PROTOCOL_VERSION = 1;
-export const PROVIDER_PLUGIN_PROTOCOL_VERSION = 1;
+// Protocol versions are owned by the SDK (CONTRACT_VERSIONS) — derive, never redeclare.
+export const RUNNER_PROTOCOL_VERSION = CONTRACT_VERSIONS.runnerProtocol;
+export const PROVIDER_PLUGIN_PROTOCOL_VERSION = CONTRACT_VERSIONS.providerPluginProtocol;
 
 export const CONTRACTS = {
   runnerProtocol: RUNNER_PROTOCOL_VERSION,