@humwick/runner 0.0.0-stage → 0.130.1

package/src/config.ts

@@ -0,0 +1,547 @@
+import { relayEnv, writeChildEnv } from "@humwick/sdk/env";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { DEFAULT_RELAY_URL, PROJECT_TOOLCHAIN_ENV, RUNNER_CONFIG_RETRY_TIMEOUT_MS, ReconnectionManager, errMessage, isRecord, localOrchestratorIdFromEnv, stringValue } from "@humwick/sdk";
+import type { ProjectToolchain, WorkspaceMetadata } from "@humwick/sdk";
+import { sanitizeFsName } from "@humwick/sdk/fs-name";
+import { defaultApprovalModeForProvider, getManifest } from "@humwick/providers";
+import { fetchStartupConfig, type StartupFetchDeps } from "./startup-config-fetch";
+import { spawnSyncBounded } from "./bounded-spawn-sync";
+import { ACTIVE_TURN_MESSAGE_DELIVERY_VALUES, type ActiveTurnMessageDelivery } from "./adapter";
+
+interface ProviderConfig {
+  command: string;
+  defaultArgs: string[];
+  env: Record<string, string>;
+  pluginDirs: string[];
+  globalInstructionFiles?: string[];
+  defaultCapabilities: string[];
+  defaultApprovalMode: string;
+  defaultTags: string[];
+  chatCaptureMode: "final" | "full";
+  reasoningCapture?: boolean;
+  // #2539 Phase A — optional: absent resolves through the OWNING adapter's default (codex
+  // adapter → steer, others → defer). `"defer"` is the operational kill switch for soft-steer.
+  activeTurnMessageDelivery?: ActiveTurnMessageDelivery;
+  headless: {
+    tmuxPrefix: string;
+    shutdownTimeoutMs: number;
+  };
+}
+
+interface GlobalRunnerConfig {
+  relayUrl: string;
+  token?: string;
+  defaultCwd: string;
+}
+
+interface LoadedProviderConfig extends ProviderConfig {
+  path: string;
+}
+
+export function humwickHome(): string {
+  return relayEnv(process.env, "AGENT_RELAY_HOME") || join(homedir(), ".agent-relay");
+}
+
+export function logDirFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_LOG_DIR");
+}
+
+function providersDir(home = humwickHome()): string {
+  return join(home, "providers");
+}
+
+const DEFAULT_PROVIDER_ARGS: Record<string, string[]> = {
+  claude: ["--dangerously-skip-permissions"],
+};
+
+export function defaultProviderConfig(provider: string): ProviderConfig {
+  const manifest = getManifest(provider);
+  const home = recordValue(manifest?.home);
+  return {
+    command: manifest?.probe?.command ?? provider,
+    defaultArgs: DEFAULT_PROVIDER_ARGS[provider] ?? [],
+    env: {},
+    pluginDirs: [],
+    globalInstructionFiles: stringArray(home.globalInstructionFiles) ?? [],
+    defaultCapabilities: ["chat", "code", "review"],
+    defaultApprovalMode: defaultApprovalModeForProvider(provider),
+    defaultTags: [],
+    chatCaptureMode: "final",
+    reasoningCapture: true,
+    // #2539 Phase A — deliberately NOT set here: absent resolves through the OWNING adapter's
+    // default (codex → steer, others → defer) at the steer policy seam, so this config module
+    // carries no provider-identity branch (lint:provider-contract).
+    headless: {
+      tmuxPrefix: `${provider}-relay`,
+      shutdownTimeoutMs: 10_000,
+    },
+  };
+}
+
+export function loadGlobalConfig(home = humwickHome()): GlobalRunnerConfig {
+  const path = join(home, "config.json");
+  const parsed = readJson(path);
+  return {
+    relayUrl: stringValue(parsed.relayUrl) ?? relayUrlFromEnv() ?? DEFAULT_RELAY_URL,
+    token: stringValue(parsed.token) ?? relayTokenFromEnv(),
+    defaultCwd: stringValue(parsed.defaultCwd) ?? process.cwd(),
+  };
+}
+
+function relayUrlFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_URL");
+}
+
+// #1096 — override for the Codex hooks version gate (finding 4). An explicit version string
+// bypasses the `codex --version` probe: deterministic in tests, and an operator escape hatch
+// when the probe can't run. Empty string means "assume supported".
+export function codexVersionOverrideFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_CODEX_VERSION");
+}
+
+function textEnvOrFile(name: string): string | undefined {
+  const inline = relayEnv(process.env, name);
+  if (inline) return inline;
+  const file = relayEnv(process.env, `${name}_FILE`);
+  if (!file) return undefined;
+  try {
+    const text = readFileSync(file, "utf8");
+    return text.length > 0 ? text : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function relayTokenFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_TOKEN");
+}
+
+// #2254 — escape hatch for the per-launch Claude folder-trust seed. Off by default: an
+// unseeded launch wedges on CC's trust dialog until a human answers, so this exists only for
+// an operator who deliberately wants relay to keep its hands off a shared config. Never set
+// it to protect a test — tests point CLAUDE_CONFIG_DIR at a fixture instead
+// (scripts/test-preload-provider-home.ts), so the production path stays exercised.
+export function claudeTrustSeedDisabledFromEnv(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_TRUST_SEED_DISABLED") === "1";
+}
+
+// #2950 slice flag: launch Claude with `--effort` and accept mid-session effort switches.
+export function effortSwitchEnabledFromEnv(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_EFFORT_SWITCH") === "1";
+}
+
+export function runtimeTokenProfileFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_TOKEN_PROFILE");
+}
+
+export function runtimeTokenJtiFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_TOKEN_JTI");
+}
+
+export function runtimeTokenExpiresAtFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_TOKEN_EXPIRES_AT");
+}
+
+export function runtimeTokenFileFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_TOKEN_FILE");
+}
+
+export function runtimeTokenExpiresAtFileFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_TOKEN_EXPIRES_AT_FILE");
+}
+
+// Deadline for a freshly spawned runner's INITIAL relay registration. Reconnects after the
+// first registration retry forever (a long-lived agent rides out a relay blip), but the
+// initial handshake is bounded: a runner that can never register (a token the relay rejects,
+// an unreachable relay) must EXIT instead of hanging `active` forever — a hung runner is
+// invisible to the orchestrator's exit detection, so the spawn-parent is never notified.
+export function registrationTimeoutMsFromEnv(): number {
+  const parsed = Number(relayEnv(process.env, "AGENT_RELAY_REGISTRATION_TIMEOUT_MS"));
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 60_000;
+}
+
+export { NATIVE_SELF_RESUME_TIMEOUT_MS, MIN_NATIVE_SELF_RESUME_TIMEOUT_MS, nativeSelfResumeTimeoutMsFromEnv } from "@humwick/sdk";
+
+// #2095 self-compact e2e test rig — one-shot forced context utilization. When set, the runner
+// REPORTS a synthetic ContextState at this utilization (lifecycleState "working", source "estimate",
+// confidence "estimated") so the server's REAL 10s lifecycle tick fires the REAL advisory + REAL
+// forced clear-inject exactly once — the actual compaction path is never stubbed. Accepts a fraction
+// (0.90) or a percentage (90); both normalize to a 0..1 fraction. Unparseable / out of range (<=0 or
+// >1 after normalization) → undefined = feature OFF, and the runner's context reporting is UNCHANGED.
+// The strict one-shot LATCH lives in runner-core (heartbeatRuntimeMeta + handleCommand), not here.
+export function forceContextPctFromEnv(): number | undefined {
+  const raw = relayEnv(process.env, "AGENT_RELAY_FORCE_CONTEXT_PCT");
+  if (raw === undefined || raw.trim() === "") return undefined;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
+  // Accept a fraction (0.90) or a percentage (90): a value above 1 is read as a percentage. This is a
+  // config-lever parse (the value may already be a fraction), NOT the quota percent path, so it does
+  // not use normalizePercentUnit's always-/100 adapter rule.
+  let fraction = parsed;
+  if (fraction > 1) fraction = fraction / 100;
+  if (!(fraction > 0) || fraction > 1) return undefined;
+  return fraction;
+}
+
+export function agentProfileNameFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_AGENT_PROFILE");
+}
+
+/** Explicit launch policy is independent of whether the named profile still exists. */
+export function harnessSubagentsFromEnv(env: Record<string, string | undefined> = process.env): boolean | undefined {
+  const value = relayEnv(env, "AGENT_RELAY_HARNESS_SUBAGENTS");
+  return value === "1" ? true : value === "0" ? false : undefined;
+}
+
+export function agentProfileJsonFromEnv(): string | undefined {
+  return textEnvOrFile("AGENT_RELAY_AGENT_PROFILE_JSON");
+}
+
+export function workspaceJsonFromEnv(): string | undefined {
+  return textEnvOrFile("AGENT_RELAY_WORKSPACE_JSON");
+}
+
+/** #2947 — the toolchain the orchestrator launched this runner on, reported at registration; the relay validates it. */
+export function projectToolchainFromEnv(): ProjectToolchain | undefined {
+  try {
+    const parsed: unknown = JSON.parse(relayEnv(process.env, PROJECT_TOOLCHAIN_ENV) ?? "");
+    return isRecord(parsed) && typeof parsed.project === "string" && Array.isArray(parsed.tools) ? parsed as unknown as ProjectToolchain : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function relayInjectionEventsJsonFromEnv(): string | undefined {
+  return textEnvOrFile("AGENT_RELAY_INJECTION_EVENTS_JSON");
+}
+
+export function promptFromEnv(): string | undefined {
+  return textEnvOrFile("AGENT_RELAY_PROMPT");
+}
+
+export function systemPromptAppendFromEnv(): string | undefined {
+  return textEnvOrFile("AGENT_RELAY_SYSTEM_PROMPT_APPEND");
+}
+
+export function tmuxSessionFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_TMUX_SESSION");
+}
+
+export function policyNameFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_POLICY");
+}
+
+export function spawnRequestIdFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_SPAWN_REQUEST_ID");
+}
+
+export function taskIdFromEnv(): number | undefined {
+  const parsed = Number(relayEnv(process.env, "AGENT_RELAY_TASK_ID"));
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+export function automationIdFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_AUTOMATION_ID");
+}
+
+export function automationRunIdFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_AUTOMATION_RUN_ID");
+}
+
+export function lifecycleFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_LIFECYCLE");
+}
+
+export function sessionDebugEnabled(): boolean {
+  return relayEnv(process.env, "AGENT_RELAY_SESSION_DEBUG") === "1";
+}
+
+export function logLevelFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_LOG_LEVEL");
+}
+
+function envSwitchOn(name: string): boolean {
+  return !["0", "false", "off"].includes((relayEnv(process.env, name) ?? "").trim().toLowerCase());
+}
+
+export function mcpProxyEnabledFromEnv(): boolean {
+  return envSwitchOn("AGENT_RELAY_MCP_PROXY");
+}
+
+/** #3025 rollback switch for agent-redact secret redaction hooks. */
+export function redactionEnabledFromEnv(): boolean {
+  return envSwitchOn("AGENT_RELAY_REDACT");
+}
+
+export function runnerInfoFileFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_RUNNER_INFO_FILE");
+}
+
+// #1514 — the owning orchestrator's state-home id, stamped onto each tmux session
+// (@agent-relay-owner) so the wedged-session reaper only reaps sessions it owns.
+export function tmuxOwnerIdFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_TMUX_OWNER");
+}
+
+export function runnerOutboxDirFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_RUNNER_OUTBOX_DIR");
+}
+
+export function runnerOutboxDirWithInfoFallback(): string | undefined {
+  const dir = runnerOutboxDirFromEnv();
+  if (dir) return dir;
+  const infoFile = runnerInfoFileFromEnv();
+  return infoFile ? join(dirname(infoFile), "outbox") : undefined;
+}
+
+export function capsFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_CAPS");
+}
+
+export function tagsFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_TAGS");
+}
+
+export function workspaceModeFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_WORKSPACE_MODE");
+}
+
+export function orchestratorBaseDirFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_ORCHESTRATOR_BASE_DIR");
+}
+
+/**
+ * The orchestrator stamps its stable Relay id on every managed runner. Central
+ * provider configuration is keyed by that id, rather than the mutable OS hostname
+ * (for example, orchestrator `wbox` may report hostname `wbox-1`). Interactive
+ * runners have no owner id and retain the hostname-scoped fallback.
+ */
+export function providerConfigHostFromEnv(): string {
+  return localOrchestratorIdFromEnv() ?? hostname();
+}
+
+/** Stable managed key plus hostname-only compatibility read for legacy central rows. */
+export function providerConfigLookupFromEnv(): { host: string; legacyHost?: string; managed: boolean } {
+  const managedHost = localOrchestratorIdFromEnv();
+  if (!managedHost) return { host: hostname(), managed: false };
+  const legacyHost = relayEnv(process.env, "AGENT_RELAY_ORCHESTRATOR_HOSTNAME")?.trim();
+  return {
+    host: managedHost,
+    ...(legacyHost && legacyHost !== managedHost ? { legacyHost } : {}),
+    managed: true,
+  };
+}
+
+export function runnerLogFileFromEnv(): string | undefined {
+  return typeof relayEnv(process.env, "AGENT_RELAY_LOG_FILE") === "string" ? relayEnv(process.env, "AGENT_RELAY_LOG_FILE") : undefined;
+}
+
+export function orchestratorUrlFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_ORCHESTRATOR_URL");
+}
+
+export function contextStateDirFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_CONTEXT_STATE_DIR");
+}
+
+export function attachmentCacheDirFromEnv(): string | undefined {
+  return relayEnv(process.env, "AGENT_RELAY_ATTACHMENT_CACHE_DIR");
+}
+
+export function providerHomeRootFromEnv(): string {
+  return relayEnv(process.env, "AGENT_RELAY_PROVIDER_HOME_ROOT") || join(homedir(), ".agent-relay", "provider-homes");
+}
+
+export function loadProviderConfig(provider: string, home = humwickHome()): LoadedProviderConfig {
+  const path = join(providersDir(home), `${provider}.json`);
+  const raw = readJson(path);
+  const defaults = defaultProviderConfig(provider);
+  return {
+    path,
+    command: stringValue(raw.command) ?? defaults.command,
+    defaultArgs: stringArray(raw.defaultArgs) ?? defaults.defaultArgs,
+    env: stringRecord(raw.env) ?? defaults.env,
+    pluginDirs: stringArray(raw.pluginDirs) ?? defaults.pluginDirs,
+    globalInstructionFiles: stringArray(raw.globalInstructionFiles) ?? defaults.globalInstructionFiles,
+    defaultCapabilities: stringArray(raw.defaultCapabilities) ?? defaults.defaultCapabilities,
+    defaultApprovalMode: stringValue(raw.defaultApprovalMode) ?? defaults.defaultApprovalMode,
+    defaultTags: stringArray(raw.defaultTags) ?? defaults.defaultTags,
+    chatCaptureMode: enumValue(raw.chatCaptureMode, ["final", "full"]) ?? defaults.chatCaptureMode,
+    reasoningCapture: booleanValue(raw.reasoningCapture) ?? defaults.reasoningCapture,
+    // #2539 — an invalid value falls back to absent, which the steer policy resolves through
+    // the owning adapter's default.
+    activeTurnMessageDelivery: enumValue(raw.activeTurnMessageDelivery, [...ACTIVE_TURN_MESSAGE_DELIVERY_VALUES]),
+    headless: {
+      tmuxPrefix: stringValue(recordValue(raw.headless).tmuxPrefix) ?? defaults.headless.tmuxPrefix,
+      shutdownTimeoutMs: positiveInteger(recordValue(raw.headless).shutdownTimeoutMs) ?? defaults.headless.shutdownTimeoutMs,
+    },
+  };
+}
+
+export async function loadProviderConfigFromRelay(
+  provider: string,
+  opts: { relayUrl: string; token?: string; home?: string; host?: string; legacyHost?: string; managed?: boolean },
+): Promise<LoadedProviderConfig> {
+  const host = opts.host ?? hostname();
+  const home = opts.home ?? humwickHome();
+  const local = loadProviderConfig(provider, home);
+  const key = `${host}/${provider}`;
+  const attemptedKeys = [key];
+  const retry = opts.managed ? { deadlineAt: Date.now() + Math.min(registrationTimeoutMsFromEnv(), RUNNER_CONFIG_RETRY_TIMEOUT_MS), reconnect: new ReconnectionManager() } : undefined;
+
+  try {
+    const fetched = await fetchProviderConfig(provider, opts.relayUrl, opts.token, key, retry);
+    if (fetched && fetched.version > 0) return fetched.config;
+    if (opts.legacyHost) {
+      const legacyKey = `${opts.legacyHost}/${provider}`;
+      attemptedKeys.push(legacyKey);
+      const legacy = await fetchProviderConfig(provider, opts.relayUrl, opts.token, legacyKey, retry);
+      if (legacy && legacy.version > 0) {
+        console.warn(`[agent-relay] central provider config ${key} is missing; using legacy hostname key ${legacyKey}. Migrate this row to ${key}.`);
+        return legacy.config;
+      }
+      if (!fetched && legacy) return legacy.config;
+    }
+    if (fetched) return fetched.config;
+    if (opts.managed) throw new Error(`central provider config missing for managed keys ${attemptedKeys.join(", ")}`);
+  } catch (error) {
+    // #3238: a local fallback can select a different, obsolete provider binary.
+    if (opts.managed) throw new Error(`Managed provider config ${key} could not be loaded: ${errMessage(error)}`);
+    console.warn(`[agent-relay] provider config relay read failed (${errMessage(error)}); using local fallback ${local.path}.`);
+  }
+  return local;
+}
+
+export function writeProviderConfig(provider: string, config: ProviderConfig, home = humwickHome()): LoadedProviderConfig {
+  const dir = providersDir(home);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${provider}.json`);
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  chmodSync(path, 0o600);
+  return { ...config, path };
+}
+
+export function runnerId(provider: string, cwd: string, label?: string): string {
+  const project = cwd.split("/").filter(Boolean).at(-1) || "workspace";
+  const cleanLabel = sanitizeFsName(label || project, { replacement: "-", lowercase: true });
+  return `${hostname()}-${provider}-${cleanLabel}-${crypto.randomUUID().slice(0, 8)}`;
+}
+
+/**
+ * Stable project identifier for insights aggregation: the repo NAME, never a
+ * per-branch/per-session worktree dir or full path. Isolated workspace agents run
+ * from a session-specific worktree (…/workspaces/<repo>/<id>) whose basename is
+ * unique per session — using it would scatter one repo's data across many "projects"
+ * and break per-project rollups. So we resolve up to the main repo root, then take
+ * its basename. Falls back to the git toplevel of cwd (handles a direct agent
+ * launched in a subdir), then to the cwd basename for a non-git directory.
+ */
+export function resolveProjectName(cwd: string, workspace?: WorkspaceMetadata): string {
+  const root =
+    workspace?.repoRoot ||
+    workspace?.probe?.repoRoot ||
+    gitToplevel(cwd) ||
+    workspace?.sourceCwd ||
+    cwd;
+  return root.split("/").filter(Boolean).at(-1) || "unknown";
+}
+
+function gitToplevel(cwd: string): string | undefined {
+  try {
+    const result = spawnSyncBounded(["git", "-C", cwd, "rev-parse", "--show-toplevel"], {
+      stdin: "ignore", stdout: "pipe", stderr: "ignore",
+    });
+    if (result.exitCode !== 0) return undefined;
+    const out = result.stdout.toString().trim();
+    return out || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveCwd(value: string | undefined, fallback: string): string {
+  return resolve(value || fallback);
+}
+
+function readJson(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : {};
+  } catch {
+    return {};
+  }
+}
+
+function positiveInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+function enumValue<T extends string>(value: unknown, allowed: T[]): T | undefined {
+  return typeof value === "string" && allowed.includes(value as T) ? (value as T) : undefined;
+}
+
+function booleanValue(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function stringArray(value: unknown): string[] | undefined {
+  return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : undefined;
+}
+
+function stringRecord(value: unknown): Record<string, string> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const entries = Object.entries(value);
+  if (entries.some(([, item]) => typeof item !== "string")) return undefined;
+  return Object.fromEntries(entries) as Record<string, string>;
+}
+
+function recordValue(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+async function fetchProviderConfig(
+  provider: string,
+  relayUrl: string,
+  token: string | undefined,
+  key: string,
+  retry?: Partial<StartupFetchDeps>,
+): Promise<{ config: LoadedProviderConfig; version: number } | null> {
+  const url = new URL(`/api/settings/provider-config/${encodeURIComponent(key)}`, relayUrl);
+  const { response: res, body } = await fetchStartupConfig(url, token, retry ? RUNNER_CONFIG_RETRY_TIMEOUT_MS : 0, retry);
+  if (res.status === 404) return null;
+  if (!res.ok) throw new Error(body?.error ? `${res.status}: ${body.error}` : `HTTP ${res.status}`);
+  if (!isRecord(body) || !Number.isSafeInteger(body.version) || body.version! < 0
+    || !isRecord(body.value) || !stringValue(body.value.command)) {
+    throw new Error(`invalid central provider config response for ${key}`);
+  }
+  // Version zero is the hub's resolved default, not a failed config read (#3320).
+  return { config: providerConfigFromValue(provider, body.value, `config:provider-config/${key}`), version: body.version! };
+}
+
+function providerConfigFromValue(provider: string, value: unknown, path: string): LoadedProviderConfig {
+  const raw = recordValue(value);
+  const defaults = defaultProviderConfig(provider);
+  return {
+    path,
+    command: stringValue(raw.command) ?? defaults.command,
+    defaultArgs: stringArray(raw.defaultArgs) ?? defaults.defaultArgs,
+    env: stringRecord(raw.env) ?? defaults.env,
+    pluginDirs: stringArray(raw.pluginDirs) ?? defaults.pluginDirs,
+    globalInstructionFiles: stringArray(raw.globalInstructionFiles) ?? defaults.globalInstructionFiles,
+    defaultCapabilities: stringArray(raw.defaultCapabilities) ?? defaults.defaultCapabilities,
+    defaultApprovalMode: stringValue(raw.defaultApprovalMode) ?? defaults.defaultApprovalMode,
+    defaultTags: stringArray(raw.defaultTags) ?? defaults.defaultTags,
+    chatCaptureMode: enumValue(raw.chatCaptureMode, ["final", "full"]) ?? defaults.chatCaptureMode,
+    reasoningCapture: booleanValue(raw.reasoningCapture) ?? defaults.reasoningCapture,
+    // #2539 — an invalid value falls back to absent, which the steer policy resolves through
+    // the owning adapter's default.
+    activeTurnMessageDelivery: enumValue(raw.activeTurnMessageDelivery, [...ACTIVE_TURN_MESSAGE_DELIVERY_VALUES]),
+    headless: {
+      tmuxPrefix: stringValue(recordValue(raw.headless).tmuxPrefix) ?? defaults.headless.tmuxPrefix,
+      shutdownTimeoutMs: positiveInteger(recordValue(raw.headless).shutdownTimeoutMs) ?? defaults.headless.shutdownTimeoutMs,
+    },
+  };
+}

package/src/context-boundary.ts

@@ -0,0 +1,101 @@
+import { errMessage } from "@humwick/sdk";
+import type { ProviderStatusUpdate } from "./adapter";
+
+/**
+ * #3398 — Relay lists the agent's reads when a provider context resets. A reset fact goes out only after
+ * every delivery settlement started before it, so each mark-read the old context started has committed or
+ * failed by then; a failed one leaves its message unread.
+ */
+export class DeliverySettlements {
+  private readonly unsettled = new Set<Promise<void>>();
+
+  track(work: Promise<unknown>): void {
+    const settled: Promise<void> = work.then(() => undefined, () => undefined).finally(() => this.unsettled.delete(settled));
+    this.unsettled.add(settled);
+  }
+
+  /** Resolves once every settlement tracked so far has committed or failed. */
+  settled(): Promise<void> {
+    return Promise.all([...this.unsettled]).then(() => undefined);
+  }
+}
+
+export type ContextResetKind = "compact" | "clear";
+
+/** A boundary command that gave up before its destructive input reached the provider (#3441). */
+export class ContextSubmitAborted extends Error {}
+
+export interface ContextResetFact {
+  resetId: string;
+  kind: ContextResetKind;
+  observedAt: number;
+  /** The boundary command whose destructive input this reset settled, on the provider's evidence. */
+  commandId?: string;
+}
+
+/**
+ * #3398 (docs/design/self-resume-carry.md) — one reset fact per genuine provider reset, waited for or not.
+ * Submitted destructive inputs stay in order until provider evidence settles one: a manual reset settles
+ * the oldest of its kind, an automatic one none. A timed-out command keeps input the provider holds.
+ */
+/** How long a reset the adapter confirmed may still be observed as its provider status (#3698). */
+export const CONFIRMED_RESET_OBSERVE_WINDOW_MS = 60_000;
+
+export class ContextResetReporter {
+  private readonly submitted: Array<{ commandId: string; kind: ContextResetKind }> = [];
+  /** #3698 — confirmed by the adapter before its provider status arrived: that status is the SAME reset. */
+  private readonly confirmedUnobserved: Array<{ commandId: string; kind: ContextResetKind; at: number }> = [];
+
+  /** `onUncommandedReset` runs at observation for a reset no boundary command caused (operator `/clear`, auto-compaction). */
+  constructor(private readonly settlements: DeliverySettlements, private readonly send: (fact: ContextResetFact) => void, private readonly log: (message: string) => void, private readonly onUncommandedReset: () => void = () => {}) {}
+
+  /** The destructive input of boundary `commandId` is about to reach the provider. */
+  submitting(commandId: string, kind: ContextResetKind): void {
+    this.submitted.push({ commandId, kind });
+  }
+
+  /** Submitted, and no reset has settled it yet. */
+  unsettled(commandId: string): boolean {
+    return this.submitted.some((entry) => entry.commandId === commandId);
+  }
+
+  /** The adapter itself confirmed boundary `commandId`'s reset (a clear that rotated the session). */
+  confirmed(kind: ContextResetKind, commandId: string): void {
+    const index = this.submitted.findIndex((entry) => entry.commandId === commandId);
+    const at = Date.now();
+    if (index >= 0) {
+      this.submitted.splice(index, 1);
+      this.confirmedUnobserved.push({ commandId, kind, at });
+    }
+    this.report({ resetId: `${kind}:${commandId}`, kind, observedAt: at, commandId });
+  }
+
+  /** Reports `update` when it is a provider reset: the `compacted` / `context-cleared` timeline. */
+  observeStatus(update: ProviderStatusUpdate): void {
+    if (typeof update === "string") return;
+    const kind = update.timeline?.status === "compacted" ? "compact" : update.timeline?.status === "context-cleared" ? "clear" : undefined;
+    if (!kind) return;
+    const observedAt = typeof update.timeline?.timestamp === "number" ? update.timeline.timestamp : Date.now();
+    // A clear is always the slash command; a compaction is ours only on the provider's manual trigger.
+    const manual = kind === "clear" || update.metadata?.compactTrigger === "manual";
+    const settled = manual ? this.settleObserved(kind, observedAt) : undefined;
+    if (!settled) this.onUncommandedReset();
+    this.report({ resetId: settled ? `${kind}:${settled}` : crypto.randomUUID(), kind, observedAt, ...(settled ? { commandId: settled } : {}) });
+  }
+
+  /** The boundary command a manual reset settles: the oldest submitted one of its kind, else one
+   *  the adapter already confirmed (same reset id, so the server records it once). */
+  private settleObserved(kind: ContextResetKind, observedAt: number): string | undefined {
+    const index = this.submitted.findIndex((entry) => entry.kind === kind);
+    if (index >= 0) return this.submitted.splice(index, 1)[0]!.commandId;
+    for (let i = this.confirmedUnobserved.length - 1; i >= 0; i -= 1) {
+      if (observedAt - this.confirmedUnobserved[i]!.at > CONFIRMED_RESET_OBSERVE_WINDOW_MS) this.confirmedUnobserved.splice(i, 1);
+    }
+    const confirmed = this.confirmedUnobserved.findIndex((entry) => entry.kind === kind);
+    return confirmed >= 0 ? this.confirmedUnobserved.splice(confirmed, 1)[0]!.commandId : undefined;
+  }
+
+  private report(fact: ContextResetFact): void {
+    void this.settlements.settled().then(() => this.send(fact)).catch((error) => this.log(`context reset fact not queued: ${errMessage(error)}`));
+  }
+}