@openscout/scout 0.2.98 → 0.2.105

package/dist/statusline.mjs

@@ -6,55 +6,1034 @@ import { spawn } from "child_process";
 
 // ../runtime/src/claude-statusline.ts
 import { appendFile, mkdir, readFile, writeFile } from "fs/promises";
-import { basename, dirname, join as join2 } from "path";
+import { basename, dirname, join as join3 } from "path";
 
-// ../runtime/src/support-paths.ts
+// ../runtime/src/system-probes/scoutd-client.ts
+import { existsSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
+import { Socket } from "net";
+
+// ../runtime/src/system-probes/registry.ts
+var DEFAULT_MIN_MAX_STALE_MS = 2 * 60000;
+var PROBE_RUN_OUTPUT = Symbol("openscout.probeRunOutput");
+class ProbeBackendError extends Error {
+  backend;
+  fallbackSince;
+  fallbackReason;
+  code;
+  timedOut;
+  constructor(message, metadata, cause) {
+    super(message);
+    this.name = "ProbeBackendError";
+    this.backend = metadata.backend;
+    this.fallbackSince = metadata.fallbackSince;
+    this.fallbackReason = metadata.fallbackReason;
+    const details = probeErrorDetails(cause);
+    if (details.code) {
+      this.code = details.code;
+    }
+    if (details.timedOut !== undefined) {
+      this.timedOut = details.timedOut;
+    }
+  }
+}
+function probeRunOutput(value, metadata) {
+  return {
+    [PROBE_RUN_OUTPUT]: true,
+    value,
+    ...metadata
+  };
+}
+function isProbeRunOutput(value) {
+  return typeof value === "object" && value !== null && value[PROBE_RUN_OUTPUT] === true;
+}
+function backendMetadataFromError(error) {
+  if (error instanceof ProbeBackendError) {
+    return {
+      backend: error.backend,
+      fallbackSince: error.fallbackSince,
+      fallbackReason: error.fallbackReason
+    };
+  }
+  if (typeof error === "object" && error !== null) {
+    const record = error;
+    if (record.backend === "local" || record.backend === "scoutd" || record.backend === "local-fallback") {
+      return {
+        backend: record.backend,
+        fallbackSince: typeof record.fallbackSince === "number" ? record.fallbackSince : undefined,
+        fallbackReason: typeof record.fallbackReason === "string" ? record.fallbackReason : undefined
+      };
+    }
+  }
+  return null;
+}
+function probeErrorDetails(error) {
+  if (typeof error !== "object" || error === null) {
+    return {};
+  }
+  const record = error;
+  const code = typeof record.code === "string" && record.code.trim() ? record.code.trim() : undefined;
+  const timedOut = record.timedOut === true || code === "timeout" ? true : record.timedOut === false ? false : undefined;
+  return { code, timedOut };
+}
+function assertProbeSpec(spec) {
+  if (!spec.id.trim()) {
+    throw new Error("Probe id is required");
+  }
+  if (!Number.isFinite(spec.ttlMs) || spec.ttlMs <= 0) {
+    throw new Error(`Probe ${spec.id} must declare a positive ttlMs`);
+  }
+  if (!Number.isFinite(spec.timeoutMs) || spec.timeoutMs <= 0) {
+    throw new Error(`Probe ${spec.id} must declare a positive timeoutMs`);
+  }
+  if (spec.maxStaleMs !== undefined && (!Number.isFinite(spec.maxStaleMs) || spec.maxStaleMs <= 0)) {
+    throw new Error(`Probe ${spec.id} maxStaleMs must be positive when set`);
+  }
+}
+function maxStaleMsFor(spec) {
+  return spec.maxStaleMs ?? Math.max(DEFAULT_MIN_MAX_STALE_MS, spec.ttlMs * 10);
+}
+function failureBackoffMs(consecutiveFailures) {
+  if (consecutiveFailures <= 0) {
+    return 0;
+  }
+  return Math.min(30000, 1000 * 2 ** Math.min(consecutiveFailures - 1, 5));
+}
+function probeErrorFromUnknown(error, at, timedOut = false) {
+  if (typeof error === "object" && error !== null) {
+    const record = error;
+    const code = typeof record.code === "string" && record.code.trim() ? record.code.trim() : timedOut ? "timeout" : typeof record.name === "string" && record.name.trim() ? record.name.trim() : "error";
+    const message = typeof record.message === "string" && record.message.trim() ? record.message : String(error);
+    return { code, message, at, ...timedOut ? { timedOut: true } : {} };
+  }
+  return {
+    code: timedOut ? "timeout" : "error",
+    message: String(error),
+    at,
+    ...timedOut ? { timedOut: true } : {}
+  };
+}
+function timeoutError(probeId, timeoutMs) {
+  return {
+    code: "timeout",
+    message: `Probe ${probeId} timed out after ${timeoutMs}ms`,
+    at: Date.now(),
+    timedOut: true
+  };
+}
+function staleTooLongError(probeId, ageMs, maxStaleMs) {
+  return {
+    code: "max_stale_exceeded",
+    message: `Probe ${probeId} last good snapshot is ${ageMs}ms old, exceeding maxStaleMs ${maxStaleMs}`,
+    at: Date.now()
+  };
+}
+function isFreshEnough(state, maxAgeMs) {
+  if (state.at === null || state.invalidated) {
+    return false;
+  }
+  return Date.now() - state.at <= maxAgeMs;
+}
+function logBackendTransition(input) {
+  if (input.from === input.to) {
+    return;
+  }
+  const keySuffix = input.key === undefined ? "" : ` key=${JSON.stringify(input.key)}`;
+  const reasonSuffix = input.reason ? ` (${input.reason})` : "";
+  console.warn(`[openscout] system probe ${input.id}${keySuffix} backend ${input.from} -> ${input.to}${reasonSuffix}`);
+}
+
+class ProbeInstance {
+  spec;
+  key;
+  runProbe;
+  scheduleRun;
+  state = {
+    value: null,
+    at: null,
+    error: null,
+    consecutiveFailures: 0,
+    inFlight: null,
+    invalidated: false,
+    invalidationReason: null,
+    invalidationSerial: 0,
+    nextRetryAt: 0,
+    backend: "local",
+    fallbackSince: null,
+    fallbackReason: null
+  };
+  metricState;
+  lastAccessAt = Date.now();
+  constructor(options) {
+    this.spec = options.spec;
+    this.key = options.key;
+    this.runProbe = options.run;
+    this.scheduleRun = options.scheduleRun ?? ((task) => task());
+    this.metricState = {
+      id: options.spec.id,
+      ...options.key !== undefined ? { key: options.key } : {},
+      backend: "local",
+      runCount: 0,
+      failureCount: 0,
+      timeoutCount: 0,
+      staleServedCount: 0,
+      lastRunAt: null,
+      lastDurationMs: null,
+      lastSuccessAt: null
+    };
+  }
+  read() {
+    this.touch();
+    if (this.shouldRefreshForRead(Date.now())) {
+      this.ensureRefresh(false, this.spec.ttlMs);
+    }
+    const snap = this.snapshot();
+    if (snap.status === "stale" || snap.status === "failed" && snap.at !== null) {
+      this.metricState.staleServedCount += 1;
+    }
+    return snap;
+  }
+  async fresh(options = {}) {
+    this.touch();
+    const maxAgeMs = options.maxAgeMs ?? this.spec.ttlMs;
+    for (let attempt = 0;attempt < 3; attempt += 1) {
+      if (isFreshEnough(this.state, maxAgeMs)) {
+        return this.snapshot();
+      }
+      await this.ensureRefresh(true, maxAgeMs);
+      if (!this.state.invalidated) {
+        return this.snapshot();
+      }
+    }
+    return this.snapshot();
+  }
+  snapshot() {
+    const now = Date.now();
+    const ageMs = this.state.at === null ? null : Math.max(0, now - this.state.at);
+    const maxStaleMs = maxStaleMsFor(this.spec);
+    const exceededMaxStale = ageMs !== null && ageMs > maxStaleMs;
+    const fresh = ageMs !== null && !this.state.invalidated && ageMs <= this.spec.ttlMs;
+    const status = this.state.at === null ? this.state.error ? "failed" : "empty" : exceededMaxStale ? "failed" : fresh ? "fresh" : "stale";
+    const error = exceededMaxStale ? this.state.error ?? staleTooLongError(this.spec.id, ageMs ?? 0, maxStaleMs) : this.state.error;
+    return {
+      id: this.spec.id,
+      ...this.key !== undefined ? { key: this.key } : {},
+      value: status === "failed" && exceededMaxStale ? null : this.state.value,
+      at: this.state.at,
+      ageMs,
+      stale: status === "stale" || status === "failed" && this.state.at !== null,
+      refreshing: this.state.inFlight !== null,
+      status,
+      error,
+      consecutiveFailures: this.state.consecutiveFailures,
+      backend: this.state.backend,
+      ...this.state.fallbackSince !== null ? { fallbackSince: this.state.fallbackSince } : {},
+      ...this.state.fallbackReason !== null ? { fallbackReason: this.state.fallbackReason } : {}
+    };
+  }
+  invalidate(reason) {
+    this.touch();
+    this.state.invalidated = true;
+    this.state.invalidationReason = reason ?? null;
+    this.state.invalidationSerial += 1;
+    this.state.nextRetryAt = 0;
+  }
+  metrics() {
+    return {
+      ...this.metricState,
+      consecutiveFailures: this.state.consecutiveFailures,
+      inFlight: this.state.inFlight !== null,
+      ...this.state.fallbackSince !== null ? { fallbackSince: this.state.fallbackSince } : {},
+      ...this.state.fallbackReason !== null ? { fallbackReason: this.state.fallbackReason } : {}
+    };
+  }
+  isRefreshing() {
+    return this.state.inFlight !== null;
+  }
+  touch() {
+    this.lastAccessAt = Date.now();
+  }
+  shouldRefreshForRead(now) {
+    if (this.state.inFlight !== null) {
+      return false;
+    }
+    if (this.state.nextRetryAt > now) {
+      return false;
+    }
+    if (this.state.at === null) {
+      return true;
+    }
+    if (this.state.invalidated) {
+      return true;
+    }
+    return now - this.state.at > this.spec.ttlMs;
+  }
+  ensureRefresh(force, maxAgeMs) {
+    if (this.state.inFlight) {
+      return this.state.inFlight;
+    }
+    const now = Date.now();
+    if (!force && this.state.nextRetryAt > now) {
+      return Promise.resolve();
+    }
+    const inFlight = this.scheduleRun(() => this.executeRun(maxAgeMs)).finally(() => {
+      if (this.state.inFlight === inFlight) {
+        this.state.inFlight = null;
+      }
+    });
+    this.state.inFlight = inFlight;
+    return inFlight;
+  }
+  async executeRun(maxAgeMs) {
+    const startedAt = Date.now();
+    const previousBackend = this.state.backend;
+    const invalidationSerialAtStart = this.state.invalidationSerial;
+    const controller = new AbortController;
+    let timeout = null;
+    this.metricState.runCount += 1;
+    this.metricState.lastRunAt = startedAt;
+    const ctx = {
+      probeId: this.spec.id,
+      ...this.key !== undefined ? { key: this.key } : {},
+      signal: controller.signal,
+      timeoutMs: this.spec.timeoutMs,
+      maxAgeMs,
+      startedAt
+    };
+    const timeoutProbeError = timeoutError(this.spec.id, this.spec.timeoutMs);
+    const runPromise = this.runProbe(ctx);
+    runPromise.catch(() => {
+      return;
+    });
+    try {
+      const result = await new Promise((resolve, reject) => {
+        timeout = setTimeout(() => {
+          controller.abort(timeoutProbeError);
+          reject(timeoutProbeError);
+        }, this.spec.timeoutMs);
+        runPromise.then(resolve, reject);
+      });
+      const output = isProbeRunOutput(result) ? result : probeRunOutput(result, { backend: "local" });
+      this.state.value = output.value;
+      this.state.at = output.generatedAt ?? Date.now();
+      this.state.error = null;
+      this.state.consecutiveFailures = 0;
+      if (this.state.invalidationSerial === invalidationSerialAtStart) {
+        this.state.invalidated = false;
+        this.state.invalidationReason = null;
+      }
+      this.state.nextRetryAt = 0;
+      this.state.backend = output.backend;
+      this.state.fallbackSince = output.fallbackSince ?? null;
+      this.state.fallbackReason = output.fallbackReason ?? null;
+      this.metricState.backend = output.backend;
+      this.metricState.lastSuccessAt = this.state.at;
+      logBackendTransition({
+        id: this.spec.id,
+        key: this.key,
+        from: previousBackend,
+        to: output.backend,
+        reason: output.fallbackReason
+      });
+    } catch (error) {
+      const timedOut = error === timeoutProbeError || typeof error === "object" && error !== null && (error.code === "timeout" || error.timedOut === true);
+      const at = Date.now();
+      this.state.error = error === timeoutProbeError ? timeoutProbeError : probeErrorFromUnknown(error, at, timedOut);
+      this.state.consecutiveFailures += 1;
+      this.state.nextRetryAt = at + failureBackoffMs(this.state.consecutiveFailures);
+      const backendMetadata = backendMetadataFromError(error);
+      if (backendMetadata) {
+        this.state.backend = backendMetadata.backend;
+        this.state.fallbackSince = backendMetadata.fallbackSince ?? null;
+        this.state.fallbackReason = backendMetadata.fallbackReason ?? null;
+        this.metricState.backend = backendMetadata.backend;
+        logBackendTransition({
+          id: this.spec.id,
+          key: this.key,
+          from: previousBackend,
+          to: backendMetadata.backend,
+          reason: backendMetadata.fallbackReason
+        });
+      }
+      this.metricState.failureCount += 1;
+      if (this.state.error.timedOut || this.state.error.code === "timeout") {
+        this.metricState.timeoutCount += 1;
+      }
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      this.metricState.lastDurationMs = Date.now() - startedAt;
+    }
+  }
+}
+
+class FamilyLimiter {
+  maxConcurrent;
+  active = 0;
+  queue = [];
+  constructor(maxConcurrent) {
+    this.maxConcurrent = maxConcurrent;
+  }
+  queued() {
+    return this.queue.length;
+  }
+  async run(task) {
+    if (this.active >= this.maxConcurrent) {
+      await new Promise((resolve) => this.queue.push(resolve));
+    }
+    this.active += 1;
+    try {
+      return await task();
+    } finally {
+      this.active -= 1;
+      const next = this.queue.shift();
+      if (next) {
+        next();
+      }
+    }
+  }
+}
+
+class ProbeFamily {
+  spec;
+  entries = new Map;
+  limiter;
+  constructor(spec) {
+    this.spec = spec;
+    assertProbeSpec(spec);
+    if (!Number.isInteger(spec.maxKeys) || spec.maxKeys <= 0) {
+      throw new Error(`Probe family ${spec.id} must declare a positive maxKeys`);
+    }
+    if (!Number.isFinite(spec.idleKeyTtlMs) || spec.idleKeyTtlMs <= 0) {
+      throw new Error(`Probe family ${spec.id} must declare a positive idleKeyTtlMs`);
+    }
+    if (!Number.isInteger(spec.maxConcurrentKeys) || spec.maxConcurrentKeys <= 0) {
+      throw new Error(`Probe family ${spec.id} must declare a positive maxConcurrentKeys`);
+    }
+    this.limiter = new FamilyLimiter(spec.maxConcurrentKeys);
+  }
+  for(rawKey) {
+    const key = this.normalize(rawKey);
+    this.cleanupIdle(Date.now());
+    let entry = this.entries.get(key);
+    if (!entry) {
+      entry = new ProbeInstance({
+        spec: this.spec,
+        key,
+        run: (ctx) => this.spec.run(key, ctx),
+        scheduleRun: (task) => this.limiter.run(task)
+      });
+      this.entries.set(key, entry);
+    }
+    entry.lastAccessAt = Date.now();
+    this.evictLruIfNeeded();
+    return entry;
+  }
+  snapshot(key) {
+    return this.for(key).snapshot();
+  }
+  invalidate(key, reason) {
+    this.for(key).invalidate(reason);
+  }
+  metrics() {
+    this.cleanupIdle(Date.now());
+    return {
+      id: this.spec.id,
+      keyCount: this.entries.size,
+      maxKeys: this.spec.maxKeys,
+      activeRuns: this.limiter.active,
+      queuedRuns: this.limiter.queued(),
+      keys: Array.from(this.entries.values(), (entry) => entry.metrics())
+    };
+  }
+  keys() {
+    this.cleanupIdle(Date.now());
+    return Array.from(this.entries.keys());
+  }
+  normalize(rawKey) {
+    const key = this.spec.normalizeKey(rawKey).trim();
+    if (!key) {
+      throw new Error(`Probe family ${this.spec.id} normalized an empty key`);
+    }
+    return key;
+  }
+  cleanupIdle(now) {
+    for (const [key, entry] of this.entries) {
+      if (!entry.isRefreshing() && now - entry.lastAccessAt > this.spec.idleKeyTtlMs) {
+        this.entries.delete(key);
+      }
+    }
+  }
+  evictLruIfNeeded() {
+    while (this.entries.size > this.spec.maxKeys) {
+      let oldestKey = null;
+      let oldestAccess = Number.POSITIVE_INFINITY;
+      for (const [key, entry] of this.entries) {
+        if (entry.isRefreshing()) {
+          continue;
+        }
+        if (entry.lastAccessAt < oldestAccess) {
+          oldestAccess = entry.lastAccessAt;
+          oldestKey = key;
+        }
+      }
+      if (!oldestKey) {
+        return;
+      }
+      this.entries.delete(oldestKey);
+    }
+  }
+}
+
+// ../runtime/src/system-probes/scout-host-catalog.ts
+var SCOUT_HOST_PROBE_SCHEMA_VERSIONS = {
+  "tailscale.status": 1,
+  "git.buildInfo": 1,
+  "git.revParse": 1,
+  "git.diffShortstat": 1,
+  "git.statusPorcelain": 1,
+  "git.mergeBase": 1,
+  "git.logLastCommitUnix": 1,
+  "git.worktreeListPorcelain": 1,
+  "tmux.sessions": 2,
+  "tmux.panes": 1,
+  "zellij.sessions": 1,
+  "ps.runtime": 1,
+  "ps.discovery": 1,
+  "ps.cwd": 1,
+  "net.listeners": 1,
+  "repo.scan": 1,
+  "repo.diff": 1
+};
+var SCOUT_HOST_EXEC_VERB_SCHEMA_VERSIONS = {
+  "tmux.sendKeys": 1,
+  "tmux.sendKeysLiteral": 1,
+  "tmux.loadBuffer": 1,
+  "tmux.pasteBuffer": 1,
+  "tmux.deleteBuffer": 1,
+  "tmux.killSession": 1,
+  "tmux.newSession": 1,
+  "tmux.detachClient": 1,
+  "tailscale.cert": 1,
+  "reveal.open": 1
+};
+function expectedScoutHostProbeSchemaVersion(probeId) {
+  return Object.hasOwn(SCOUT_HOST_PROBE_SCHEMA_VERSIONS, probeId) ? SCOUT_HOST_PROBE_SCHEMA_VERSIONS[probeId] : null;
+}
+function expectedScoutHostExecVerbSchemaVersion(verb) {
+  return Object.hasOwn(SCOUT_HOST_EXEC_VERB_SCHEMA_VERSIONS, verb) ? SCOUT_HOST_EXEC_VERB_SCHEMA_VERSIONS[verb] : null;
+}
+
+// ../runtime/src/system-probes/scoutd-client.ts
+var CAPABILITIES_SCHEMA = "openscout.probe.capabilities/v1";
+var REQUEST_SCHEMA = "openscout.probe.request/v1";
+var SNAPSHOT_SCHEMA = "openscout.probe.snapshot/v1";
+var ERROR_SCHEMA = "openscout.probe.error/v1";
+var EXEC_REQUEST_SCHEMA = "openscout.exec.request/v1";
+var EXEC_RESPONSE_SCHEMA = "openscout.exec.response/v1";
+var CAPABILITY_RECHECK_MS = 1e4;
+var SOCKET_TIMEOUT_MS = 900;
+var MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+function readString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function readNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fallbackMessage(error) {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message;
+  }
+  return String(error);
+}
+
+class ScoutdExecResponseError extends Error {
+  code;
+  timedOut;
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "ScoutdExecResponseError";
+    this.code = options.code ?? "exec_error";
+    this.timedOut = options.timedOut ?? false;
+  }
+}
+
+class ScoutdProbeResponseError extends Error {
+  code;
+  timedOut;
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "ScoutdProbeResponseError";
+    this.code = options.code ?? "probe_error";
+    this.timedOut = options.timedOut ?? false;
+  }
+}
+function resolveScoutdProbesSocketPath(env = process.env) {
+  const explicit = env.OPENSCOUT_PROBES_SOCKET?.trim();
+  if (explicit) {
+    return explicit;
+  }
+  const openScoutHome = env.OPENSCOUT_HOME?.trim() || join(homedir(), ".openscout");
+  return join(openScoutHome, "run", "scoutd-probes.sock");
+}
+
+class ScoutdProbeClient {
+  env;
+  capabilities = null;
+  lastCapabilityCheckAt = null;
+  lastError = null;
+  daemonObserved = false;
+  fallbackByProbe = new Map;
+  fallbackByExec = new Map;
+  constructor(env = process.env) {
+    this.env = env;
+  }
+  async requestProbe(input) {
+    const socketPath = resolveScoutdProbesSocketPath(this.env);
+    const socketTimeoutMs = probeSocketTimeoutMs(input.timeoutMs);
+    const socketExists = existsSync(socketPath);
+    if (!socketExists) {
+      this.capabilities = null;
+      this.lastError = null;
+      return this.daemonObserved ? this.fallback(input.probeId, input.key, `probe socket is missing: ${socketPath}`) : { state: "local" };
+    }
+    this.daemonObserved = true;
+    const capabilities = await this.ensureCapabilities(socketPath, socketTimeoutMs);
+    if (!capabilities) {
+      return this.fallback(input.probeId, input.key, this.lastError ?? "probe capabilities unavailable");
+    }
+    const capability = capabilities.families.get(input.probeId);
+    if (!capability) {
+      return this.fallback(input.probeId, input.key, `scoutd does not serve ${input.probeId}`);
+    }
+    const expectedSchemaVersion = expectedScoutHostProbeSchemaVersion(input.probeId);
+    if (expectedSchemaVersion === null) {
+      return this.fallback(input.probeId, input.key, `client has no compiled schema version for ${input.probeId}`);
+    }
+    if (capability.schemaVersion !== expectedSchemaVersion) {
+      return this.fallback(input.probeId, input.key, `scoutd serves ${input.probeId} schema v${capability.schemaVersion}, expected v${expectedSchemaVersion}`);
+    }
+    try {
+      const response = await requestJson(socketPath, {
+        schema: REQUEST_SCHEMA,
+        schemaVersion: expectedSchemaVersion,
+        probeId: input.probeId,
+        key: input.key ?? null,
+        maxAgeMs: input.maxAgeMs,
+        opTimeoutMs: requestOpTimeoutMs(input.timeoutMs)
+      }, { timeoutMs: socketTimeoutMs });
+      if (!isRecord(response) || response.schema !== SNAPSHOT_SCHEMA) {
+        throw new Error("scoutd returned an invalid probe snapshot envelope");
+      }
+      if (response.error) {
+        const error = isRecord(response.error) ? response.error : {};
+        const code = readString(error.code) ?? "probe_error";
+        const message = readString(error.message) ?? code;
+        const timedOut = error.timedOut === true || error.timed_out === true;
+        throw new ScoutdProbeResponseError(message, { code, timedOut });
+      }
+      this.fallbackByProbe.delete(fallbackKey(input.probeId, input.key));
+      this.lastError = null;
+      return {
+        state: "scoutd",
+        value: response.value,
+        generatedAt: readNumber(response.generatedAt) ?? Date.now(),
+        daemonVersion: readString(response.daemonVersion) ?? capabilities.daemonVersion
+      };
+    } catch (error) {
+      if (!(error instanceof ScoutdProbeResponseError)) {
+        this.capabilities = null;
+        this.lastCapabilityCheckAt = null;
+      }
+      this.lastError = fallbackMessage(error);
+      return this.fallback(input.probeId, input.key, this.lastError);
+    }
+  }
+  async requestExecVerb(input) {
+    const socketPath = resolveScoutdProbesSocketPath(this.env);
+    const socketTimeoutMs = execSocketTimeoutMs(input.args);
+    const socketExists = existsSync(socketPath);
+    if (!socketExists) {
+      this.capabilities = null;
+      this.lastError = null;
+      return this.daemonObserved ? this.execFallback(input.verb, `probe socket is missing: ${socketPath}`) : { state: "local" };
+    }
+    this.daemonObserved = true;
+    const capabilities = await this.ensureCapabilities(socketPath, socketTimeoutMs);
+    if (!capabilities) {
+      return this.execFallback(input.verb, this.lastError ?? "probe capabilities unavailable");
+    }
+    const capability = capabilities.verbs.get(input.verb);
+    if (!capability) {
+      return this.execFallback(input.verb, `scoutd does not serve ${input.verb}`);
+    }
+    const expectedSchemaVersion = expectedScoutHostExecVerbSchemaVersion(input.verb);
+    if (expectedSchemaVersion === null) {
+      return this.execFallback(input.verb, `client has no compiled schema version for ${input.verb}`);
+    }
+    if (capability.schemaVersion !== expectedSchemaVersion) {
+      return this.execFallback(input.verb, `scoutd serves ${input.verb} schema v${capability.schemaVersion}, expected v${expectedSchemaVersion}`);
+    }
+    try {
+      const response = await requestJson(socketPath, {
+        schema: EXEC_REQUEST_SCHEMA,
+        schemaVersion: expectedSchemaVersion,
+        verb: input.verb,
+        args: input.args
+      }, { timeoutMs: socketTimeoutMs });
+      if (!isRecord(response) || response.schema !== EXEC_RESPONSE_SCHEMA) {
+        throw new Error("scoutd returned an invalid exec response envelope");
+      }
+      if (!response.ok) {
+        const error = isRecord(response.error) ? response.error : {};
+        const code = readString(error.code) ?? "exec_error";
+        const message = readString(error.message) ?? code;
+        const timedOut = error.timedOut === true || error.timed_out === true;
+        throw new ScoutdExecResponseError(message, { code, timedOut });
+      }
+      this.fallbackByExec.delete(input.verb);
+      this.lastError = null;
+      return {
+        state: "scoutd",
+        value: response.value,
+        daemonVersion: readString(response.daemonVersion) ?? capabilities.daemonVersion
+      };
+    } catch (error) {
+      if (error instanceof ScoutdExecResponseError) {
+        throw error;
+      }
+      this.capabilities = null;
+      this.lastCapabilityCheckAt = null;
+      this.lastError = fallbackMessage(error);
+      return this.execFallback(input.verb, this.lastError);
+    }
+  }
+  diagnostics() {
+    const socketPath = resolveScoutdProbesSocketPath(this.env);
+    return {
+      socketPath,
+      socketExists: existsSync(socketPath),
+      daemonObserved: this.daemonObserved,
+      daemonVersion: this.capabilities?.daemonVersion ?? null,
+      supportedProbeIds: this.capabilities ? [...this.capabilities.families.keys()].sort() : [],
+      supportedExecVerbs: this.capabilities ? [...this.capabilities.verbs.keys()].sort() : [],
+      lastCapabilityCheckAt: this.lastCapabilityCheckAt,
+      lastError: this.lastError
+    };
+  }
+  resetForTests() {
+    this.capabilities = null;
+    this.lastCapabilityCheckAt = null;
+    this.lastError = null;
+    this.daemonObserved = false;
+    this.fallbackByProbe.clear();
+    this.fallbackByExec.clear();
+  }
+  async ensureCapabilities(socketPath, timeoutMs = SOCKET_TIMEOUT_MS) {
+    const now = Date.now();
+    if (this.capabilities && this.lastCapabilityCheckAt !== null && now - this.lastCapabilityCheckAt < CAPABILITY_RECHECK_MS) {
+      return this.capabilities;
+    }
+    this.lastCapabilityCheckAt = now;
+    try {
+      const response = await requestJson(socketPath, { schema: CAPABILITIES_SCHEMA }, { timeoutMs });
+      if (!isRecord(response) || response.schema !== CAPABILITIES_SCHEMA) {
+        throw new Error("scoutd returned an invalid capabilities envelope");
+      }
+      const daemonVersion = readString(response.daemonVersion) ?? "unknown";
+      const families = new Map;
+      if (Array.isArray(response.families)) {
+        for (const entry of response.families) {
+          if (!isRecord(entry))
+            continue;
+          const probeId = readString(entry.probeId);
+          const schemaVersion = readNumber(entry.schemaVersion);
+          const ttlMs = readNumber(entry.ttlMs);
+          if (probeId && schemaVersion !== null && ttlMs !== null) {
+            families.set(probeId, { probeId, schemaVersion, ttlMs });
+          }
+        }
+      }
+      const verbs = new Map;
+      if (Array.isArray(response.verbs)) {
+        for (const entry of response.verbs) {
+          if (!isRecord(entry))
+            continue;
+          const verb = readString(entry.verb);
+          const schemaVersion = readNumber(entry.schemaVersion);
+          if (verb && schemaVersion !== null) {
+            verbs.set(verb, { verb, schemaVersion });
+          }
+        }
+      }
+      this.capabilities = { daemonVersion, families, verbs };
+      this.daemonObserved = true;
+      this.lastError = null;
+      return this.capabilities;
+    } catch (error) {
+      this.capabilities = null;
+      this.lastError = fallbackMessage(error);
+      return null;
+    }
+  }
+  fallback(probeId, key, reason) {
+    const id = fallbackKey(probeId, key);
+    let state = this.fallbackByProbe.get(id);
+    if (!state || state.reason !== reason) {
+      state = { since: Date.now(), reason };
+      this.fallbackByProbe.set(id, state);
+    }
+    return {
+      state: "local",
+      fallbackSince: state.since,
+      fallbackReason: state.reason
+    };
+  }
+  execFallback(verb, reason) {
+    let state = this.fallbackByExec.get(verb);
+    if (!state || state.reason !== reason) {
+      state = { since: Date.now(), reason };
+      this.fallbackByExec.set(verb, state);
+    }
+    return {
+      state: "local",
+      fallbackSince: state.since,
+      fallbackReason: state.reason
+    };
+  }
+}
+function probeSocketTimeoutMs(timeoutMs) {
+  if (timeoutMs === undefined || !Number.isFinite(timeoutMs)) {
+    return SOCKET_TIMEOUT_MS;
+  }
+  return Math.max(SOCKET_TIMEOUT_MS, Math.min(Math.max(0, timeoutMs) + 1000, 31000));
+}
+function requestOpTimeoutMs(timeoutMs) {
+  if (timeoutMs === undefined || !Number.isFinite(timeoutMs)) {
+    return;
+  }
+  return Math.max(0, Math.floor(timeoutMs));
+}
+function execSocketTimeoutMs(args) {
+  const timeoutMs = typeof args.timeoutMs === "number" && Number.isFinite(args.timeoutMs) ? Math.max(0, args.timeoutMs) : 5000;
+  return Math.max(SOCKET_TIMEOUT_MS, Math.min(timeoutMs + 1000, 31000));
+}
+async function requestJson(socketPath, payload, options = {}) {
+  const bun = globalThis.Bun;
+  if (bun?.connect) {
+    return await requestJsonWithBun(bun.connect, socketPath, payload, options);
+  }
+  return await new Promise((resolve, reject) => {
+    const socket = new Socket;
+    let response = "";
+    let settled = false;
+    const finish = (error, value) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      socket.removeAllListeners();
+      socket.destroy();
+      if (error) {
+        reject(error);
+      } else {
+        resolve(value);
+      }
+    };
+    const timeoutMs = options.timeoutMs ?? SOCKET_TIMEOUT_MS;
+    const timer = setTimeout(() => {
+      finish(new Error(`scoutd probe socket timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    timer.unref?.();
+    const finishFromResponse = () => {
+      if (settled)
+        return;
+      try {
+        const parsed = JSON.parse(response);
+        if (isRecord(parsed) && parsed.schema === ERROR_SCHEMA) {
+          const error = isRecord(parsed.error) ? parsed.error : {};
+          const message = readString(error.message) ?? readString(error.code) ?? "scoutd probe request failed";
+          finish(new Error(message));
+          return;
+        }
+        finish(null, parsed);
+      } catch (error) {
+        finish(new Error(`scoutd probe response was not JSON: ${fallbackMessage(error)}`));
+      }
+    };
+    socket.setEncoding("utf8");
+    socket.on("connect", () => {
+      socket.write(`${JSON.stringify(payload)}
+`);
+    });
+    socket.on("data", (chunk) => {
+      response += chunk;
+      if (Buffer.byteLength(response, "utf8") > MAX_RESPONSE_BYTES) {
+        finish(new Error("scoutd probe response exceeded output limit"));
+      }
+    });
+    socket.on("error", (error) => finish(error));
+    socket.on("end", finishFromResponse);
+    socket.on("close", () => {
+      if (!settled) {
+        if (response.length === 0) {
+          finish(new Error("scoutd probe socket closed without a response"));
+        } else {
+          finishFromResponse();
+        }
+      }
+    });
+    socket.connect(socketPath);
+  });
+}
+async function requestJsonWithBun(connect, socketPath, payload, options = {}) {
+  return await new Promise((resolve, reject) => {
+    let response = "";
+    let settled = false;
+    let socketRef = null;
+    const decoder = new TextDecoder;
+    const finish = (error, value) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        socketRef?.end?.();
+      } catch {}
+      if (error) {
+        reject(error);
+      } else {
+        resolve(value);
+      }
+    };
+    const finishFromResponse = () => {
+      if (settled)
+        return;
+      try {
+        const parsed = JSON.parse(response);
+        if (isRecord(parsed) && parsed.schema === ERROR_SCHEMA) {
+          const error = isRecord(parsed.error) ? parsed.error : {};
+          const message = readString(error.message) ?? readString(error.code) ?? "scoutd probe request failed";
+          finish(new Error(message));
+          return;
+        }
+        finish(null, parsed);
+      } catch (error) {
+        finish(new Error(`scoutd probe response was not JSON: ${fallbackMessage(error)}`));
+      }
+    };
+    const timeoutMs = options.timeoutMs ?? SOCKET_TIMEOUT_MS;
+    const timer = setTimeout(() => {
+      finish(new Error(`scoutd probe socket timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    timer.unref?.();
+    connect({
+      unix: socketPath,
+      socket: {
+        open(socket) {
+          socketRef = socket;
+          socket.write(`${JSON.stringify(payload)}
+`);
+        },
+        data(_socket, data) {
+          response += decoder.decode(data, { stream: true });
+          if (Buffer.byteLength(response, "utf8") > MAX_RESPONSE_BYTES) {
+            finish(new Error("scoutd probe response exceeded output limit"));
+          }
+        },
+        close() {
+          if (response.length === 0) {
+            finish(new Error("scoutd probe socket closed without a response"));
+          } else {
+            response += decoder.decode();
+            finishFromResponse();
+          }
+        },
+        error(_socket, error) {
+          finish(error);
+        }
+      }
+    }).then((socket) => {
+      socketRef = socket;
+    }, (error) => {
+      finish(error instanceof Error ? error : new Error(String(error)));
+    });
+  });
+}
+function fallbackKey(probeId, key) {
+  return `${probeId}\x00${key ?? ""}`;
+}
+
+// ../runtime/src/system-probes/exec.ts
+var DEFAULT_STDOUT_CAP_BYTES = 1024 * 1024;
+var DEFAULT_STDERR_CAP_BYTES = 128 * 1024;
+var EXEC_SYSTEM_TRANSPORT_METADATA = Symbol.for("openscout.execSystem.transport");
+
+// ../runtime/src/claude-session-records.ts
+var TRANSCRIPT_TAIL_BYTES = 256 * 1024;
+
+// ../runtime/src/support-paths.ts
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
 var OPENSCOUT_RPC_CUTOVER_MARKER = "rpc-runtime-cutover-v1";
 function resolveOpenScoutSupportPaths() {
-  const home = homedir();
-  const supportDirectory = process.env.OPENSCOUT_SUPPORT_DIRECTORY ?? join(home, "Library", "Application Support", "OpenScout");
-  const logsDirectory = join(supportDirectory, "logs");
-  const runtimeDirectory = join(supportDirectory, "runtime");
-  const catalogDirectory = join(supportDirectory, "catalog");
-  const controlHome = process.env.OPENSCOUT_CONTROL_HOME ?? join(home, ".openscout", "control-plane");
-  const knowledgeDirectory = join(controlHome, "knowledge");
+  const home = homedir2();
+  const supportDirectory = process.env.OPENSCOUT_SUPPORT_DIRECTORY ?? join2(home, "Library", "Application Support", "OpenScout");
+  const logsDirectory = join2(supportDirectory, "logs");
+  const runtimeDirectory = join2(supportDirectory, "runtime");
+  const catalogDirectory = join2(supportDirectory, "catalog");
+  const controlHome = process.env.OPENSCOUT_CONTROL_HOME ?? join2(home, ".openscout", "control-plane");
+  const knowledgeDirectory = join2(controlHome, "knowledge");
   return {
     supportDirectory,
     logsDirectory,
-    appLogsDirectory: join(logsDirectory, "app"),
-    brokerLogsDirectory: join(logsDirectory, "broker"),
+    appLogsDirectory: join2(logsDirectory, "app"),
+    brokerLogsDirectory: join2(logsDirectory, "broker"),
     runtimeDirectory,
     catalogDirectory,
-    relayAgentsDirectory: join(runtimeDirectory, "agents"),
-    settingsPath: join(supportDirectory, "settings.json"),
-    harnessCatalogPath: join(catalogDirectory, "harness-catalog.json"),
-    relayAgentsRegistryPath: join(supportDirectory, "relay-agents.json"),
-    managedInstallsPath: join(supportDirectory, "managed-installs.json"),
-    hostInfoPath: join(supportDirectory, ".host-info"),
-    relayHubDirectory: process.env.OPENSCOUT_RELAY_HUB ?? join(home, ".openscout", "relay"),
+    relayAgentsDirectory: join2(runtimeDirectory, "agents"),
+    settingsPath: join2(supportDirectory, "settings.json"),
+    harnessCatalogPath: join2(catalogDirectory, "harness-catalog.json"),
+    relayAgentsRegistryPath: join2(supportDirectory, "relay-agents.json"),
+    managedInstallsPath: join2(supportDirectory, "managed-installs.json"),
+    hostInfoPath: join2(supportDirectory, ".host-info"),
+    relayHubDirectory: process.env.OPENSCOUT_RELAY_HUB ?? join2(home, ".openscout", "relay"),
     controlHome,
     knowledgeDirectory,
-    knowledgeQmdDirectory: join(knowledgeDirectory, "qmd"),
-    knowledgeSqlitePath: join(knowledgeDirectory, "knowledge.sqlite"),
-    desktopStatusPath: join(supportDirectory, "agent-status.json"),
-    workspaceStatePath: join(supportDirectory, "workspace-state.json"),
-    cutoverMarkerPath: join(supportDirectory, OPENSCOUT_RPC_CUTOVER_MARKER)
+    knowledgeQmdDirectory: join2(knowledgeDirectory, "qmd"),
+    knowledgeSqlitePath: join2(knowledgeDirectory, "knowledge.sqlite"),
+    desktopStatusPath: join2(supportDirectory, "agent-status.json"),
+    workspaceStatePath: join2(supportDirectory, "workspace-state.json"),
+    cutoverMarkerPath: join2(supportDirectory, OPENSCOUT_RPC_CUTOVER_MARKER)
   };
 }
 
 // ../runtime/src/claude-statusline.ts
 function resolveClaudeStatuslineDirectory() {
-  return join2(resolveOpenScoutSupportPaths().runtimeDirectory, "statusline");
+  return join3(resolveOpenScoutSupportPaths().runtimeDirectory, "statusline");
+}
+function resolveClaudeStatuslineSessionsDirectory(directory = resolveClaudeStatuslineDirectory()) {
+  return join3(directory, "sessions");
+}
+var CLAUDE_STATUSLINE_SESSION_ID_PATTERN = /^[A-Za-z0-9._-]{1,128}$/u;
+function resolveClaudeStatuslineSessionSnapshotPath(sessionId, directory) {
+  const trimmed = sessionId.trim();
+  if (!CLAUDE_STATUSLINE_SESSION_ID_PATTERN.test(trimmed))
+    return null;
+  return join3(resolveClaudeStatuslineSessionsDirectory(directory), `${trimmed}.json`);
 }
 function resolveClaudeStatuslineDelegatePath() {
-  return join2(resolveClaudeStatuslineDirectory(), "claude-delegate.json");
+  return join3(resolveClaudeStatuslineDirectory(), "claude-delegate.json");
 }
 function resolveClaudeStatuslineWrapperPath() {
-  return join2(resolveClaudeStatuslineDirectory(), "claude-statusline.sh");
+  return join3(resolveClaudeStatuslineDirectory(), "claude-statusline.sh");
 }
-function isRecord(value) {
+function isRecord2(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function stringValue(value) {
@@ -75,12 +1054,12 @@ function percentLabel(value) {
   return `${number.toFixed(1)}%`;
 }
 function recordValue(value) {
-  return isRecord(value) ? value : null;
+  return isRecord2(value) ? value : null;
 }
 function parseClaudeStatuslinePayload(input) {
   try {
     const parsed = JSON.parse(input);
-    return isRecord(parsed) ? parsed : null;
+    return isRecord2(parsed) ? parsed : null;
   } catch {
     return null;
   }
@@ -102,20 +1081,27 @@ async function captureClaudeStatuslineSnapshot(input, options = {}) {
   if (!parsed) {
     return { captured: false, reason: typeof input === "string" ? "invalid-json" : "invalid-record" };
   }
-  if (!isRecord(parsed)) {
+  if (!isRecord2(parsed)) {
     return { captured: false, reason: "invalid-record" };
   }
   const directory = options.directory ?? resolveClaudeStatuslineDirectory();
-  const latestPath = join2(directory, "claude-latest.json");
-  const historyPath = join2(directory, "claude-history.jsonl");
+  const latestPath = join3(directory, "claude-latest.json");
+  const historyPath = join3(directory, "claude-history.jsonl");
   const snapshot = normalizeClaudeStatuslineSnapshot(parsed, options.capturedAt);
   const line = JSON.stringify(snapshot);
+  const sessionId = stringValue(snapshot.session_id);
+  const sessionSnapshotPath = sessionId ? resolveClaudeStatuslineSessionSnapshotPath(sessionId, directory) : null;
   await mkdir(directory, { recursive: true });
+  if (sessionSnapshotPath) {
+    await mkdir(resolveClaudeStatuslineSessionsDirectory(directory), { recursive: true });
+  }
   await Promise.all([
     writeFile(latestPath, `${line}
 `, "utf8"),
     appendFile(historyPath, `${line}
-`, "utf8")
+`, "utf8"),
+    ...sessionSnapshotPath ? [writeFile(sessionSnapshotPath, `${line}
+`, "utf8")] : []
   ]);
   return {
     captured: true,
@@ -127,7 +1113,7 @@ async function captureClaudeStatuslineSnapshot(input, options = {}) {
 async function readClaudeStatuslineDelegate(path = resolveClaudeStatuslineDelegatePath()) {
   try {
     const parsed = JSON.parse(await readFile(path, "utf8"));
-    if (!isRecord(parsed))
+    if (!isRecord2(parsed))
       return null;
     const command = stringValue(parsed.command);
     if (!command)
@@ -137,7 +1123,7 @@ async function readClaudeStatuslineDelegate(path = resolveClaudeStatuslineDelega
       command,
       source: parsed.source === "manual" ? "manual" : "claude-settings.statusLine",
       installedAt: numberValue(parsed.installedAt) ?? Date.now(),
-      ...isRecord(parsed.statusLine) ? { statusLine: parsed.statusLine } : {}
+      ...isRecord2(parsed.statusLine) ? { statusLine: parsed.statusLine } : {}
     };
   } catch {
     return null;