catherd-cli 1.3.0 → 1.5.0

package/src/infra/codex-queue.ts

@@ -0,0 +1,165 @@
+import type { HostSessionRef } from "../domain/host.ts";
+import { runCli } from "./cli.ts";
+import { scrubSecrets } from "./env.ts";
+
+export interface QueueCapability {
+  cli: boolean;
+  server: "supported" | "unsupported" | "unverified";
+  reason: string | null;
+  /** false when nothing was probed yet: `cli` then says nothing about the CLI */
+  checked?: false;
+}
+export type QueueSendResult =
+  | { outcome: "accepted"; msgId: string }
+  | { outcome: "not-submitted"; reason: string }
+  | { outcome: "ambiguous"; reason: string };
+
+const UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const uuid = new RegExp(`^${UUID}$`, "i");
+const receipt = new RegExp(`^Queued message (${UUID}) for thread (${UUID})\\.$`);
+const TIMEOUT_MS = 10000;
+
+export async function queueCapability(
+  env: Record<string, string | undefined>,
+  run: typeof runCli = runCli,
+): Promise<QueueCapability> {
+  try {
+    const help = await run("codex", ["queue", "--help"], {
+      timeoutMs: TIMEOUT_MS,
+      env: scrubSecrets({ ...process.env, ...env }),
+    });
+    if (
+      !help?.ok ||
+      !/\bqueue\b/.test(help.out) ||
+      !["--thread", "--message", "--remote"].every((flag) => new RegExp(`${flag}\\s`).test(help.out))
+    )
+      return {
+        cli: false,
+        server: "unverified",
+        reason: "Native codex queue with --remote is unavailable; update Codex and use peek/result.",
+      };
+    return {
+      cli: true,
+      server: "unverified",
+      reason: "Native server queue method enumeration is unavailable; help proves CLI support only.",
+    };
+  } catch {
+    return {
+      cli: false,
+      server: "unverified",
+      reason: "Could not inspect native codex queue; use peek/result.",
+    };
+  }
+}
+
+const PROBE_TTL_MS = 60_000;
+let known: { at: number; capability: QueueCapability } | null = null;
+let probing: Promise<void> | null = null;
+
+/** The capability a one-shot command reports without probing: it never waits, and doctor checks it. */
+export const UNCHECKED_QUEUE: QueueCapability = {
+  cli: false,
+  server: "unverified",
+  reason: "Native codex queue is not checked by this command; catherd doctor checks it.",
+  checked: false,
+};
+
+/**
+ * The last known queue capability, without waiting on the Codex CLI: peek and status never wait (spec §3.7).
+ * A missing or stale answer starts one probe in the background; until it lands the capability reads unchecked.
+ */
+export function knownQueueCapability(
+  env: Record<string, string | undefined>,
+  run: typeof runCli = runCli,
+  now: number = Date.now(),
+): QueueCapability {
+  if (!probing && (!known || now - known.at >= PROBE_TTL_MS))
+    probing = queueCapability(env, run)
+      .then((capability) => {
+        known = { at: now, capability };
+      })
+      .finally(() => {
+        probing = null;
+      });
+  return (
+    known?.capability ?? {
+      cli: false,
+      server: "unverified",
+      reason: "Native codex queue is being checked; peek again for the result.",
+      checked: false,
+    }
+  );
+}
+
+/** Settles the background probe knownQueueCapability started, if any (a test seam). */
+export async function queueProbeSettled(): Promise<void> {
+  await probing;
+}
+
+/** Settles any background probe and forgets its answer (a test seam). */
+export async function resetQueueProbe(): Promise<void> {
+  await probing;
+  known = null;
+}
+
+export async function sendToCodexQueue(
+  target: HostSessionRef,
+  content: string,
+  env: Record<string, string | undefined>,
+  run: typeof runCli = runCli,
+): Promise<QueueSendResult> {
+  if (target.host !== "codex" || target.sessionId.length !== 36 || !uuid.test(target.sessionId))
+    return {
+      outcome: "not-submitted",
+      reason: "Queue requires a validated original Codex thread UUID; use peek/result.",
+    };
+  if (!content.trim()) return { outcome: "not-submitted", reason: "Queue message is empty." };
+  const capability = await queueCapability(env, run);
+  if (!capability.cli || capability.server === "unsupported")
+    return {
+      outcome: "not-submitted",
+      reason: capability.reason ?? "Native queue is unavailable; use peek/result.",
+    };
+  try {
+    const args = ["queue", "--remote", "unix://", "--thread", target.sessionId, "--message", content];
+    const result = await run("codex", args, {
+      timeoutMs: TIMEOUT_MS,
+      env: scrubSecrets({ ...process.env, ...env }),
+      logArgs: [...args.slice(0, -1), "[redacted]"],
+    });
+    if (result === null)
+      return { outcome: "not-submitted", reason: "Codex executable is unavailable; use peek/result." };
+    const match = result.ok ? receipt.exec(result.out.trim()) : null;
+    if (match && match[2]?.toLowerCase() === target.sessionId.toLowerCase())
+      return { outcome: "accepted", msgId: match[1]! };
+    if (
+      !result.ok &&
+      !result.out.trim() &&
+      (/^Error: the remote app server does not support thread\/queue\/add; update or restart the remote app server(?:\n|$)/.test(
+        result.err,
+      ) ||
+        /^error: (?:unrecognized subcommand 'queue'|unexpected argument '--remote' found)(?:\n|$)/.test(
+          result.err,
+        ) ||
+        /^Error: failed to connect to remote app server at `unix:\/\/[^`\n]+`: [^\n]+(?:\n|$)/.test(
+          result.err,
+        ))
+    )
+      return {
+        outcome: "not-submitted",
+        reason:
+          "Native queue refused before submission; check CLI/server support and the existing native endpoint, then use peek/result.",
+      };
+    return {
+      outcome: "ambiguous",
+      reason:
+        "Native queue invocation has no verified receipt; use peek/result. Retrying may duplicate input.",
+    };
+  } catch {
+    return {
+      outcome: "ambiguous",
+      reason:
+        "Native queue invocation failed without a verified receipt; use peek/result. Retrying may duplicate input.",
+    };
+  }
+}

package/src/infra/delivery.ts

@@ -0,0 +1,86 @@
+import { existsSync } from "node:fs";
+import { z } from "zod";
+import { CatherdError } from "../domain/errors.ts";
+import { sessionKey, type HostSessionRef } from "../domain/host.ts";
+import { awaitsCollect, dispatchPaths } from "./dispatch-dir.ts";
+import { withFileLockSync } from "./filelock.ts";
+import { readVersioned, writeJsonAtomic } from "./store.ts";
+
+const AttemptSchema = z
+  .looseObject({
+    attemptId: z.string().min(1),
+    target: z.object({
+      host: z.enum(["codex", "claude-code"]),
+      sessionId: z.string().min(1),
+      hostSessionId: z.string().nullable(),
+      name: z.string().nullable(),
+    }),
+    eventIds: z.array(z.string().min(1)).min(1),
+    at: z.iso.datetime(),
+    status: z.enum(["submitting", "accepted", "ambiguous", "failed"]),
+    msgId: z.string().nullable(),
+    reason: z.string().nullable(),
+  })
+  .refine((a) => a.status !== "accepted" || Boolean(a.msgId?.trim()), "accepted attempt needs a receipt");
+const DeliverySchema = z.looseObject({ schema: z.literal(1), attempts: z.array(AttemptSchema) });
+export type DeliveryAttempt = z.infer<typeof AttemptSchema>;
+/** How a delivery to a role's thread is recorded (spec 1.5 plan 21); `status` warns about it. */
+export const ROLE_THREAD_REFUSAL = "refused: the target is a role's thread";
+
+export type DeliveryState = "pending" | "enqueue-accepted" | "ambiguous" | "collected";
+
+export function readDelivery(dir: string): DeliveryAttempt[] {
+  const file = dispatchPaths(dir).delivery;
+  return existsSync(file)
+    ? readVersioned(file, DeliverySchema, 1, {
+        fix: "Use peek/result; delivery evidence is unreadable and retry may duplicate input.",
+      }).attempts
+    : [];
+}
+
+/** Short shared lock: distinct stalled/finished event claims must not lose each other's updates. */
+export function writeDeliveryAttempt(dir: string, attempt: DeliveryAttempt): void {
+  const parsed = AttemptSchema.safeParse(attempt);
+  if (!parsed.success) throw new CatherdError("E_INPUT_INVALID", "Invalid delivery attempt");
+  const file = dispatchPaths(dir).delivery;
+  withFileLockSync(file, () => {
+    const document = existsSync(file)
+      ? readVersioned(file, DeliverySchema, 1)
+      : { schema: 1 as const, attempts: [] as DeliveryAttempt[] };
+    const prior = document.attempts.findIndex((a) => a.attemptId === attempt.attemptId);
+    if (prior < 0) document.attempts.push(parsed.data);
+    else {
+      const sent = document.attempts[prior]!;
+      if (
+        JSON.stringify(sent.target) !== JSON.stringify(parsed.data.target) ||
+        JSON.stringify(sent.eventIds) !== JSON.stringify(attempt.eventIds) ||
+        sent.at !== attempt.at
+      )
+        throw new CatherdError(
+          "E_INPUT_INVALID",
+          "Delivery target, events and submission time are immutable",
+        );
+      document.attempts[prior] = { ...sent, ...parsed.data };
+    }
+    writeJsonAtomic(file, document);
+  });
+}
+
+export function deliveryState(dir: string, target: HostSessionRef, eventId: string): DeliveryState {
+  try {
+    const event = JSON.parse(eventId) as unknown;
+    if (Array.isArray(event) && event[2] === "finished" && !awaitsCollect(dir)) return "collected";
+  } catch {
+    /* Invalid event text cannot imply collection. */
+  }
+  try {
+    const attempts = readDelivery(dir).filter(
+      (a) => sessionKey(a.target) === sessionKey(target) && a.eventIds.includes(eventId),
+    );
+    if (attempts.some((a) => a.status === "accepted")) return "enqueue-accepted";
+    if (attempts.some((a) => a.status === "submitting" || a.status === "ambiguous")) return "ambiguous";
+    return "pending";
+  } catch {
+    return "ambiguous";
+  }
+}

package/src/infra/dispatch-dir.ts

@@ -40,10 +40,13 @@ export function dispatchPaths(dir: string) {
     failover: join(dir, "failover.json"),
     /** the message that announced this dispatch's record to its session, once sent (plan 10) */
     notified: join(dir, "notified.json"),
+    delivery: join(dir, "delivery.json"),
     /** written once by the supervisor when the worker went quiet for half its idle timeout, not busy (spec §3.6) */
     stall: join(dir, "stall.json"),
     /** the message that announced the stall, once sent */
     stallNotified: join(dir, "stall-notified.json"),
+    /** the role's own thread, written by the supervisor once the CLI names it (spec 1.5 plan 21) */
+    thread: join(dir, "thread.json"),
   };
 }
 

package/src/infra/env.ts

@@ -5,6 +5,9 @@
  * runs, a headless claude-code worker would inherit it): no process catherd starts gets them.
  */
 const SECRET_ENV = new Set([
+  "CODEX_THREAD_ID",
+  "CODEX_SESSION_ID",
+  "CATHERD_ORCHESTRATION_HOST",
   "TYPESAFE_API_KEY",
   // spec 1.2 §9: the user's Artificial Analysis key reads scores for catherd alone
   "ARTIFICIAL_ANALYSIS_API_KEY",
@@ -14,6 +17,9 @@ const SECRET_ENV = new Set([
   "CLAUDE_CODE_HOST_SESSION_ID",
 ]);
 
+/** Whether `name` is one of catherd's own secrets, which no process catherd starts ever gets. */
+export const isCatherdSecret = (name: string): boolean => SECRET_ENV.has(name);
+
 /** `base` without catherd's own secrets and without unset keys; for every process catherd starts. */
 export function scrubSecrets(base: Record<string, string | undefined>): Record<string, string> {
   const env: Record<string, string> = {};
@@ -39,7 +45,7 @@ export function workerEnv(
   overrides: Record<string, string>,
   cwd: string,
 ): Record<string, string> {
-  return { ...scrubSecrets(base), ...overrides, PWD: cwd };
+  return { ...scrubSecrets({ ...base, ...overrides }), PWD: cwd };
 }
 
 /** What a preflight check may see; everything else, credentials included, stays out (spec §4.7). */
@@ -59,11 +65,18 @@ const CHECK_ENV = new Set([
   "CATHERD_LOCK_SLOTS",
 ]);
 const CHECK_ENV_PATTERN = /^(LC_[A-Z_]+|XDG_[A-Z_]+_(HOME|DIR|DIRS))$/;
+/**
+ * Plan 23: where the toolchains a check runs find their daemon, proxy and caches (DOCKER_HOST for OrbStack or
+ * rootless Docker, a proxy, Go's and pnpm's caches); without them a check that would run fails as if broken.
+ */
+const TOOL_ENV_PATTERN =
+  /^(DOCKER_(HOST|CONTEXT|CONFIG|CERT_PATH|TLS_VERIFY)|TESTCONTAINERS_[A-Z_]+|(HTTPS?|NO|ALL)_PROXY|(https?|no|all)_proxy|GO(PATH|CACHE|MODCACHE|FLAGS|PROXY|PRIVATE|NOSUMDB|TOOLCHAIN)|PNPM_HOME|npm_config_store_dir|BUN_INSTALL(_CACHE_DIR)?|NVM_DIR|JAVA_HOME|CARGO_HOME|RUSTUP_HOME)$/;
 
 /** A strict allowlist of `base` plus PWD, for lane-authored shell text such as preflight checks. */
 export function checkEnv(base: Record<string, string | undefined>, cwd: string): Record<string, string> {
   const env: Record<string, string> = {};
   for (const [k, v] of Object.entries(base))
-    if (v !== undefined && (CHECK_ENV.has(k) || CHECK_ENV_PATTERN.test(k))) env[k] = v;
+    if (v !== undefined && (CHECK_ENV.has(k) || CHECK_ENV_PATTERN.test(k) || TOOL_ENV_PATTERN.test(k)))
+      env[k] = v;
   return { ...env, PWD: cwd };
 }

package/src/infra/git.ts

@@ -54,6 +54,12 @@ export async function gitToplevel(dir: string): Promise<string | null> {
   return r.kind === "ok" ? r.out.trim() || null : null;
 }
 
+/** The repo's `origin` remote URL, or null when it has none (or git cannot say). */
+export async function gitOrigin(repo: string): Promise<string | null> {
+  const r = await git(repo, ["config", "--get", "remote.origin.url"]);
+  return (r.kind === "ok" && r.out.trim()) || null;
+}
+
 /** The short HEAD, or null when git cannot say (no commit, not a repo, failure, timeout). */
 export async function gitHead(repo: string, timeoutMs?: number): Promise<string | null> {
   const r = await git(repo, ["rev-parse", "--short", "HEAD"], timeoutMs);

package/src/infra/heavy-lock.ts

@@ -1,8 +1,11 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
 import { availableParallelism } from "node:os";
 import { join } from "node:path";
-import { tryLock } from "./filelock.ts";
+import { tryLock, withFileLock } from "./filelock.ts";
 import { locksDir } from "./paths.ts";
-import { ensurePrivateDir } from "./store.ts";
+import { isAlive, selfIdentity } from "./proc.ts";
+import { ensurePrivateDir, writeJsonAtomic } from "./store.ts";
 
 /** A profile's `lock.heavy` as a slot count: a number, or half the cores. */
 export function heavySlots(setting: number | "cpus/2" | undefined): number {
@@ -17,20 +20,106 @@ export function heavySlots(setting: number | "cpus/2" | undefined): number {
 export async function withHeavySlot<T>(
   slots: number,
   fn: (slot: number) => T | Promise<T>,
-  o: { pollMs?: number } = {},
+  o: { pollMs?: number; onWait?: () => void } = {},
 ): Promise<T> {
+  const r = await withHeavySlotWithin(slots, Number.POSITIVE_INFINITY, fn, o);
+  if (r.busy) throw new Error("unreachable: an unbounded wait never gives up");
+  return r.value;
+}
+
+/**
+ * withHeavySlot with a wait budget (plan 23): `{ busy: true }` when no slot came free within `waitMs`, so a
+ * caller with a deadline of its own (preflight) reports the lock as busy instead of timing out behind it.
+ */
+export async function withHeavySlotWithin<T>(
+  slots: number,
+  waitMs: number,
+  fn: (slot: number) => T | Promise<T>,
+  o: { pollMs?: number; onWait?: () => void } = {},
+): Promise<{ busy: false; value: T } | { busy: true }> {
   const dir = locksDir();
   ensurePrivateDir(dir);
+  const deadline = Date.now() + waitMs;
   for (;;) {
     for (let i = 0; i < slots; i++) {
       const release = tryLock(join(dir, `slot-${i}`));
       if (!release) continue;
       try {
-        return await fn(i);
+        return { busy: false, value: await fn(i) };
       } finally {
         release();
       }
     }
+    const left = deadline - Date.now();
+    if (left <= 0) return { busy: true };
+    o.onWait?.();
+    await Bun.sleep(Math.min(o.pollMs ?? 500, left));
+  }
+}
+
+/** A process inside a role lock: who, so a dead one is dropped, and a token, so one process can hold twice. */
+interface RoleHolder {
+  pid: number;
+  startTime: string | null;
+  token: string;
+}
+
+interface RoleLockState {
+  /** whose the lock is: a run id (holders of one run share it), or a lone process's own key */
+  owner: string;
+  holders: RoleHolder[];
+}
+
+function readRoleState(file: string): RoleLockState | null {
+  if (!existsSync(file)) return null;
+  try {
+    const v = JSON.parse(readFileSync(file, "utf8")) as RoleLockState;
+    return typeof v?.owner === "string" && Array.isArray(v.holders) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Spec 1.5 "Cross-run verifier contention": one owner at a time machine-wide holds the lock of `role`.
+ * Commands of the same owner (one run's verifier, side by side within its slots) share it; another owner's
+ * wait until the last of them ends, so two runs' verifiers never overlap. A dead holder is dropped.
+ */
+export async function withRoleLock<T>(
+  role: string,
+  owner: string,
+  fn: () => T | Promise<T>,
+  o: { pollMs?: number; onWait?: () => void } = {},
+): Promise<T> {
+  const dir = locksDir();
+  ensurePrivateDir(dir);
+  const file = join(dir, `role-${role}.json`);
+  const me: RoleHolder = { ...selfIdentity(), token: randomUUID() };
+  const enter = () =>
+    withFileLock(file, () => {
+      const state = readRoleState(file);
+      const live = (state?.holders ?? []).filter((h) => isAlive(h.pid, h.startTime));
+      if (live.length && state?.owner !== owner) return false;
+      writeJsonAtomic(file, { owner, holders: [...live, me] } satisfies RoleLockState);
+      return true;
+    });
+  while (!(await enter())) {
+    o.onWait?.();
     await Bun.sleep(o.pollMs ?? 500);
   }
+  try {
+    return await fn();
+  } finally {
+    await withFileLock(file, () => {
+      const state = readRoleState(file);
+      if (state)
+        writeJsonAtomic(file, { ...state, holders: state.holders.filter((h) => h.token !== me.token) });
+    });
+  }
+}
+
+/** Who holds the role lock now, or null. */
+export function roleLockOwner(role: string): string | null {
+  const state = readRoleState(join(locksDir(), `role-${role}.json`));
+  return state && state.holders.some((h) => isAlive(h.pid, h.startTime)) ? state.owner : null;
 }

package/src/infra/host-context.ts

@@ -0,0 +1,58 @@
+import type { HostContext, KnownHost, OrchestrationHost } from "../domain/host.ts";
+import { readSessionEnv, sessionFileFor } from "./claude-session.ts";
+
+export function resolveHost(e: {
+  clientName?: string;
+  env: Record<string, string | undefined>;
+  terminalHost?: OrchestrationHost;
+}): HostContext {
+  const conflict = (message: string): HostContext => ({ host: "unknown", session: null, conflict: message });
+  const hosts = new Set<KnownHost>();
+  const client = e.clientName;
+  if (client === "codex-mcp-client") hosts.add("codex");
+  if (client === "claude-code") hosts.add("claude-code");
+  const launcher = e.env.CATHERD_ORCHESTRATION_HOST;
+  if (launcher === "codex" || launcher === "claude-code") hosts.add(launcher);
+  const claude = readSessionEnv(e.env);
+  if (claude) hosts.add("claude-code");
+  // UUIDs are case-insensitive: one spelling, so the launcher's and a request's casing name the same thread
+  const thread = e.env.CODEX_THREAD_ID?.toLowerCase();
+  const session = e.env.CODEX_SESSION_ID?.toLowerCase();
+  const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (thread !== undefined || session !== undefined) {
+    hosts.add("codex");
+    if ((thread !== undefined && !uuid.test(thread)) || (session !== undefined && !uuid.test(session)))
+      return conflict("Codex session IDs must be UUIDs; remove invalid CODEX_THREAD_ID / CODEX_SESSION_ID");
+    if (thread && session && thread !== session)
+      return conflict("CODEX_THREAD_ID and CODEX_SESSION_ID disagree; correct the launcher environment");
+  }
+  if (hosts.size > 1)
+    return conflict(
+      "Initialized client and launcher session evidence disagree; remove the other host's environment",
+    );
+  const host = [...hosts][0] ?? e.terminalHost ?? "unknown";
+  if (host === "codex")
+    return {
+      host,
+      session:
+        thread || session ? { host, sessionId: thread || session!, hostSessionId: null, name: null } : null,
+      conflict: null,
+    };
+  if (host === "claude-code" && claude) {
+    const file = sessionFileFor(claude);
+    const id = file?.sessionId ?? claude.sessionId;
+    return {
+      host,
+      session: id
+        ? {
+            host,
+            sessionId: id,
+            hostSessionId: file?.hostSessionId ?? claude.hostSessionId,
+            name: file?.name ?? null,
+          }
+        : null,
+      conflict: null,
+    };
+  }
+  return { host, session: null, conflict: null };
+}

package/src/infra/host-probe.ts

@@ -0,0 +1,16 @@
+// Plan 23: a host probe that fails once may have caught the network mid-change (a VPN just dropped, a route
+// still settling). catherd's own host probes run twice, this far apart, before they call the host blocked.
+
+/** The pause before the second try; tests shorten it. */
+export const hostProbe = { retryMs: 5_000 };
+
+/** `probe`, and once more after hostProbe.retryMs when `ok` says the first answer failed. */
+export async function probeTwice<T>(
+  probe: () => Promise<T>,
+  ok: (r: T) => boolean,
+): Promise<{ result: T; attempts: 1 | 2 }> {
+  const first = await probe();
+  if (ok(first)) return { result: first, attempts: 1 };
+  await Bun.sleep(hostProbe.retryMs);
+  return { result: await probe(), attempts: 2 };
+}

package/src/infra/lock-activity.ts

@@ -0,0 +1,88 @@
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { locksDir } from "./paths.ts";
+import { isAlive, processStartTime } from "./proc.ts";
+import { ensurePrivateDir, writeJsonAtomic } from "./store.ts";
+
+// Plan 23: a role's long gate runs behind `catherd lock`. While such a lock child is alive and writing, the
+// role's wall timeout counts from its last output, not from the role's start. The lock writes here, in the
+// locks dir every role may write; the supervisor reads it.
+
+/** The env var the supervisor's spec carries, so a `catherd lock` inside the role knows its dispatch. */
+export const DISPATCH_ID_ENV = "CATHERD_DISPATCH_ID";
+
+/** A lock child reports at most this often, so a chatty command does not write a file per line. */
+export const ACTIVITY_EVERY_MS = 1_000;
+
+const SAFE_ID = /^[A-Za-z0-9][\w.-]{0,127}$/;
+
+/** `<locks>/activity/<dispatch id>`: one file per live `catherd lock` of that dispatch. */
+export const activityDir = (dispatchId: string): string => join(locksDir(), "activity", dispatchId);
+
+interface Activity {
+  schema: 1;
+  pid: number;
+  startTime: string | null;
+  /** the last time the lock's command wrote output (its start, before the first line) */
+  at: string;
+}
+
+/**
+ * A reporter for this `catherd lock` process, or null outside a dispatch (no id, or one that is not a plain
+ * id: it names a path). `tick` records output, at most once per ACTIVITY_EVERY_MS; `done` removes the file.
+ */
+export function activityReporter(
+  dispatchId: string | undefined,
+  now: () => number = Date.now,
+  everyMs = ACTIVITY_EVERY_MS,
+): { tick: () => void; done: () => void } | null {
+  if (!dispatchId || !SAFE_ID.test(dispatchId) || dispatchId.includes("..")) return null;
+  const dir = activityDir(dispatchId);
+  const file = join(dir, `${process.pid}.json`);
+  const startTime = processStartTime(process.pid);
+  let last = 0;
+  const write = (t: number): void => {
+    try {
+      ensurePrivateDir(dir);
+      writeJsonAtomic(file, {
+        schema: 1,
+        pid: process.pid,
+        startTime,
+        at: new Date(t).toISOString(),
+      } satisfies Activity);
+      last = t;
+    } catch {
+      // advisory: a lock that cannot report still runs its command
+    }
+  };
+  write(now());
+  return {
+    tick: () => {
+      const t = now();
+      if (t - last >= everyMs) write(t);
+    },
+    done: () => rmSync(file, { force: true }),
+  };
+}
+
+/**
+ * When a live `catherd lock` of the dispatch last wrote output, in ms; null when none is alive. A file whose
+ * process is gone is left alone (its lock may still be finishing its own cleanup) and never counts.
+ */
+export function lastLockOutput(dispatchId: string): number | null {
+  const dir = activityDir(dispatchId);
+  if (!existsSync(dir)) return null;
+  let latest: number | null = null;
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      const a = JSON.parse(readFileSync(join(dir, name), "utf8")) as Activity;
+      if (a.schema !== 1 || !isAlive(a.pid, a.startTime)) continue;
+      const at = Date.parse(a.at);
+      if (!Number.isNaN(at)) latest = Math.max(latest ?? at, at);
+    } catch {
+      // a file being written, or damaged: skipped this poll
+    }
+  }
+  return latest;
+}

package/src/infra/login-env.ts

@@ -0,0 +1,48 @@
+import { scrubSecrets } from "./env.ts";
+
+// Plan 23: what a login shell of the user's sees (DOCKER_HOST for OrbStack or rootless Docker, a proxy, a
+// toolchain's PATH), which a server started by a desktop app or a plugin launcher may not inherit.
+// `$SHELL -lc env` is run once per process and kept.
+
+/** How long the login shell may take; one that hangs (a prompt in a profile) counts as an empty env. */
+export const loginShell = { timeoutMs: 5_000 };
+
+let captured: Record<string, string> | null = null;
+
+/** Parses `env -0` output, or plain `env` lines from a shell whose env has no -0. */
+export function parseEnv(out: string): Record<string, string> {
+  const env: Record<string, string> = {};
+  const rows = out.includes("\0") ? out.split("\0") : out.split("\n");
+  for (const row of rows) {
+    const eq = row.indexOf("=");
+    if (eq > 0) env[row.slice(0, eq)] = row.slice(eq + 1);
+  }
+  return env;
+}
+
+function capture(): Record<string, string> {
+  const shell = process.env.SHELL || "/bin/sh";
+  try {
+    const r = Bun.spawnSync([shell, "-lc", "env -0 2>/dev/null || env"], {
+      env: scrubSecrets(process.env),
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "ignore",
+      timeout: loginShell.timeoutMs,
+    });
+    return r.exitCode === 0 ? scrubSecrets(parseEnv(r.stdout.toString())) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The user's login environment, without catherd's secrets; empty when the shell cannot say. Captured once. */
+export function loginEnv(): Record<string, string> {
+  captured ??= capture();
+  return captured;
+}
+
+/** Forgets the captured env (tests, which change SHELL). */
+export function resetLoginEnv(): void {
+  captured = null;
+}