pim-agent 0.13.0 → 0.14.0

package/packages/core/src/shared/Paths.ts

@@ -36,7 +36,10 @@ function expandHome(value: string): string {
 
 function abbreviateHome(path: string): string {
   const home = homedir();
-  return home && path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+  if (!home || !(path === home || path.startsWith(home + sep))) {
+    return path;
+  }
+  return `~${path.slice(home.length)}`;
 }
 
 function displayRelative(path: string, cwd: string): string {

package/packages/core/src/shared/PiExtensions.ts

@@ -10,11 +10,7 @@ import { ExtensionToggles } from "./ExtensionToggles";
 import { Fs } from "./Fs";
 import { Paths } from "./Paths";
 
-/**
- * Every origin an entry comes from, in the order a reader meets them: the
- * roster is sorted by it, and a pane groups what it is handed without
- * restating it.
- */
+/** Also the sort order of `list`. */
 const EXTENSION_GROUPS = ["pim", "package", "user", "project"] as const;
 
 export type ExtensionGroup = (typeof EXTENSION_GROUPS)[number];
@@ -24,7 +20,7 @@ export type ExtensionEntry = {
   readonly label: string;
   readonly group: ExtensionGroup;
   readonly enabled: boolean;
-  /** Whether this process will write the toggle; a project-scoped entry is listed but not switched. */
+  /** False for project-scoped entries: listed, but not switchable. */
   readonly writable: boolean;
 };
 
@@ -76,8 +72,7 @@ async function setEnabled(
   await writes.run(() => writePiToggle(id.slice("pi:".length), enabled, scope));
 }
 
-// A fresh SettingsManager per write: `setExtensionPaths` persists its in-memory
-// copy, which another process may have superseded since we last read it.
+// Fresh SettingsManager per write: another process may have changed the file since.
 async function writePiToggle(
   path: string,
   enabled: boolean,
@@ -171,8 +166,7 @@ async function resolve(scope: ExtensionScope): Promise<Resolution> {
     agentDir,
     settingsManager,
   });
-  // Without an answer, pi npm-installs every missing or drifted package, so a
-  // bare listing request would fire off an install.
+  // "skip" stops pi from npm-installing missing packages during a listing.
   const resolved = await manager.resolve(async () => "skip");
   return { extensions: resolved.extensions, settingsManager };
 }
@@ -205,8 +199,7 @@ function piEntry(resource: ResolvedResource): ExtensionEntry {
       : fileLabel(path),
     group,
     enabled: resource.enabled,
-    // Scope, not group: a package a project configures is written to the repo's
-    // settings, which a browser toggle never touches.
+    // By scope, not group: project-configured packages live in the repo's settings.
     writable: metadata.scope === "user",
   };
 }

package/packages/core/src/shared/PimSettings.ts

@@ -62,25 +62,24 @@ function load(): Promise<Settings> {
   return loaded;
 }
 
