pi-famulus 0.1.0

package/src/comms/tools.ts

@@ -0,0 +1,339 @@
+/**
+ * comms tools (design doc §4.7):
+ *
+ * - `contact_supervisor` — registered in child sessions; need_decision blocks
+ *   until the parent replies, progress_update is fire-and-forget.
+ * - `agent_message` — parent session (and child variant with implicit `from`)
+ *   for send / reply / broadcast / list.
+ *
+ * Zero runtime pi dependency: ToolDefinition is a type-only import.
+ */
+import { Type } from "typebox";
+import { realClock, type Clock } from "../clock";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { CommsWithOrigin } from "./comms";
+import { assertSiblingAllowed } from "./routing";
+import type { ChildStatus, Comms, CommsHost, MailboxEntry } from "./types";
+
+export type AgentMessageSender =
+  | { kind: "parent" }
+  | { kind: "child"; childId: string; runId: string };
+
+// ---------------------------------------------------------------------------
+// contact_supervisor (child sessions)
+// ---------------------------------------------------------------------------
+
+const contactSupervisorParameters = Type.Object({
+  reason: Type.Union([Type.Literal("need_decision"), Type.Literal("progress_update")], {
+    description:
+      '"need_decision" blocks until the supervisor (parent agent) replies; ' +
+      '"progress_update" is fire-and-forget.',
+  }),
+  message: Type.String({ description: "Message for the supervisor." }),
+});
+
+export interface ContactSupervisorDetails {
+  reason: "need_decision" | "progress_update";
+  replied: boolean;
+  error?: string;
+}
+
+export function createContactSupervisorTool(
+  comms: Comms,
+  childId: string,
+): ToolDefinition<typeof contactSupervisorParameters, ContactSupervisorDetails> {
+  return {
+    name: "contact_supervisor",
+    label: "Contact Supervisor",
+    description:
+      "Contact the supervisor (parent agent). " +
+      'Use reason "need_decision" when you are blocked and need the parent to decide — ' +
+      "the call blocks until the parent replies (10 minute timeout, after which you must " +
+      "decide yourself). " +
+      'Use reason "progress_update" for a fire-and-forget status note.',
+    promptSnippet: "Ask the parent agent for a decision or report progress",
+    parameters: contactSupervisorParameters,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      try {
+        const text = await comms.contactSupervisor(childId, params.reason, params.message);
+        return {
+          content: [{ type: "text", text }],
+          details: { reason: params.reason, replied: params.reason === "need_decision" },
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `contact_supervisor failed: ${message}` }],
+          details: { reason: params.reason, replied: false, error: message },
+        };
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// agent_message (parent session; child variant with implicit from)
+// ---------------------------------------------------------------------------
+
+const agentMessageParameters = Type.Object({
+  action: Type.Union(
+    [Type.Literal("send"), Type.Literal("reply"), Type.Literal("broadcast"), Type.Literal("list")],
+    {
+      description:
+        '"send" a message to a child, "reply" to a pending decision request, ' +
+        '"broadcast" to all running children of a run, "list" pending requests and recent traffic.',
+    },
+  ),
+  to: Type.Optional(
+    Type.String({
+      description:
+        'Target child_id or name ("send"/"reply"). For "broadcast" from the parent session: run_id. ' +
+        "Child sessions broadcast to their own run and must omit this.",
+    }),
+  ),
+  message: Type.Optional(Type.String({ description: "Message text." })),
+  delivery: Type.Optional(
+    Type.Union([Type.Literal("steer"), Type.Literal("queue")], {
+      description:
+        '"steer" (default) injects into a running child immediately; "queue" delivers after ' +
+        'its current turn. Sending to a finished child is an error — resume with subagent({action:"resume"}).',
+    }),
+  ),
+});
+
+export interface AgentMessageDetails {
+  action: "send" | "reply" | "broadcast" | "list";
+  ok: boolean;
+  error?: string;
+  to?: string;
+  delivery?: "steer" | "queue";
+  delivered?: string[];
+  pending?: { childId: string; name: string; message: string; sinceMs: number }[];
+  children?: { childId: string; runId: string; name: string; status: ChildStatus }[];
+  log?: MailboxEntry[];
+}
+
+type AgentMessageResult = {
+  content: { type: "text"; text: string }[];
+  details: AgentMessageDetails;
+};
+
+function errorResult(
+  action: AgentMessageDetails["action"],
+  text: string,
+  extra: Partial<AgentMessageDetails> = {},
+): AgentMessageResult {
+  return {
+    content: [{ type: "text", text: `Error: ${text}` }],
+    details: { action, ok: false, error: text, ...extra },
+  };
+}
+
+function okResult(
+  action: AgentMessageDetails["action"],
+  text: string,
+  extra: Partial<AgentMessageDetails> = {},
+): AgentMessageResult {
+  return { content: [{ type: "text", text }], details: { action, ok: true, ...extra } };
+}
+
+function truncate(text: string, maxChars = 120): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > maxChars ? `${flat.slice(0, maxChars - 1)}…` : flat;
+}
+
+interface ChildRef {
+  childId: string;
+  runId: string;
+  name: string;
+  status: ChildStatus;
+}
+
+/** Resolve a `to` argument that may be a child_id or a display name. */
+function resolveChildRef(host: CommsHost, ref: string): ChildRef | undefined {
+  const all = host.listChildren();
+  const byId = all.find((c) => c.childId === ref);
+  if (byId) return byId;
+  const byName = all.filter((c) => c.name === ref);
+  if (byName.length > 1) {
+    throw new Error(
+      `Ambiguous child name "${ref}" matches ${byName.map((c) => c.childId).join(", ")}; ` +
+        "use child_id.",
+    );
+  }
+  return byName[0];
+}
+
+function knownChildrenText(host: CommsHost): string {
+  return host.listChildren().map((c) => `${c.childId} (${c.name})`).join(", ") || "none";
+}
+
+function formatListText(
+  pending: { childId: string; name: string; message: string; sinceMs: number }[],
+  children: ChildRef[],
+  entries: MailboxEntry[],
+  now: number,
+): string {
+  const lines: string[] = [];
+  lines.push(`Pending decision requests: ${pending.length}`);
+  for (const p of pending) {
+    const ageS = Math.max(0, Math.round((now - p.sinceMs) / 1000));
+    lines.push(`- ${p.childId} (${p.name}) waiting ${ageS}s: "${truncate(p.message)}"`);
+  }
+  lines.push("", `Children: ${children.length}`);
+  for (const c of children) {
+    lines.push(`- ${c.childId} [${c.runId}] ${c.name} — ${c.status}`);
+  }
+  lines.push("", `Recent messages (last ${entries.length}):`);
+  for (const e of entries) {
+    const reply = e.reply !== undefined ? ` → reply: "${truncate(e.reply, 80)}"` : "";
+    lines.push(`- ${e.from} → ${e.to} (${e.kind}): "${truncate(e.message, 80)}"${reply}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * @param comms  the shared Comms instance
+ * @param sender parent session, or the child the tool is registered for
+ * @param host   CommsHost — needed for lineage checks, name resolution, and
+ *               the `list` summary (deviation from the two-arg sketch in the
+ *               task brief; required by the §4.7 routing rules)
+ */
+export function createAgentMessageTool(
+  comms: CommsWithOrigin,
+  sender: AgentMessageSender,
+  host: CommsHost,
+  clock: Clock = realClock,
+): ToolDefinition<typeof agentMessageParameters, AgentMessageDetails> {
+  const isChild = sender.kind === "child";
+  return {
+    name: "agent_message",
+    label: "Agent Message",
+    description: isChild
+      ? "Message sibling subagents in your run, or list pending requests. " +
+        '"send" delivers to a running sibling. Sending to a finished sibling errors and does not resume it; ' +
+        'resume with subagent({ action: "resume", run_id, child_id, message }). ' +
+        '"broadcast" steers every running sibling in your run; "list" shows pending ' +
+        "decision requests and recent traffic. Cross-run messaging is rejected."
+      : "Message your subagents. " +
+        '"send" steers or queues a running child. Sending to a finished child errors ' +
+        '(it does not resume) and points at subagent({ action: "resume", run_id, child_id, message }). ' +
+        '"reply" answers a child\'s pending decision request; "broadcast" steers every ' +
+        'running child of a run (to = run_id); "list" shows children, pending decision ' +
+        "requests, and recent traffic.",
+    promptSnippet: isChild
+      ? "Message sibling subagents in your run"
+      : "Send/reply/broadcast messages to subagents",
+    parameters: agentMessageParameters,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const action = params.action;
+      const from = isChild ? sender.childId : "supervisor";
+
+      if (action === "list") {
+        const pending = comms.pendingRequests();
+        const children = host.listChildren();
+        let entries: MailboxEntry[];
+        if (isChild) {
+          entries = comms.log(sender.runId, 20);
+        } else {
+          const runIds = [...new Set(children.map((c) => c.runId))];
+          entries = runIds
+            .flatMap((runId) => comms.log(runId, 200))
+            .sort((a, b) => a.ts - b.ts)
+            .slice(-20);
+        }
+        return okResult("list", formatListText(pending, children, entries, clock.now()), {
+          pending,
+          children,
+          log: entries,
+        });
+      }
+
+      if (!params.message) {
+        return errorResult(action, `action "${action}" requires "message".`);
+      }
+      const message = params.message;
+
+      if (action === "broadcast") {
+        let runId: string;
+        let fromChildId: string | undefined;
+        if (isChild) {
+          if (params.to !== undefined && params.to !== sender.runId) {
+            return errorResult("broadcast", "cross-run messaging not allowed");
+          }
+          runId = sender.runId;
+          fromChildId = sender.childId;
+        } else {
+          if (!params.to) {
+            return errorResult("broadcast", 'action "broadcast" requires "to" (run_id).');
+          }
+          runId = params.to;
+        }
+        const delivered = await comms.broadcast(runId, message, fromChildId);
+        const text =
+          delivered.length === 0
+            ? `Broadcast to run ${runId}: no running children received it.`
+            : `Broadcast to run ${runId} delivered to: ${delivered.join(", ")}.`;
+        return okResult("broadcast", text, { delivered });
+      }
+
+      // send / reply need a target child.
+      if (!params.to) {
+        return errorResult(action, `action "${action}" requires "to" (child_id or name).`);
+      }
+      let target: ChildRef | undefined;
+      try {
+        target = resolveChildRef(host, params.to);
+      } catch (err) {
+        return errorResult(action, err instanceof Error ? err.message : String(err));
+      }
+      if (!target) {
+        return errorResult(
+          action,
+          `Unknown child "${params.to}". Known children: ${knownChildrenText(host)}.`,
+        );
+      }
+      if (isChild) {
+        try {
+          assertSiblingAllowed(host, sender.childId, target.childId);
+        } catch (err) {
+          return errorResult(action, err instanceof Error ? err.message : String(err), {
+            to: target.childId,
+          });
+        }
+      }
+
+      if (action === "reply") {
+        try {
+          comms.reply(target.childId, message, from);
+        } catch (err) {
+          return errorResult("reply", err instanceof Error ? err.message : String(err), {
+            to: target.childId,
+          });
+        }
+        return okResult(
+          "reply",
+          `Replied to ${target.childId} (${target.name}): "${truncate(message, 80)}"`,
+          { to: target.childId },
+        );
+      }
+
+      // send
+      const delivery = params.delivery ?? "steer";
+      try {
+        await comms.send(target.childId, message, delivery, from);
+      } catch (err) {
+        return errorResult("send", err instanceof Error ? err.message : String(err), {
+          to: target.childId,
+          delivery,
+        });
+      }
+      const how =
+        delivery === "steer" ? "steered into the running child" : "queued for the running child";
+      return okResult("send", `Message to ${target.childId} (${target.name}) ${how}.`, {
+        to: target.childId,
+        delivery,
+      });
+    },
+  };
+}

package/src/comms/types.ts

@@ -0,0 +1,68 @@
+/**
+ * comms types (design doc appendix B, M4).
+ *
+ * `ChildStatus` / `ChildResult` / `ChildHandle` are structural re-declarations
+ * of the appendix B contract. They are intentionally NOT imported from
+ * `../subagent/types` (M3 is developed in parallel and may not exist yet);
+ * any value satisfying these shapes is accepted.
+ */
+
+// ---------- structural subagent types (appendix B, re-declared) ----------
+
+export type ChildStatus = "pending" | "running" | "completed" | "failed" | "interrupted";
+
+export interface ChildResult {
+  status: "completed" | "failed" | "interrupted";
+  text: string;
+  error?: string;
+  durationMs: number;
+}
+
+export interface ChildHandle {
+  readonly childId: string;
+  readonly result: Promise<ChildResult>;
+  steer(message: string): Promise<void>;
+  followUp(message: string): Promise<void>;
+  resume(message: string): Promise<void>;
+  interrupt(): Promise<void>;
+  status(): ChildStatus;
+  lastEventAt(): number;
+  /** Resolved `provider/id` once the child session exists (optional for stubs). */
+  resolvedModel?(): string | undefined;
+}
+
+import type { FamulusWake } from "../wake";
+
+// ---------- comms contract (appendix B, verbatim) ----------
+
+export interface CommsHost {
+  // Implemented by the subagent registry (wired at integration time).
+  getChild(
+    childId: string,
+  ): { handle: ChildHandle; runId: string; name: string; status: ChildStatus } | undefined;
+  listChildren(): { childId: string; runId: string; name: string; status: ChildStatus }[];
+  sameRun(childIdA: string, childIdB: string): boolean;
+  notifySupervisor(wake: { content: string; details: FamulusWake }): void;
+}
+
+export interface MailboxEntry {
+  ts: number;
+  from: string; // "supervisor" | childId
+  to: string; // "supervisor" | childId
+  kind: "need_decision" | "progress_update" | "send" | "reply" | "broadcast";
+  message: string;
+  reply?: string;
+}
+
+export interface Comms {
+  contactSupervisor(
+    fromChildId: string,
+    reason: "need_decision" | "progress_update",
+    message: string,
+  ): Promise<string>; // need_decision → reply text; progress_update → immediate "ok"
+  reply(toChildId: string, message: string): void; // no pending waiter → throw
+  send(toChildId: string, message: string, delivery: "steer" | "queue"): Promise<void>;
+  broadcast(runId: string, message: string, fromChildId?: string): Promise<string[]>; // delivered childIds
+  pendingRequests(): { childId: string; name: string; message: string; sinceMs: number }[];
+  log(runId: string, limit?: number): MailboxEntry[]; // default 20, ring 200/run
+}

package/src/config.ts

@@ -0,0 +1,266 @@
+/**
+ * Extension configuration loading (design doc §4.9).
+ *
+ * Config file: <famulus-home>/config.json
+ * Base directory resolution: PI_FAMULUS_HOME env > ~/.pi/agent/pi-famulus
+ */
+import { accessSync, constants, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { nativePackageName, resolveNativeManagerPath } from "./native-manager.js";
+
+export interface FamulusConfig {
+  /** Foreground budget for bash before auto-backgrounding (ms). */
+  foregroundBudgetMs: number;
+  /** Foreground budget for subagent runs (ms). Reserved for M3. */
+  subagentBudgetMs: number;
+  /** Explicit path to the pi-famulus binary, or null for auto-resolution. */
+  managerPath: string | null;
+  logLevel: "debug" | "info" | "warn" | "error";
+  /** Optional M3 subagent tuning section (design doc §4.6 limits). */
+  subagent?: FamulusSubagentConfig;
+}
+
+/** Optional `subagent` section of config.json; every field defaults (see resolveSubagentConfig). */
+export interface FamulusSubagentConfig {
+  /** Sync-wait budget before a run is moved to background (ms). Overrides top-level subagentBudgetMs. */
+  budgetMs?: number;
+  /** Default per-child hard timeout (ms). */
+  timeoutMs?: number;
+  /** Stall watchdog: abort a child with no events for this long (ms). Paused during tools and need_decision. */
+  stallMs?: number;
+  /** Auto-resume attempts after a stall before the run settles failed (stalled). Default 1. */
+  stallRetries?: number;
+  /** Pause between the stall abort and the retry prompt (ms). Default 5000. */
+  stallRetryDelayMs?: number;
+  /** need_decision wait for the parent (ms). Independent of stallMs and timeoutMs. */
+  decisionTimeoutMs?: number;
+  /** Default per-run worker pool concurrency. */
+  concurrency?: number;
+  /** Global cap on concurrently running children across all runs. */
+  maxConcurrentChildren?: number;
+  /** Max child sessions spawned per hour. */
+  spawnBudgetPerHour?: number;
+}
+
+/** Subagent settings with every field resolved (design doc §4.6 defaults). */
+export interface ResolvedSubagentConfig {
+  budgetMs: number;
+  timeoutMs: number;
+  stallMs: number;
+  stallRetries: number;
+  stallRetryDelayMs: number;
+  decisionTimeoutMs: number;
+  concurrency: number;
+  maxConcurrentChildren: number;
+  spawnBudgetPerHour: number;
+}
+
+/**
+ * Largest delay (ms) Node's setTimeout accepts without overflow. Larger
+ * configured values would clamp to ~1ms and fire immediately — cap instead.
+ */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+function capTimerDelay(value: number): number {
+  return Math.min(Math.floor(value), MAX_TIMER_DELAY_MS);
+}
+
+export const DEFAULT_SUBAGENT_CONFIG: ResolvedSubagentConfig = {
+  budgetMs: 45000,
+  timeoutMs: 1_800_000,
+  stallMs: 300_000,
+  stallRetries: 1,
+  stallRetryDelayMs: 5_000,
+  decisionTimeoutMs: 600_000,
+  concurrency: 4,
+  maxConcurrentChildren: 8,
+  spawnBudgetPerHour: 32,
+};
+
+/** Merge defaults <- top-level subagentBudgetMs <- subagent section. */
+export function resolveSubagentConfig(config: FamulusConfig): ResolvedSubagentConfig {
+  const section = config.subagent ?? {};
+  const resolved = { ...DEFAULT_SUBAGENT_CONFIG };
+  resolved.budgetMs = config.subagentBudgetMs > 0 ? config.subagentBudgetMs : resolved.budgetMs;
+  if (typeof section.budgetMs === "number" && section.budgetMs > 0) resolved.budgetMs = section.budgetMs;
+  if (typeof section.timeoutMs === "number" && section.timeoutMs > 0) resolved.timeoutMs = section.timeoutMs;
+  if (typeof section.stallMs === "number" && section.stallMs > 0) {
+    resolved.stallMs = capTimerDelay(section.stallMs);
+  }
+  if (typeof section.stallRetries === "number" && section.stallRetries >= 0) {
+    resolved.stallRetries = Math.floor(section.stallRetries);
+  }
+  if (typeof section.stallRetryDelayMs === "number" && section.stallRetryDelayMs >= 0) {
+    resolved.stallRetryDelayMs = capTimerDelay(section.stallRetryDelayMs);
+  }
+  if (typeof section.decisionTimeoutMs === "number" && section.decisionTimeoutMs > 0) {
+    resolved.decisionTimeoutMs = section.decisionTimeoutMs;
+  }
+  if (typeof section.concurrency === "number" && section.concurrency >= 1) {
+    resolved.concurrency = Math.floor(section.concurrency);
+  }
+  if (typeof section.maxConcurrentChildren === "number" && section.maxConcurrentChildren >= 1) {
+    resolved.maxConcurrentChildren = Math.floor(section.maxConcurrentChildren);
+  }
+  if (typeof section.spawnBudgetPerHour === "number" && section.spawnBudgetPerHour >= 1) {
+    resolved.spawnBudgetPerHour = Math.floor(section.spawnBudgetPerHour);
+  }
+  return resolved;
+}
+
+export const DEFAULT_CONFIG: FamulusConfig = {
+  foregroundBudgetMs: 20000,
+  subagentBudgetMs: 45000,
+  managerPath: null,
+  logLevel: "info",
+};
+
+/** Resolve the pi-famulus base directory. PI_FAMULUS_HOME overrides the default. */
+export function getFamulusHome(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.PI_FAMULUS_HOME;
+  if (override && override.trim().length > 0) return override;
+  return join(homedir(), ".pi", "agent", "pi-famulus");
+}
+
+/** Well-known paths inside the pi-famulus home directory (design doc §3.1). */
+export function famulusPaths(home: string) {
+  return {
+    home,
+    socket: join(home, "manager.sock"),
+    pidFile: join(home, "manager.pid"),
+    spawnLock: join(home, "manager.spawn.lock"),
+    log: join(home, "manager.log"),
+    config: join(home, "config.json"),
+    sessionsDir: join(home, "sessions"),
+  };
+}
+
+/** Full-output file path for a task (design doc §3.1 layout). */
+export function taskOutputPath(home: string, sessionId: string, taskId: string): string {
+  return join(home, "sessions", sessionId, "tasks", `${taskId}.output`);
+}
+
+/** Load config.json, tolerating missing/malformed files and unknown fields. */
+export function loadConfig(home: string = getFamulusHome()): FamulusConfig {
+  const path = famulusPaths(home).config;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+  if (typeof raw !== "object" || raw === null) return { ...DEFAULT_CONFIG };
+  const obj = raw as Record<string, unknown>;
+  const config = { ...DEFAULT_CONFIG };
+  if (typeof obj.foregroundBudgetMs === "number" && obj.foregroundBudgetMs > 0) {
+    config.foregroundBudgetMs = obj.foregroundBudgetMs;
+  }
+  if (typeof obj.subagentBudgetMs === "number" && obj.subagentBudgetMs > 0) {
+    config.subagentBudgetMs = obj.subagentBudgetMs;
+  }
+  if (typeof obj.managerPath === "string" && obj.managerPath.length > 0) {
+    config.managerPath = obj.managerPath;
+  }
+  if (
+    obj.logLevel === "debug" ||
+    obj.logLevel === "info" ||
+    obj.logLevel === "warn" ||
+    obj.logLevel === "error"
+  ) {
+    config.logLevel = obj.logLevel;
+  }
+  if (typeof obj.subagent === "object" && obj.subagent !== null) {
+    const section = obj.subagent as Record<string, unknown>;
+    const subagent: FamulusSubagentConfig = {};
+    if (typeof section.budgetMs === "number" && section.budgetMs > 0) subagent.budgetMs = section.budgetMs;
+    if (typeof section.timeoutMs === "number" && section.timeoutMs > 0) subagent.timeoutMs = section.timeoutMs;
+    if (typeof section.stallMs === "number" && section.stallMs > 0) {
+      subagent.stallMs = capTimerDelay(section.stallMs);
+    }
+    if (typeof section.stallRetries === "number" && section.stallRetries >= 0) {
+      subagent.stallRetries = Math.floor(section.stallRetries);
+    }
+    if (typeof section.stallRetryDelayMs === "number" && section.stallRetryDelayMs >= 0) {
+      subagent.stallRetryDelayMs = capTimerDelay(section.stallRetryDelayMs);
+    }
+    if (typeof section.decisionTimeoutMs === "number" && section.decisionTimeoutMs > 0) {
+      subagent.decisionTimeoutMs = section.decisionTimeoutMs;
+    }
+    if (typeof section.concurrency === "number" && section.concurrency >= 1) {
+      subagent.concurrency = section.concurrency;
+    }
+    if (typeof section.maxConcurrentChildren === "number" && section.maxConcurrentChildren >= 1) {
+      subagent.maxConcurrentChildren = section.maxConcurrentChildren;
+    }
+    if (typeof section.spawnBudgetPerHour === "number" && section.spawnBudgetPerHour >= 1) {
+      subagent.spawnBudgetPerHour = section.spawnBudgetPerHour;
+    }
+    config.subagent = subagent;
+  }
+  return config;
+}
+
+/** Return why a candidate is unusable, or null for an executable regular file. */
+function managerCandidateProblem(path: string): string | null {
+  try {
+    if (!statSync(path).isFile()) return "not a regular file";
+    accessSync(path, constants.X_OK);
+    return null;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return "missing";
+    if (code === "EACCES" || code === "EPERM") return "not executable";
+    return "inaccessible";
+  }
+}
+
+/**
+ * Human-readable account of the manager search locations for the degraded-startup
+ * warning, including why explicit and home/bin candidates are ignored.
+ */
+export function describeManagerSearch(
+  config: FamulusConfig,
+  home: string = getFamulusHome(),
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const describeCandidate = (path: string): string => {
+    const problem = managerCandidateProblem(path);
+    return `${path}${problem ? ` (${problem}, ignored)` : ""}`;
+  };
+  const tried: string[] = [];
+  if (config.managerPath) tried.push(`config managerPath ${describeCandidate(config.managerPath)}`);
+  if (env.PI_FAMULUS_MANAGER_PATH) tried.push(`PI_FAMULUS_MANAGER_PATH ${describeCandidate(env.PI_FAMULUS_MANAGER_PATH)}`);
+  const nativeName = nativePackageName(process.platform, process.arch);
+  const native = resolveNativeManagerPath();
+  tried.push(nativeName
+    ? `npm ${nativeName}${native ? ` ${native}` : " (missing or unusable, ignored)"}`
+    : `npm native manager (unsupported ${process.platform}/${process.arch})`);
+  tried.push(describeCandidate(join(home, "bin", "pi-famulus")));
+  tried.push("pi-famulus on PATH");
+  return tried.join("; ");
+}
+
+/**
+ * Resolve an executable regular pi-famulus binary, or null if none is usable.
+ * Priority: config.managerPath > PI_FAMULUS_MANAGER_PATH env > npm native package > <home>/bin/pi-famulus > PATH.
+ */
+export function resolveManagerPath(
+  config: FamulusConfig,
+  home: string = getFamulusHome(),
+  env: NodeJS.ProcessEnv = process.env,
+): string | null {
+  if (config.managerPath && managerCandidateProblem(config.managerPath) === null) return config.managerPath;
+  const envPath = env.PI_FAMULUS_MANAGER_PATH;
+  if (envPath && managerCandidateProblem(envPath) === null) return envPath;
+  const native = resolveNativeManagerPath();
+  if (native) return native;
+  const bundled = join(home, "bin", "pi-famulus");
+  if (managerCandidateProblem(bundled) === null) return bundled;
+  for (const dir of (env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, "pi-famulus");
+    if (managerCandidateProblem(candidate) === null) return candidate;
+  }
+  return null;
+}