catherd-cli 1.4.0 → 1.5.0

package/src/entry/tui/views/runs.tsx

@@ -1,4 +1,5 @@
-import { type MutableRefObject, useEffect, useRef, useState } from "react";
+import { type MutableRefObject, useEffect, useMemo, useRef, useState } from "react";
+import { waitingLine } from "../../../services/orchestrator-wait.ts";
 import { useApp, useBack, useNow } from "../providers/app.tsx";
 import { useData, usePoll } from "../providers/data.tsx";
 import { useCommandLayer } from "../providers/keymap.tsx";
@@ -7,7 +8,7 @@ import { useUi } from "../providers/theme.tsx";
 import { isArmed } from "../state.ts";
 import { ago, clock, plural, shortRung, wrap, wrapHanging } from "../text.ts";
 import { glyph, mascot, type Token } from "../theme.ts";
-import type { RoleRow, SessionRow, SessionRun } from "../effects.ts";
+import type { RoleRow, SessionDetail, SessionRow, SessionRun } from "../effects.ts";
 import { Line, type Part } from "../widgets/line.tsx";
 import { List, type ListItem, useSelected } from "../widgets/list.tsx";
 
@@ -166,6 +167,8 @@ function roleMark(r: RoleRow, plain: boolean): Part {
 function runHeading(r: SessionRun, now: number, plain: boolean): Part[] {
   const bits = [r.repo, `started ${ago(now - Date.parse(r.createdAt))}`];
   if (r.budget !== null) bits.push(`budget ${Math.round(r.budget * 100)}%`);
+  const waiting = waitingLine(r.waiting, now);
+  if (waiting) bits.push(waiting);
   const moved =
     r.continued === "here" ? "continued here" : r.continuedIn ? `continued in ${r.continuedIn}` : null;
   return [
@@ -181,8 +184,11 @@ function useLiveRead<T extends { dirs: string[] }>(read: () => T, key: string) {
   const app = useApp();
   const [watching, setWatching] = useState(false);
   const polled = usePoll(read, watching ? WATCHED_EVERY_MS : RUN_EVERY_MS, { paused: app.state.paused, key });
+  // the watch calls the latest refresh; the ref moves after each commit, never during a render
   const refresh = useRef(polled.refresh);
-  refresh.current = polled.refresh;
+  useEffect(() => {
+    refresh.current = polled.refresh;
+  });
   const dirs = polled.value?.dirs.join("\n") ?? "";
   useEffect(() => {
     if (app.state.paused || dirs === "") {
@@ -196,8 +202,26 @@ function useLiveRead<T extends { dirs: string[] }>(read: () => T, key: string) {
   return { ...polled, watching };
 }
 
+/**
+ * The row a session's screen starts on before the cursor moves: the first row of the run it was opened for,
+ * else its first live role (live roles can sit below many landed milestones), else its first row.
+ */
+function startRow(d: SessionDetail, run: string | undefined): string | null {
+  const rows = (r: SessionDetail["runs"][number]) => [
+    ...r.milestones.map((m) => milestoneKey(r.id, m.name)),
+    ...r.roles.map((x) => roleKey(x.run, x.dispatchId)),
+  ];
+  const asked = run === undefined ? undefined : d.runs.find((r) => r.id === run);
+  const first = asked ? rows(asked)[0] : undefined;
+  if (first) return first;
+  const live = d.runs.flatMap((r) => r.roles).find((x) => x.live);
+  if (live) return roleKey(live.run, live.dispatchId);
+  return d.runs.flatMap(rows)[0] ?? null;
+}
+
 function SessionView(props: {
   sessionKey: string | null;
+  run: string | undefined;
   width: number;
   height: number;
   initial: string | null;
@@ -206,17 +230,26 @@ function SessionView(props: {
   const app = useApp();
   const ui = useUi();
   const now = useNow(1_000);
-  const [selected, setSelected, selectedNow] = useSelection(props.initial);
+  const [chosen, setSelected, chosenNow] = useSelection(props.initial);
   const polled = useLiveRead(() => app.effects.session(props.sessionKey), String(props.sessionKey));
   useRefresher(props.refresher, polled.refresh);
   useBack(true, "view", () => app.dispatch({ type: "up" }));
   const d = polled.value;
-  const roleAt = (key: string | null) =>
-    d?.runs.flatMap((r) => r.roles).find((x) => key === roleKey(x.run, x.dispatchId)) ?? null;
-  const milestoneAt = (key: string | null) =>
-    d?.runs
-      .flatMap((r) => r.milestones.map((m) => ({ run: r.id, name: m.name })))
-      .find((x) => key === milestoneKey(x.run, x.name)) ?? null;
+  // each row's role or milestone by its key, built once per read rather than on every key
+  const byKey = useMemo(() => {
+    const roles = new Map<string, RoleRow>();
+    const milestones = new Map<string, { run: string; name: string }>();
+    for (const r of d?.runs ?? []) {
+      for (const m of r.milestones) milestones.set(milestoneKey(r.id, m.name), { run: r.id, name: m.name });
+      for (const x of r.roles) roles.set(roleKey(x.run, x.dispatchId), x);
+    }
+    return { roles, milestones, start: d ? startRow(d, props.run) : null };
+  }, [d, props.run]);
+  // until the cursor moves, it stands on the start row
+  const selected = chosen ?? byKey.start;
+  const selectedNow = () => chosenNow() ?? byKey.start;
+  const roleAt = (key: string | null) => (key === null ? null : (byKey.roles.get(key) ?? null));
+  const milestoneAt = (key: string | null) => (key === null ? null : (byKey.milestones.get(key) ?? null));
   useCommandLayer("row.runs", {
     "runs.open": () => {
       const k = selectedNow();
@@ -275,7 +308,7 @@ function SessionView(props: {
                 : { text: `${glyph("waiting", ui.plain)} ${m.name}`, tone: "muted" },
               m.landed
                 ? { text: m.what ? `  ${m.what}` : "", tone: "muted" }
-                : { text: "  not landed", tone: "muted" },
+                : { text: `  not landed${m.what ? ` · ${m.what}` : ""}`, tone: "muted" },
             ]}
           />
         ),
@@ -349,10 +382,17 @@ function RoleView(props: {
   const app = useApp();
   const ui = useUi();
   const [selected, setSelected] = useSelection();
+  // a role with its record is finished for good: nothing on its screen changes, so it is read no more
+  // (r still reads it again)
+  const [done, setDone] = useState(false);
   const polled = usePoll(() => app.effects.role(props.run, props.dispatchId), RUN_EVERY_MS, {
-    paused: app.state.paused,
+    paused: app.state.paused || done,
     key: `${props.run}/${props.dispatchId}`,
   });
+  const recorded = polled.value?.record != null;
+  useEffect(() => {
+    if (recorded) setDone(true);
+  }, [recorded]);
   useRefresher(props.refresher, polled.refresh);
   useBack(true, "view", () => app.dispatch({ type: "up" }));
   const d = polled.value;
@@ -532,13 +572,16 @@ export function RunsView(props: { width: number; height: number }) {
       app.toast({ variant: "info", message: app.getState().paused ? "Updates paused" : "Updates resumed" });
     },
   });
-  const { milestone, role, session } = app.state;
+  const { milestone, role, session, back } = app.state;
   // esc lands on the row it came from: the last session opened, and the last milestone or role opened in it
-  const back = useRef<{ session: string | null; row: string | null }>({ session: null, row: null });
-  if (session && back.current.session !== keyOf(session.key))
-    back.current = { session: keyOf(session.key), row: null };
-  if (milestone) back.current.row = milestoneKey(milestone.run, milestone.name);
-  if (role) back.current.row = roleKey(role.run, role.dispatchId);
+  const backRow =
+    back && session && back.session === session.key
+      ? back.milestone
+        ? milestoneKey(back.milestone.run, back.milestone.name)
+        : back.role
+          ? roleKey(back.role.run, back.role.dispatchId)
+          : null
+      : null;
   if (milestone)
     return (
       <MilestoneView
@@ -563,11 +606,14 @@ export function RunsView(props: { width: number; height: number }) {
     return (
       <SessionView
         sessionKey={session.key}
+        run={session.run}
         width={props.width}
         height={props.height}
-        initial={back.current.row}
+        initial={backRow}
         refresher={refresher}
       />
     );
-  return <SessionList width={props.width} height={props.height} initial={back.current.session} />;
+  return (
+    <SessionList width={props.width} height={props.height} initial={back ? keyOf(back.session) : null} />
+  );
 }

package/src/entry/tui/views/save-dialog.tsx

@@ -48,7 +48,7 @@ export interface SavePreview {
  */
 function previewSave(
   d: Draft,
-  fx: Pick<Effects, "catalog" | "validate" | "agents" | "readProfile">,
+  fx: Pick<Effects, "catalog" | "validate" | "agents" | "readProfile" | "profiles">,
   now: ProfileDoc = fx.readProfile(d.name),
 ): SavePreview {
   const before = resolveProfile(now, d.name, d.host);
@@ -62,7 +62,11 @@ function previewSave(
     changes: diffProfiles(before, after),
     treatLikes: Object.entries(d.treatLikes),
     validation,
-    repair: validation.errors.length > 0 && repairs(fx.validate(before, staged), validation),
+    // as the ProfileService rules: a profile with no stored file has no errors a save could repair (1.2 minor)
+    repair:
+      validation.errors.length > 0 &&
+      fx.profiles().names.includes(d.name) &&
+      repairs(fx.validate(before, staged), validation),
     agentsAdded: [...b].filter((x) => !a.has(x)),
     agentsRemoved: [...a].filter((x) => !b.has(x)),
   };

package/src/entry/tui/views/status.tsx

@@ -1,4 +1,5 @@
 import type { Check } from "../../../services/doctor-checks.ts";
+import { waitingLine } from "../../../services/orchestrator-wait.ts";
 import { useApp, useNow } from "../providers/app.tsx";
 import { useData } from "../providers/data.tsx";
 import { useCommandLayer } from "../providers/keymap.tsx";
@@ -19,6 +20,8 @@ function stateParts(state: Check["state"], word: string, plain: boolean): Part[]
 /** A run in one line: its state word first, then title, repo and progress (research C4). */
 export function runParts(r: RunRow, now: number, plain: boolean): Part[] {
   const bits = [plural(r.roleRuns, "role run"), `${r.landed} landed`];
+  const waiting = waitingLine(r.waiting, now);
+  if (waiting) bits.push(waiting);
   if (r.budget !== null) bits.push(`${Math.round(r.budget * 100)}% budget`);
   return [
     r.live
@@ -189,10 +192,11 @@ export function StatusView(props: { width: number; height: number }) {
       if (name !== null) {
         showProfile(app, name);
       } else if (selected?.startsWith("run:")) {
-        // spec §4: a run opens in its session's screen, which shows it with the session's other runs
+        // spec §4: a run opens in its session's screen, which shows it with the session's other runs; the
+        // cursor starts on that run
         const row = runs.find((r) => `run:${r.id}` === selected);
         app.dispatch({ type: "tab", tab: "runs" });
-        if (row) app.dispatch({ type: "session", key: row.session });
+        if (row) app.dispatch({ type: "session", key: row.session, run: row.id });
       }
     },
   });

package/src/entry/workspace-command.ts

@@ -0,0 +1,44 @@
+import { resolve } from "node:path";
+import { defineCommand } from "citty";
+import { inspectWorkspace, workspaceStatus } from "../services/workspace-service.ts";
+import { JSON_ARG, printJson } from "./cli-kit.ts";
+import { defaultDeps } from "./deps.ts";
+
+const inspect = defineCommand({
+  meta: { name: "inspect", description: "Read the explicit repositories in a workspace manifest" },
+  args: {
+    root: { type: "positional", description: "workspace root (default: current directory)" },
+    ...JSON_ARG,
+  },
+  async run({ args }) {
+    const view = await inspectWorkspace(resolve(args.root ?? process.cwd()));
+    if (args.json) return printJson(view);
+    console.log(view.root);
+    for (const [name, path] of Object.entries(view.repos)) console.log(`${name}: ${path}`);
+  },
+});
+
+const status = defineCommand({
+  meta: { name: "status", description: "Read a workspace run's children, dependencies and budget" },
+  args: {
+    workspace: { type: "positional", required: true, description: "workspace run id" },
+    ...JSON_ARG,
+  },
+  async run({ args }) {
+    const view = await workspaceStatus(defaultDeps(), args.workspace);
+    if (args.json) return printJson(view);
+    console.log(`${view.workspace.id}: ${view.workspace.title}`);
+    for (const step of view.steps) {
+      const blocked = step.blockedBy.length ? ` (waiting for ${step.blockedBy.join(", ")})` : "";
+      console.log(`${step.id}: ${step.repo} ${step.state}${step.run ? ` ${step.run}` : ""}${blocked}`);
+    }
+    console.log(
+      `spend: ${view.spend.tokens} tokens, ${view.spend.minutes.toFixed(2)} min, $${view.spend.usd.toFixed(2)}`,
+    );
+  },
+});
+
+export const workspaceCommand = defineCommand({
+  meta: { name: "workspace", description: "Inspect workspace members and coordinated runs" },
+  subCommands: { inspect, status },
+});

package/src/infra/boot-lock.ts

@@ -0,0 +1,25 @@
+import { join } from "node:path";
+import { tryLock } from "./filelock.ts";
+import { log } from "./log.ts";
+import { locksDir } from "./paths.ts";
+import { ensurePrivateDir } from "./store.ts";
+
+/** The machine-wide lock the MCP server that runs the boot sync and reconcile holds for its life. */
+export const bootLockTarget = (): string => join(locksDir(), "mcp-boot");
+
+/**
+ * Plan 22 (the three MCP servers of one Codex session): boot sync and reconcile are single-flight across
+ * processes. The first server takes this lock (its pid and start time in it; a dead holder's is reclaimed) and
+ * keeps it until it closes; a second server finds it held and skips both. Returns the release, or null while
+ * another live server holds it. A lock that cannot be taken for another reason never costs a reconcile: the
+ * server runs the boot work, with nothing to release.
+ */
+export function takeBootLock(): (() => void) | null {
+  try {
+    ensurePrivateDir(locksDir());
+    return tryLock(bootLockTarget());
+  } catch (e) {
+    log("warn", "boot", { lock: bootLockTarget(), error: e instanceof Error ? e.message : String(e) });
+    return () => {};
+  }
+}

package/src/infra/delivery.ts

@@ -24,6 +24,9 @@ const AttemptSchema = z
   .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[] {

package/src/infra/dispatch-dir.ts

@@ -45,6 +45,8 @@ export function dispatchPaths(dir: string) {
     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

@@ -17,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> = {};
@@ -62,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-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;
+}