-async function getExaApiKey(): Promise<string | undefined> {
-  return (
-    normalize(process.env["EXA_API_KEY"]) ??
-    normalize((await get("exa")).apiKey)
-  );
+function getExaApiKey(): Promise<string | undefined> {
+  return apiKey("EXA_API_KEY", "exa");
 }
 
-async function getJinaApiKey(): Promise<string | undefined> {
-  return (
-    normalize(process.env["JINA_API_KEY"]) ??
-    normalize((await get("jina")).apiKey)
-  );
+function getJinaApiKey(): Promise<string | undefined> {
+  return apiKey("JINA_API_KEY", "jina");
 }
 
-async function getFirecrawlApiKey(): Promise<string | undefined> {
-  return (
-    normalize(process.env["FIRECRAWL_API_KEY"]) ??
-    normalize((await get("firecrawl")).apiKey)
-  );
+function getFirecrawlApiKey(): Promise<string | undefined> {
+  return apiKey("FIRECRAWL_API_KEY", "firecrawl");
+}
+
+/** The env var wins over the settings file. */
+async function apiKey(
+  envName: string,
+  key: "exa" | "jina" | "firecrawl"
+): Promise<string | undefined> {
+  return normalize(process.env[envName]) ?? normalize((await get(key)).apiKey);
 }
 
 function normalize(value: string | undefined): string | undefined {

package/packages/core/src/shared/Proc.ts

@@ -1,9 +1,9 @@
 export type ProcOptions = {
   readonly cwd?: string | undefined;
   readonly stdout?: "pipe" | "inherit";
-  /** Merged over the process environment; a key set to `undefined` is removed from it. */
+  /** Merged over `process.env`; an `undefined` value removes the key. */
   readonly env?: Readonly<Record<string, string | undefined>>;
-  /** Kills the child once it elapses, answering `timedOut`. */
+  /** Kills the child and sets `timedOut` once elapsed. */
   readonly timeoutMs?: number;
 };
 
@@ -22,7 +22,6 @@ async function run(
     cwd: options.cwd,
     stdout: options.stdout ?? "pipe",
     stderr: "pipe",
-    // `undefined` is Bun's own "inherit this process's environment".
     env:
       options.env === undefined
         ? undefined

package/packages/core/src/shared/RateLimiter.ts

@@ -1,4 +1,4 @@
-export type RateLimiterOptions = {
+type RateLimiterOptions = {
   readonly maxRequests: number;
   readonly windowMs: number;
   readonly now?: () => number;

package/packages/core/src/shared/Renderer.ts

@@ -19,7 +19,7 @@ export type RenderContext = {
   readonly isError: boolean;
 };
 
-export type MarkerStatus = "warning" | "error" | "success";
+type MarkerStatus = "warning" | "error" | "success";
 
 export type PrefixSpec = {
   readonly prefix: string;
@@ -358,14 +358,12 @@ function renderErrorResult(args: {
 export const Renderer = {
   GAPPED_PREFIX,
   TIGHT_PREFIX,
-  markerColorFor,
   firstText,
   extractErrorText,
   toolTitleText,
   makeTitleBlock,
   renderToolCallTitle,
   makePrefixedBlock,
-  markdownLines,
   makeMarkdownBlock,
   renderErrorResult,
 };

package/packages/core/src/shared/RepoDiff.ts

@@ -30,10 +30,10 @@ export type ChangeSummary = {
   readonly added: number;
   readonly removed: number;
   readonly binary?: boolean;
-  /** Blob SHAs the diff was computed against; anchors an outdated review comment. */
+  /** Blob SHAs of each side; used to anchor outdated review comments. */
   readonly baseSha?: string;
   readonly headSha?: string;
-  /** Changes whenever the file's content does, so a `seen` mark keyed to it clears itself. */
+  /** Changes whenever the file's content does. */
   readonly fingerprint: string;
 };
 
@@ -51,14 +51,14 @@ export type FileDiff = {
   readonly hunks: readonly ToolDiffHunk[];
   readonly truncated?: boolean;
   readonly binary?: boolean;
-  /** Byte size of each side of a binary file, when git or the working tree can say. */
+  /** Byte sizes of each side of a binary file, when known. */
   readonly oldBytes?: number;
   readonly newBytes?: number;
-  /** Lines in the side context is read from; absent on a clipped diff, whose end is not the file's. */
+  /** Line count of the side `readLines` reads. Absent when the diff was clipped. */
   readonly total?: number;
 };
 
-/** A stretch of one file, 1-based and inclusive, numbered on the side `readLines` reads. */
+/** 1-based, inclusive, numbered on the side `readLines` reads. */
 export type LineSpan = {
   readonly start: number;
   readonly end: number;
@@ -78,24 +78,24 @@ const DEFAULT_CONTEXT = 3;
 
 const FILE_LIMIT = 2000;
 
-/** How much of one file a reader is handed at once; past either limit the rest is dropped. */
+/** Per-file caps on a diff; the rest is dropped. */
 const CHANGED_LINE_LIMIT = 2000;
 const PATCH_TEXT_LIMIT = 1_000_000;
 
-/** Past this an untracked file is reported as binary rather than read. */
+/** Larger untracked files are reported as binary. */
 const UNTRACKED_BYTE_LIMIT = 1_000_000;
 
-/** Past this a file is diffed but never read whole, so no gap of it can be opened. */
+/** Larger files are diffed but never read whole, so gaps can't be expanded. */
 const CONTEXT_BYTE_LIMIT = 1_000_000;
 
-/** Most lines one `readLines` hands back, however many spans asked. */
+/** Max lines per `readLines` call, across all spans. */
 const CONTEXT_LINE_LIMIT = 2000;
 
 const EMPTY_SHA = /^0+$/;
 
 const BINARY_PATCH = /^(?:Binary files |GIT binary patch)/m;
 
-/** One `git` read; `--no-optional-locks` or it takes `index.lock` and fails an agent's write beside it. */
+/** `--no-optional-locks` keeps reads from taking `index.lock` and failing concurrent writes. */
 function git(cwd: string, args: readonly string[]): Promise<ProcResult> {
   return Proc.run(["git", "--no-optional-locks", ...args], { cwd });
 }
@@ -112,21 +112,13 @@ async function read(
   return result.stdout;
 }
 
-/**
- * Whether the branch checked out has a commit on it. A repository whose first
- * commit is still unwritten has an unborn `HEAD`: it names nothing, and every
- * `git diff HEAD` of it fails outright instead of calling the tree new.
- */
+/** False for an unborn `HEAD` (no commits yet), where `git diff HEAD` fails. */
 async function born(cwd: string): Promise<boolean> {
   const head = await git(cwd, ["rev-parse", "--quiet", "--verify", "HEAD"]);
   return head.code === 0;
 }
 
-/**
- * The base an unborn `HEAD` is diffed against, so that every file reads as
- * added. `hash-object` names git's empty tree without writing it, and names it
- * right in a sha256 repository too, where the familiar `4b825dc…` is not it.
- */
+/** Base for an unborn `HEAD`. `hash-object` also gets it right in sha256 repos. */
 async function emptyTree(cwd: string): Promise<string> {
   const sha = await read(
     cwd,
@@ -136,7 +128,7 @@ async function emptyTree(cwd: string): Promise<string> {
   return sha.trim();
 }
 
-/** What every `git diff` of this base is asked about; `branch` resolves to the merge base first. */
+/** `git diff` args for a base; `branch` diffs against the merge base. */
 async function baseArgs(
   cwd: string,
   base: DiffBase
@@ -151,7 +143,6 @@ async function baseArgs(
     case "commit":
       return [base.ref];
     case "branch": {
-      // Nothing is shared with a branch when this one has no commits at all.
       if (!(await born(cwd))) {
         return [await emptyTree(cwd)];
       }
@@ -199,7 +190,7 @@ function shaOf(value: string | undefined): string | undefined {
     : value;
 }
 
-/** `:<oldmode> <newmode> <oldsha> <newsha> <status>\0<path>\0`, a second path when the status is a rename or copy. */
+/** `:<oldmode> <newmode> <oldsha> <newsha> <status>\0<path>\0`, plus a second path for a rename or copy. */
 function parseRaw(text: string): readonly Entry[] {
   const fields = text.split("\0");
   const entries: Entry[] = [];
@@ -240,7 +231,7 @@ function parseRaw(text: string): readonly Entry[] {
   return entries;
 }
 
-/** `<added>\t<removed>\t<path>\0`; a rename leaves the path empty and follows with the old and new ones. */
+/** `<added>\t<removed>\t<path>\0`; a rename has an empty path followed by old and new paths. */
 function parseNumstat(text: string): ReadonlyMap<string, Counts> {
   const fields = text.split("\0");
   const counts = new Map<string, Counts>();
@@ -278,7 +269,7 @@ function parseNumstat(text: string): ReadonlyMap<string, Counts> {
   return counts;
 }
 
-/** Only the `?` entries of porcelain v2; a rename entry carries a second field that is a path, not a record. */
+/** The `?` entries of porcelain v2. A rename (`2`) entry is followed by an extra path field. */
 function parseUntracked(text: string): readonly string[] {
   const fields = text.split("\0");
   const paths: string[] = [];
@@ -332,10 +323,7 @@ async function readUntracked(cwd: string, path: string): Promise<Untracked> {
     return opaque;
   }
   const bytes = await file.bytes().catch(() => undefined);
-  if (bytes === undefined) {
-    return opaque;
-  }
-  if (Lines.isBinaryBytes(bytes)) {
+  if (bytes === undefined || Lines.isBinaryBytes(bytes)) {
     return opaque;
   }
   const text = new TextDecoder().decode(bytes);
@@ -446,7 +434,7 @@ type Clip = {
   readonly truncated: boolean;
 };
 
-/** The longest prefix of a patch that is still whole hunks, once it is too much text to parse. */
+/** Cuts an oversized patch back to its last whole hunk. */
 function clipPatch(patch: string): {
   readonly text: string;
   readonly cut: boolean;
@@ -462,7 +450,7 @@ function changedOf(lines: readonly ToolDiffLine[]): number {
   return lines.filter((line) => line.kind !== "context").length;
 }
 
-/** A hunk cut short still has to describe itself: its spans count the lines left in it. */
+/** Recounts a cut hunk's line spans. */
 function reflow(
   hunk: ToolDiffHunk,
   lines: readonly ToolDiffLine[]
@@ -493,7 +481,7 @@ function headOf(
   return kept;
 }
 
-/** Hunks while the changed-line budget lasts, the one that overruns it cut short. */
+/** Keeps hunks within the changed-line budget, cutting the one that overruns it. */
 function clipHunks(hunks: readonly ToolDiffHunk[]): Clip {
   let budget = CHANGED_LINE_LIMIT;
   const kept: ToolDiffHunk[] = [];
@@ -531,11 +519,7 @@ function clipped(
   };
 }
 
-/**
- * The text of the side a gap is read from: the new one, which is the index
- * blob where the base has staged it and the working tree everywhere else. A
- * file too big to hold, or gone from the side asked for, has no text at all.
- */
+/** The new side: the index blob when staged, else the working tree. Undefined if missing or too big. */
 async function sideText(
   cwd: string,
   path: string,
@@ -578,7 +562,6 @@ async function worktreeSize(
   return (await file.exists()) ? file.size : undefined;
 }
 
-/** A binary file is a row, not a diff: all a reader is told is how big each side is. */
 async function binaryDiff(
   cwd: string,
   path: string,
@@ -599,7 +582,7 @@ async function binaryDiff(
   };
 }
 
-/** Every changed file of one base, in git's own order and without a hunk of any of them. */
+/** Changed files in git's order, without hunks. */
 async function listChanges(
   cwd: string,
   base: DiffBase,
@@ -629,7 +612,7 @@ async function listChanges(
   });
 }
 
-/** One file's hunks; a renamed file is diffed against the path it came from, an untracked one against nothing. */
+/** A rename is diffed against its old path; an untracked file against nothing. */
 async function fileDiff(
   cwd: string,
   base: DiffBase,
@@ -679,7 +662,6 @@ async function fileDiff(
   });
 }
 
-/** The lines a reader asked to see of a file they are already reading a diff of, as they are. */
 async function readLines(
   cwd: string,
   base: DiffBase,
@@ -718,11 +700,7 @@ async function readLines(
   });
 }
 
-/**
- * Reading is serialised against the checkouts and pulls that move the tree
- * under it; a read that arrives while one runs is refused rather than answered
- * from half a working tree.
- */
+/** Refuses to read while a checkout or pull is moving the tree. */
 async function serialise<T>(
   monitor: GitMonitor,
   cwd: string,

package/packages/core/src/shared/SearchRender.ts

@@ -3,9 +3,9 @@ import { Paths } from "./Paths";
 
 export const NO_MATCHES = "No matches.";
 
-export type SearchPathFormat = "relative" | "absolute";
+type SearchPathFormat = "relative" | "absolute";
 
-export type SearchPathOptions = {
+type SearchPathOptions = {
   readonly cwd: string;
   readonly pathFormat: SearchPathFormat;
 };
@@ -17,7 +17,7 @@ export type SearchList = {
   readonly truncated: boolean;
 };
 
-export type SubjectTitleOptions = {
+type SubjectTitleOptions = {
   readonly subject: string;
   readonly path: string | undefined;
   readonly suffix?: string | undefined;
@@ -75,7 +75,6 @@ function capList(lines: readonly string[], headLimit: number): SearchList {
 }
 
 export const SearchRender = {
-  NO_MATCHES,
   formatPath,
   subjectTitle,
   capList,

package/packages/core/src/shared/SpillCache.ts

@@ -5,7 +5,7 @@ import { FsErrors } from "./FsErrors";
 import { Paths } from "./Paths";
 import { Sweeper } from "./Sweeper";
 
-// UUIDv7-named spills and content-addressed ones, which share the TTL.
+// Matches UUIDv7-named and SHA-256-named spills.
 const SPILL_FILE_RE =
   /^[a-z0-9]+-(?:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[0-9a-f]{64})\.[a-z0-9]+$/;
 
@@ -16,7 +16,7 @@ function dir(): string {
   return join(Paths.pimHomeDir(), "cache");
 }
 
-/** Writes under a caller-chosen name; an existing file of that name is kept, so content-addressed names re-write for free. */
+/** Keeps an existing file of the same name; returns its path either way. Null on failure. */
 async function writeNamed(
   name: string,
   data: string | Uint8Array
@@ -69,7 +69,6 @@ function installSweeper(): void {
 
 export const SpillCache = {
   TTL_MS,
-  SWEEP_INTERVAL_MS,
   dir,
   write,
   writeNamed,

package/packages/core/src/shared/SubagentLogs.ts

@@ -4,15 +4,14 @@ import { dirname, join } from "node:path";
 import { Paths } from "./Paths";
 import { Sweeper } from "./Sweeper";
 
-// The parent id names a directory; a call id is opaque provider data, hashed rather than trusted as a segment.
+// Parent ids become directory names; call ids are untrusted, so they are hashed.
 const ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
-// A call id arrives off the wire: bound what gets hashed.
 const MAX_CALL_ID_LENGTH = 4096;
 
 const TTL_MS = 30 * 24 * 60 * 60 * 1000;
 const SWEEP_INTERVAL_MS = 60 * 60 * 1000;
 
-// Must stay outside pi's sessions root, which `SessionRegistry` globs as the session catalogue.
+// Must stay outside pi's sessions root, which `SessionRegistry` globs.
 function dir(): string {
   return join(Paths.pimHomeDir(), "subagents");
 }
@@ -32,7 +31,7 @@ function pathFor(parentSessionId: string, callId: string): string | null {
   );
 }
 
-// Create the log empty with explicit modes: a file pi creates takes the process umask.
+// Created up front with private modes; pi would use the umask.
 async function create(
   parentSessionId: string,
   callId: string
@@ -50,7 +49,7 @@ async function create(
   }
 }
 
-// Expire a parent's children together by newest mtime, or a long run loses its earlier subagents.
+// Expires a parent's logs together, by their newest mtime.
 function cleanup(root = dir(), now = Date.now()): void {
   let names: string[];
   try {
@@ -93,7 +92,6 @@ function installSweeper(): void {
 
 export const SubagentLogs = {
   TTL_MS,
-  SWEEP_INTERVAL_MS,
   dir,
   pathFor,
   create,

package/packages/core/src/shared/Supervisor.ts

@@ -5,29 +5,28 @@ import { basename, dirname, join } from "node:path";
 import { Fs } from "./Fs";
 import { Proc } from "./Proc";
 
-// Set by the units this file writes and by nothing else: it tells a daemon an exit is a restart.
+// Set only by the units written here: tells a daemon that exiting means restarting.
 const SUPERVISED_ENV = "PIM_SUPERVISED";
 
-/** One daemon the supervisor manages, named by the `--mode` it is started with. */
+/** A supervised daemon, named by its `--mode`. */
 export type Unit = {
   readonly mode: string;
   readonly description: string;
   readonly args?: ReadonlyArray<string>;
 };
 
-/** One reversible act of an install: everything a unit's removal is made of. */
-export type UnitStep =
+type UnitStep =
   | { readonly kind: "run"; readonly cmd: ReadonlyArray<string> }
   | { readonly kind: "remove"; readonly path: string };
 
-/** Which init system, and whose home — named so a test can ask about the other platform. */
-export type UnitPlace = {
+/** Overridable so tests can target the other platform. */
+type UnitPlace = {
   readonly platform: NodeJS.Platform;
   readonly home: string;
 };
 
-export type InstallOptions = {
-  /** Units this one replaces: stopped and removed before it is written. */
+type InstallOptions = {
+  /** Stopped and removed before the new unit is written. */
   readonly replaces?: ReadonlyArray<Unit>;
 };
 
@@ -44,7 +43,7 @@ async function install(
 ): Promise<void> {
   const at = await detectInstall();
   console.log(`[install] ${at.kind} mode, root=${at.packageRoot}`);
-  // Strictly before the new unit exists: two daemons must never share a token or a port.
+  // First, so two daemons never share a token or port.
   await supersede(options.replaces ?? []);
   if (process.platform === "linux") {
     const path = systemdUnitPath(unit);
@@ -79,7 +78,7 @@ async function install(
         `gui/${uid}/${launchdLabel(unit)}`,
       ]);
     } catch {
-      // bootout fails when the service isn't loaded; ignore before bootstrap.
+      // Fails when not loaded.
     }
     await runOrThrow(["launchctl", "bootstrap", `gui/${uid}`, path]);
     console.log(`[install] bootstrapped ${launchdLabel(unit)}`);
@@ -95,10 +94,7 @@ async function uninstall(unit: Unit): Promise<void> {
   await runSteps(uninstallSteps(unit), "uninstall");
 }
 
-/**
- * Stop and remove every one of `units` that is installed, saying so. Idempotent:
- * a unit that was never installed, or is already stopped, costs a stat and a line.
- */
+/** Stops and removes whichever of `units` are installed. Idempotent. */
 async function supersede(
   units: ReadonlyArray<Unit>,
   where: Partial<UnitPlace> = {}
@@ -111,7 +107,7 @@ async function supersede(
   }
 }
 
-/** Which of `units` this machine currently has a unit file for. */
+/** The `units` that have a unit file on this machine. */
 async function installedAmong(
   units: ReadonlyArray<Unit>,
   where: Partial<UnitPlace> = {}
@@ -122,10 +118,7 @@ async function installedAmong(
   return units.filter((_, index) => present[index]);
 }
 
-/**
- * The argv the installed unit starts the daemon with, empty when it is not
- * installed: what a re-install has to preserve rather than quietly drop.
- */
+/** The installed unit's argv from `--mode` on; empty when not installed. */
 async function installedArgs(
   unit: Unit,
   where: Partial<UnitPlace> = {}
@@ -135,7 +128,6 @@ async function installedArgs(
     .text()
     .catch(() => "");
   const words = unitWords(text, at.platform);
-  // Everything before `--mode` is the interpreter and the entry point.
   const mode = words.indexOf("--mode");
   return mode < 0 ? [] : words.slice(mode);
 }
@@ -155,7 +147,7 @@ function unitWords(
     .filter((word) => word.length > 0);
 }
 
-/** Everything removing `unit` is made of, in the order it has to happen. */
+/** Ordered steps to remove `unit`. */
 function uninstallSteps(
   unit: Unit,
   where: Partial<UnitPlace> = {}
@@ -179,8 +171,7 @@ function uninstallSteps(
   ];
 }
 
-// A step that fails is reported, never fatal: an already-stopped unit still has
-// to lose its file, and a file already gone still has to trigger a reload.
+// Failed commands only warn, so later steps still run.
 async function runSteps(
   steps: ReadonlyArray<UnitStep>,
   label: string
@@ -208,7 +199,7 @@ async function runSteps(
   }
 }
 
-/** Only a supervisor turns an exit into a restart; unsupervised it is a stop. */
+/** Unsupervised, an exit is a stop rather than a restart. */
 function isSupervised(): boolean {
   const flag = Bun.env[SUPERVISED_ENV];
   return flag !== undefined && flag !== "" && flag !== "0";
@@ -218,7 +209,7 @@ function restart(): never {
   process.exit(0);
 }
 
-// A global install replaces every daemon's tree: restart the siblings or they run old code.
+// After a global update, other daemons must restart or they keep running old code.
 async function restartSiblings(self: Unit): Promise<void> {
   if (process.platform === "linux") {
     for (const name of await installedUnits(
@@ -277,7 +268,7 @@ async function restartOrWarn(
 
 async function detectInstall(): Promise<Install> {
   const here = await realpath(Bun.fileURLToPath(import.meta.url));
-  // Start above the workspace packages so the walk lands on the published root.
+  // Start above `packages/` so the walk finds the published root.
   const packageRoot = await findPackageRoot(
     join(dirname(here), "..", "..", "..", "..")
   );
@@ -349,7 +340,6 @@ function launchdPlistPath(unit: Unit, at: UnitPlace = place()): string {
   return join(launchAgentsDir(at), `${launchdLabel(unit)}.plist`);
 }
 
-/** Where this platform keeps `unit`'s definition, installed or not. */
 function unitFile(unit: Unit, where: Partial<UnitPlace> = {}): string {
   const at = place(where);
   return at.platform === "darwin"
@@ -432,11 +422,8 @@ async function lingerEnabled(): Promise<boolean> {
   return code === 0 && stdout.includes("Linger=yes");
 }
 
-async function runOrThrow(
-  cmd: ReadonlyArray<string>,
-  cwd?: string
-): Promise<void> {
-  const { code, stderr } = await Proc.run(cmd, { cwd, stdout: "inherit" });
+async function runOrThrow(cmd: ReadonlyArray<string>): Promise<void> {
+  const { code, stderr } = await Proc.run(cmd, { stdout: "inherit" });
   if (code !== 0) {
     throw new Error(
       `${cmd.join(" ")} exit ${code}: ${stderr.trim() || "(no stderr)"}`

package/packages/core/src/shared/Surface.ts

@@ -1,2 +1,2 @@
-/** Where the human on the other end is reading; absent for a subagent, which has no human. */
+/** Where the user is reading. Absent for a subagent. */
 export type Surface = "terminal" | "web browser" | "Telegram";

package/packages/core/src/shared/Sweeper.ts

@@ -18,7 +18,7 @@ function install(options: {
     cleanup();
   });
 
-  // Signals skip the "exit" handler; re-raise after the once-handler, or the default exit is suppressed.
+  // Signals skip "exit": clean up, then re-raise so the process still dies.
   for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"] as const) {
     process.once(sig, () => {
       try {