pim-agent 0.13.0 → 0.14.0

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

@@ -12,30 +12,29 @@ import { BodyRenderer } from "../view/BodyRenderer";
 import type { ToolView } from "../view/ViewBlock";
 
 export type ToolViewInput<TParams extends TSchema, TDetails> = {
-  /** Partially streamed while the call is in flight; treat fields as optional. */
+  /** Partial while streaming; treat fields as optional. */
   readonly args: Static<TParams>;
-  /** A streaming snapshot rather than the final result while `isPartial`. */
+  /** A snapshot, not the final result, while `isPartial`. */
   readonly result?: AgentToolResult<TDetails>;
   readonly isPartial: boolean;
   readonly cwd: string;
 };
 
-/** What a call to this tool can do to the host machine; declaring nothing means `unbounded`. */
-export type ToolEffect<TParams extends TSchema = TSchema> =
+/** What a call can do to the host machine. */
+type ToolEffect<TParams extends TSchema = TSchema> =
   | { readonly kind: "readOnly" }
   | {
       readonly kind: "writesPaths";
-      /** Paths as the model wrote them; throwing means "unknown" and is treated as `unbounded`. */
+      /** Paths as the model wrote them. Throwing is treated as `unbounded`. */
       readonly paths: (args: Static<TParams>) => readonly string[];
     }
   | { readonly kind: "unbounded" };
 
-/** `ToolEffect` with its parameter type erased, for name-keyed lookup. */
-export type ErasedToolEffect = ToolEffect<TSchema> & {
+type ErasedToolEffect = ToolEffect<TSchema> & {
   readonly paths?: (args: unknown) => readonly string[];
 };
 
-/** Pi's tool definition plus pim's view model, which must be pure over `(args, result, cwd)` to replay. */
+/** `toViewModel` must be pure over `(args, result, cwd)` so sessions can replay. */
 export type PimToolDefinition<
   TParams extends TSchema,
   TDetails = unknown,
@@ -46,13 +45,14 @@ export type PimToolDefinition<
   readonly effect?: ToolEffect<TParams>;
 };
 
-/** A registered `toViewModel` with its parameter types erased, for name-keyed lookup. */
-export type ToolViewFactory = (input: {
+type ViewCall = {
   readonly args: unknown;
   readonly result?: AgentToolResult<unknown>;
   readonly isPartial: boolean;
   readonly cwd: string;
-}) => ToolView;
+};
+
+type ToolViewFactory = (input: ViewCall) => ToolView;
 
 type ViewRenderState<TDetails> = {
   viewResult?: AgentToolResult<TDetails>;
@@ -73,20 +73,12 @@ type JsonSchema = {
 const viewFactories = new Map<string, ToolViewFactory>();
 const effects = new Map<string, ErasedToolEffect>();
 
-/** What a registered tool declared it can do; absent reads as `unbounded`. */
+/** Undefined means `unbounded`. */
 function effectOf(toolName: string): ErasedToolEffect | undefined {
   return effects.get(toolName);
 }
 
-function baseView(
-  toolName: string,
-  call: {
-    readonly args: unknown;
-    readonly result?: AgentToolResult<unknown>;
-    readonly isPartial: boolean;
-    readonly cwd: string;
-  }
-): ToolView {
+function baseView(toolName: string, call: ViewCall): ToolView {
   return (
     viewFactories.get(toolName)?.(call) ?? genericView(toolName, call.args)
   );
@@ -95,7 +87,7 @@ function baseView(
 const branchesOf = (schema?: JsonSchema): readonly JsonSchema[] | undefined =>
   schema?.anyOf ?? schema?.oneOf;
 
-/** The view for one call, with a generic fallback for a tool that registered none. */
+/** Falls back to a generic view for tools without a view model. */
 function viewOf(input: {
   readonly name: string;
   readonly args: unknown;
@@ -116,11 +108,7 @@ function viewOf(input: {
 
 function errorView(
   name: string,
-  call: {
-    readonly args: unknown;
-    readonly isPartial: boolean;
-    readonly cwd: string;
-  },
+  call: Omit<ViewCall, "result">,
   result: AgentToolResult<unknown> | undefined
 ): ToolView {
   const view = baseView(name, call);
@@ -135,7 +123,7 @@ function errorView(
   };
 }
 
-/** Wrap a tool definition so pi's validator errors are rewritten before reaching the model. */
+/** Registers pim-only fields and rewrites pi's validation errors into clearer ones. */
 function wrap<TParams extends TSchema, TDetails = unknown, TState = unknown>(
   def: PimToolDefinition<TParams, TDetails, TState>
 ): ToolDefinition<TParams, TDetails, TState> {
@@ -192,7 +180,6 @@ function register<
   pi.registerTool(wrap(def));
 }
 
-/** Rewrite a `validateToolArguments` error string into a clearer form. */
 function rewriteValidationError(
   toolName: string,
   schema: JsonSchema,
@@ -271,7 +258,7 @@ function synthesizeRenderers<TParams extends TSchema, TDetails, TState>(
       def.renderResult ??
       ((result, options, theme, context) => {
         const state = context.state as ViewRenderState<TDetails>;
-        // Defer the redraw: invalidating re-entrantly makes pi paint the body twice.
+        // Deferred: a re-entrant invalidate makes pi paint the body twice.
         if (!options.isPartial && state.viewResult === undefined) {
           state.viewResult = result;
           queueMicrotask(() => context.invalidate());

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

@@ -8,7 +8,7 @@ import { Supervisor, type Install } from "./Supervisor";
 
 const STAGING = "staging";
 
-// Relative to `packages/web`: the vite root `web:build` cds into.
+// Relative to `packages/web`, the vite root.
 const STAGING_OUT_DIR = `dist/${STAGING}`;
 
 type ClientDirs = {
@@ -17,7 +17,6 @@ type ClientDirs = {
   readonly previous: string;
 };
 
-/** A spawned command, or filesystem work — never both. */
 export type UpdateStep =
   | {
       readonly label: string;
@@ -26,14 +25,14 @@ export type UpdateStep =
     }
   | { readonly label: string; readonly act: () => Promise<void> };
 
-/** Work the plan declined to do; `blocking` means the run did less than asked. */
+/** `blocking` means the update did less than asked. */
 export type UpdateSkip = {
   readonly label: string;
   readonly reason: string;
   readonly blocking: boolean;
 };
 
-export type UpdatePlan = {
+type UpdatePlan = {
   readonly steps: ReadonlyArray<UpdateStep>;
   readonly skipped: ReadonlyArray<UpdateSkip>;
 };
@@ -41,24 +40,24 @@ export type UpdatePlan = {
 export type UpdateFacts = {
   readonly at: Install;
   readonly packageName: string;
-  /** A dev checkout with no uncommitted changes; irrelevant to a prod install. */
+  /** Dev only: no uncommitted changes. */
   readonly cleanTree: boolean;
-  /** The dev checkout's branch tracks a remote one, so a pull has somewhere to pull from; irrelevant to a prod install. */
+  /** Dev only: the branch has an upstream. */
   readonly tracked: boolean;
-  /** The newest published release, or undefined when the registry was silent. */
+  /** Undefined when the registry could not be reached. */
   readonly latest: string | undefined;
 };
 
 export type UpdateOutcome = {
   readonly ok: boolean;
   readonly from: string;
-  /** Re-read from disk after the steps ran, never the version that was asked for. */
+  /** Re-read from disk after the steps ran. */
   readonly to: string;
   readonly skipped: ReadonlyArray<UpdateSkip>;
   readonly error: string | undefined;
 };
 
-export type UpdateOptions = {
+type UpdateOptions = {
   readonly onStep?: (label: string) => void | Promise<void>;
 };
 
@@ -71,7 +70,7 @@ function clientDirs(packageRoot: string): ClientDirs {
   };
 }
 
-// `vite build` empties its outDir: build to staging and swap, or a failed build deletes the live bundle.
+// `vite build` empties its outDir, so build to staging and swap; a failed build keeps the live bundle.
 async function swapClient(packageRoot: string): Promise<void> {
   const dirs = clientDirs(packageRoot);
   await rm(dirs.previous, { recursive: true, force: true });
@@ -83,7 +82,6 @@ async function swapClient(packageRoot: string): Promise<void> {
   await rename(dirs.staging, dirs.client);
 }
 
-/** Why this checkout cannot be pulled, or undefined when it can. */
 function pullBlocker(facts: UpdateFacts): string | undefined {
   if (!facts.tracked) {
     return "this branch has no upstream to pull from";
@@ -137,11 +135,11 @@ function plan(facts: UpdateFacts): UpdatePlan {
       blocking: true,
     });
   } else {
-    // Install the exact version, never `@latest`: a tag cannot be reported truthfully.
+    // Exact version, not `@latest`, so the reported version is accurate.
     steps.push({
       label: `install ${packageName}@${latest}`,
       command: ["bun", "install", "-g", `${packageName}@${latest}`],
-      // No cwd: a global install must not adopt the tree it is replacing.
+      // No cwd: the global install must not run inside the tree it replaces.
       cwd: undefined,
     });
   }
@@ -156,14 +154,16 @@ async function gather(): Promise<UpdateFacts> {
       ? Git.fetchStatus(at.packageRoot).then((git) => git.dirtyCount === 0)
       : Promise.resolve(true),
     at.kind === "dev"
-      ? Git.upstreamOf(at.packageRoot).then((at) => at !== undefined)
+      ? Git.upstreamOf(at.packageRoot).then(
+          (upstream) => upstream !== undefined
+        )
       : Promise.resolve(true),
     at.kind === "prod" ? PimVersion.latest() : Promise.resolve(undefined),
   ]);
   return { at, packageName, cleanTree, tracked, latest };
 }
 
-/** Never restarts or exits: the caller owns that. */
+/** Never restarts or exits; that's the caller's job. */
 async function run(options: UpdateOptions = {}): Promise<UpdateOutcome> {
   const from = await PimVersion.current();
   const { steps, skipped } = plan(await gather());

package/packages/core/src/view/BodyRenderer.ts

@@ -98,5 +98,5 @@ const SUMMARY_BUILDERS: FrameBuilders = {
   flow: gutter(Renderer.GAPPED_PREFIX),
 };
 
-/** Turns painted body lines into the pi-tui components that frame them. */
+/** Renders view blocks into pi-tui components. */
 export const BodyRenderer = { render };

package/packages/core/src/view/DiffBlocks.ts

@@ -48,5 +48,4 @@ function fileView(args: {
   };
 }
 
-/** View-model fragments shared by every tool that reports a file diff. */
 export const DiffBlocks = { statSpans, stats, body, fileView };

package/packages/core/src/view/DiffExpand.ts

@@ -1,11 +1,7 @@
 import type { ToolDiffHunk, ToolDiffLine } from "../shared/DiffLines";
 import type { LineSpan } from "../shared/RepoDiff";
 
-/**
- * A stretch of a file neither side changed and no hunk shows, numbered on the
- * new side. `above` and `below` say which ends of it sit against a hunk, which
- * is where a reader asking for more of it is given it.
- */
+/** Unchanged lines no hunk shows, in new-side numbers. `above`/`below`: that end touches a hunk. */
 export type DiffGap = {
   readonly start: number;
   readonly end: number;
@@ -14,7 +10,7 @@ export type DiffGap = {
   readonly below: boolean;
 };
 
-/** What a diff is painted from, top to bottom: hunks and the gaps between them. */
+/** Hunks and gaps in display order. */
 export type DiffPart =
   | { readonly hunk: ToolDiffHunk }
   | { readonly gap: DiffGap };
@@ -22,7 +18,7 @@ export type DiffPart =
 /** Lines one click reveals at each end of a gap. */
 const STEP = 25;
 
-/** A remainder this small is taken with the click rather than left as a row of its own. */
+/** A smaller remainder is revealed with the click instead of left as its own gap. */
 const MIN_REMAINDER = 10;
 
 function newEnd(hunk: ToolDiffHunk): number {
@@ -44,11 +40,7 @@ function gapOf(
     : [{ start, end, count: end - start + 1, above, below }];
 }
 
-/**
- * Every gap in one file's hunks: before the first, between each pair, and
- * after the last once `total` says where the file ends. A file with no new
- * side to number has none of them.
- */
+/** Gaps before, between and (given `total` lines) after the hunks. */
 function gaps(
   hunks: readonly ToolDiffHunk[],
   total?: number
@@ -71,10 +63,7 @@ function gaps(
   ];
 }
 
-/**
- * What to ask the server for when a reader opens a gap: a step against each
- * hunk it touches, or the whole gap when what would be left of it is a sliver.
- */
+/** Line spans to fetch when a gap is opened: `STEP` lines at each hunk-facing end, or the whole gap if little would remain. */
 function spans(gap: DiffGap): readonly LineSpan[] {
   const edges = (gap.above ? 1 : 0) + (gap.below ? 1 : 0);
   if (gap.count <= edges * STEP + MIN_REMAINDER) {
@@ -86,7 +75,7 @@ function spans(gap: DiffGap): readonly LineSpan[] {
   ];
 }
 
-/** How many lines opening a gap would put on the page. */
+/** Lines that opening `gap` would reveal. */
 function revealed(gap: DiffGap): number {
   return spans(gap).reduce(
     (total, span) => total + span.end - span.start + 1,
@@ -94,15 +83,13 @@ function revealed(gap: DiffGap): number {
   );
 }
 
-/** The hunks with each gap in its place among them. */
 function parts(
   hunks: readonly ToolDiffHunk[],
   total?: number
 ): readonly DiffPart[] {
   const found = gaps(hunks, total);
   const tail = found.find((gap) => !gap.below);
-  // Keyed by the line a gap ends on, which is the line before the hunk it
-  // leads into: one lookup per hunk rather than a scan of every gap.
+  // Keyed by end line, i.e. the line before the hunk it leads into.
   const leading = new Map(found.map((gap) => [gap.end, gap]));
   return [
     ...hunks.flatMap((hunk) => {
@@ -117,7 +104,7 @@ type Run = {
   readonly oldStart: number;
   readonly newStart: number;
   readonly lines: ToolDiffLine[];
-  /** Lines of the run that stand on the new side, counted as they are added. */
+  /** New-side line count. */
   newCount: number;
 };
 
@@ -140,10 +127,8 @@ function hunkOf(run: Run): ToolDiffHunk {
 }
 
 /**
- * The hunks with every line a reader has since been given spliced back into
- * the gaps around them, and hunks that now touch merged into one. Only lines
- * running from a hunk's own edge are taken: an island in the middle of a gap
- * is not a thing this ever asks for.
+ * Splices `known` lines (by new-side number) into the hunks as context and
+ * merges hunks that now touch. Only lines contiguous with a hunk edge are used.
  */
 function expand(
   hunks: readonly ToolDiffHunk[],

package/packages/core/src/view/DiffLayout.ts

@@ -6,7 +6,7 @@ function detab(text: string): string {
   return text.replace(/\t/g, TAB);
 }
 
-// Highlight each side as one block, never line by line, or multi-line strings and comments mis-tokenise.
+/** Highlights each side as one block so multi-line strings and comments tokenise correctly. */
 function mapSides<T>(
   lines: readonly ToolDiffLine[],
   highlight: (block: string) => readonly T[]
@@ -17,7 +17,7 @@ function mapSides<T>(
   const newBlock: string[] = [];
 
   for (const line of lines) {
-    // A context line must hold a slot in both blocks to keep tokeniser state aligned.
+    // Context lines go into both sides.
     if (line.kind !== "added") {
       oldIndices.push(oldBlock.length);
       oldBlock.push(line.text);

package/packages/core/src/view/DiffPairs.ts

@@ -1,6 +1,6 @@
 import type { ToolDiffHunk, ToolDiffLine } from "../shared/DiffLines";
 
-/** One row of a split view: the old side, the new side, or both. */
+/** One split-view row. */
 export type DiffPair = {
   readonly left?: ToolDiffLine;
   readonly right?: ToolDiffLine;
@@ -32,7 +32,7 @@ function pair(hunk: ToolDiffHunk): readonly DiffPair[] {
       continue;
     }
 
-    // A removal after an addition starts a new replacement rather than joining the last.
+    // A removal after an addition starts a new replacement block.
     if (added.length > 0) {
       zip();
     }

package/packages/core/src/view/MarkdownPainter.ts

@@ -13,14 +13,6 @@ import type {
 
 type Mode = "inline" | "block";
 
-/** How a block sits in a body; `embed` payloads must never be re-wrapped. */
-export type MarkdownFrame = "flow" | "embed" | "heading";
-
-export type MarkdownGroup = {
-  readonly frame: MarkdownFrame;
-  readonly lines: readonly string[];
-};
-
 export type PaintedTool = {
   readonly icon: string;
   readonly lines: readonly string[];
@@ -50,20 +42,13 @@ function paintInline(blocks: readonly ViewBlock[]): string {
     .join(" ");
 }
 
-function paintBody(blocks: readonly ViewBlock[]): MarkdownGroup[] {
-  return Painting.groupByFrame(blocks, Painting.FRAMES).map((group) => ({
-    frame: group.frame,
-    lines: group.blocks.flatMap((block) => paintBlock(block, "block")),
-  }));
-}
-
 function icon(toolIcon: ToolIcon | undefined): string {
   return toolIcon === undefined ? DEFAULT_ICON : ICONS[toolIcon];
 }
 
 function paintTool(view: ToolView): PaintedTool {
   const head = [view.title, view.summary ?? []]
-    .map((blocks) => paintInline(blocks))
+    .map(paintInline)
     .filter((text) => text !== "")
     .join(" ");
   const outline = outlined(view.body ?? []).flatMap((block) =>
@@ -76,7 +61,7 @@ function paintTool(view: ToolView): PaintedTool {
   };
 }
 
-/** A chat row carries a body's headings and any payload that fits a line; an embedded one needs a screen. */
+/** Body blocks shown in a chat row: headings and single-line payloads. */
 function outlined(blocks: readonly ViewBlock[]): readonly ViewBlock[] {
   return blocks.filter((block) => {
     const frame = Painting.FRAMES[block.kind];
@@ -308,7 +293,5 @@ export const MarkdownPainter = {
   escape,
   paint,
   paintInline,
-  paintBody,
-  icon,
   paintTool,
 };

package/packages/core/src/view/MovePath.ts

@@ -1,29 +1,16 @@
-/**
- * A file that moved, read as one path rather than two. Everything the old and
- * new paths agree on is said once, and only the segments that actually changed
- * are named on both sides — `packages/{web ➝ tui}/src/App.tsx` rather than two
- * near-identical paths a reader has to diff by eye.
- */
+/** A move split for display as `packages/{web ➝ tui}/src/App.tsx`. */
 export type MoveParts = {
-  /** The leading directories both paths share, with its trailing `/`. */
+  /** Shared leading segments, with a trailing `/`. */
   readonly prefix: string;
-  /** What those segments used to be. */
   readonly from: string;
-  /** What they are now. */
   readonly to: string;
-  /** The trailing segments both paths share, with its leading `/`. */
+  /** Shared trailing segments, with a leading `/`. */
   readonly suffix: string;
 };
 
-/** The arrow every surface draws a move with. */
 const ARROW = "➝";
 
-/**
- * The shared head and tail of a move, or `undefined` when there is nothing
- * worth folding: two paths that share no segment read better whole, since a
- * brace around the entire path only adds punctuation. Two bare filenames are
- * the exception — `{old.ts ➝ new.ts}` shares no segment but is still one name.
- */
+/** Undefined when the paths share no segment, unless both are bare filenames. */
 function fold(oldPath: string, newPath: string): MoveParts | undefined {
   const oldParts = oldPath.split("/");
   const newParts = newPath.split("/");

package/packages/core/src/view/Painting.ts

@@ -22,7 +22,7 @@ function dispatch<TOut, TArgs extends readonly unknown[]>(
   return painter(block, ...args);
 }
 
-/** How a block sits in its container: `embed` must not be restyled or re-wrapped, `tight` paints its own leading column. */
+/** `embed` is never restyled or re-wrapped; `tight` paints its own leading column. */
 export type BlockFrame = "flow" | "embed" | "tight" | "heading";
 
 const FRAMES = {
@@ -41,7 +41,7 @@ const FRAMES = {
   notice: "flow",
 } as const satisfies Record<ViewBlock["kind"], BlockFrame>;
 
-/** What a block is to the tool that emitted it: its result, or the chrome around one. */
+/** Whether a block is the tool's result or the chrome around it. */
 export type BlockWeight = "payload" | "chrome";
 
 const WEIGHT = {
@@ -107,12 +107,12 @@ function linkLabel(block: {
     : block.label;
 }
 
-/** What a painter that cannot draw the picture says instead: `[image 1200×800 png · 240 KB]`. */
+/** Text fallback, e.g. `[image 1200×800 png · 240 KB]`. */
 function imageSummary(block: BlockOf<"image">): string {
   return `[image ${block.width}×${block.height} ${ImageMime.extensionOf(block.mimeType)} · ${Format.bytes(block.bytes)}]`;
 }
 
-/** The picture plus what it cannot show about itself; `extra` is whatever only the calling tool knows. */
+/** The image block plus a kv block of its details; `extra` is appended to the pairs. */
 function imageBlocks(
   details: ImageDetails,
   alt: string,

package/packages/core/src/view/ViewBlock.ts

@@ -41,11 +41,10 @@ export type KvPair = readonly [string, string];
 
 export type ViewBlock =
   | { readonly kind: "text"; readonly text: string; readonly tone?: Tone }
-  /** Markdown source; framed as an embed and never re-coloured or re-wrapped. */
+  /** Never re-coloured or re-wrapped. */
   | { readonly kind: "markdown"; readonly text: string }
-  /** One line of mixed-tone text, e.g. a `+5`/`-2` diff stat or a rename. */
+  /** One line of mixed-tone text, e.g. a `+5`/`-2` diff stat. */
   | { readonly kind: "spans"; readonly spans: readonly Span[] }
-  /** Introduces a sub-item inside a body; painters draw it as a separated heading. */
   | {
       readonly kind: "section";
       readonly label: string;
@@ -66,7 +65,7 @@ export type ViewBlock =
   | {
       readonly kind: "file";
       readonly path: string;
-      /** An undefined end is an open-ended range (`:40`), not a missing one. */
+      /** An undefined end means open-ended (`:40`). */
       readonly range?: readonly [number, number | undefined];
       readonly truncated?: boolean;
     }
@@ -80,15 +79,15 @@ export type ViewBlock =
       readonly pairs: readonly KvPair[];
     }
   | { readonly kind: "link"; readonly href: string; readonly label: string }
-  /** A file delivered to the reader, not a path on the agent's machine; `url` is server-relative. */
   | {
       readonly kind: "attachment";
-      /** What to call it on screen; never a path. */
+      /** Display name, never a path. */
       readonly name: string;
+      /** Server-relative. */
       readonly url: string;
       readonly isImage: boolean;
     }
-  /** A picture the model was shown, addressed by digest; the bytes never ride the wire, and the client that fetches them builds the URL. */
+  /** An image the model saw, addressed by digest; the client builds the URL. */
   | {
       readonly kind: "image";
       readonly sha256: string;
@@ -110,15 +109,15 @@ export type BlockOf<TKind extends ViewBlock["kind"]> = Extract<
 >;
 
 export type ToolView = {
-  /** Display label for the title row, e.g. `"Read"`; defaults to the definition's label. */
+  /** Defaults to the tool definition's label. */
   readonly label?: string;
-  /** Tints the label; defaults to the title colour. */
+  /** Defaults to the title colour. */
   readonly labelTone?: Tone;
   readonly icon?: ToolIcon;
-  /** Painted as one line; a lone `markdown` block is handed over unpainted instead. */
+  /** Painted as one line; a lone `markdown` block is passed through unpainted. */
   readonly title: readonly ViewBlock[];
-  /** Status content rendered in every state: streaming, collapsed and expanded. */
+  /** Shown in every state, including streaming. */
   readonly summary?: readonly ViewBlock[];
-  /** Rendered only once the row is expanded, and never while streaming. */
+  /** Shown only when expanded, never while streaming. */
   readonly body?: readonly ViewBlock[];
 };

package/packages/daemon/src/Daemon.ts

@@ -1,21 +1,16 @@
 import type { SurfaceName } from "./Surfaces";
 
-/** A running surface, and the only thing the daemon asks of one. */
 export type SurfaceHandle = {
   readonly stop: () => Promise<void>;
 };
 
 export type Surface = {
   readonly name: SurfaceName;
-  /** Brings the surface up, resolving once it is serving rather than when it stops. */
+  /** Resolves once the surface is serving. */
   readonly start: () => Promise<SurfaceHandle>;
 };
 
-/**
- * Every surface in one process, and none of them able to take another down: a
- * bot that cannot reach Telegram leaves the browser served, and a port already
- * bound leaves the bot polling.
- */
+/** Runs every surface in one process; one failing never stops the others. */
 export class Daemon {
   private readonly surfaces: ReadonlyArray<Surface>;
   private readonly live = new Map<SurfaceName, SurfaceHandle>();

package/packages/daemon/src/DaemonInstall.ts

@@ -8,7 +8,6 @@ import { Surfaces, type SurfaceName } from "./Surfaces";
 
 type FrozenUnit = Unit & { readonly args: ReadonlyArray<string> };
 
-/** What this machine serves today: the unit being replaced, or the ones it supersedes. */
 export type Installed = {
   readonly surfaces: ReadonlyArray<SurfaceName>;
   readonly args: ReadonlyArray<string>;
@@ -17,10 +16,8 @@ export type Installed = {
 const NOTHING: Installed = { surfaces: [], args: [] };
 
 /**
- * A supervisor starts the daemon with no argv: every flag it needs must be
- * frozen in here. What is installed already is the base the new argv overrides
- * flag by flag, so installing one surface keeps the other one — and its
- * settings. Naming `--surfaces` outright is how a daemon is shrunk again.
+ * The supervisor starts the daemon with no argv, so every flag is frozen here.
+ * `argv` overrides `installed` flag by flag; an explicit `--surfaces` replaces the surface list.
  */
 function unit(
   argv: ReadonlyArray<string>,
@@ -35,7 +32,7 @@ function unit(
     description: `${DaemonUnit.description} (${surfaces.join(", ")})`,
     args: [
       "--surfaces",
-      Surfaces.format(surfaces),
+      surfaces.join(","),
       ...(surfaces.includes("web")
         ? WebOptions.freeze(WebOptions.parse(merged))
         : []),
@@ -43,10 +40,7 @@ function unit(
   };
 }
 
-/**
- * The merged unit's own argv, or — before the cutover — whatever the per-surface
- * units were installed with, so a tailnet hostname frozen months ago survives.
- */
+/** The daemon unit's argv, falling back to the superseded per-surface units'. */
 async function installed(): Promise<Installed> {
   const current = await Supervisor.installedArgs(DaemonUnit);
   if (current.length > 0) {
@@ -63,7 +57,7 @@ async function installed(): Promise<Installed> {
   };
 }
 
-// `--web-cwd` becomes `--cwd` on the way in, or it would outrank a new `--cwd`.
+// Map `--web-cwd` back to `--cwd` so a new `--cwd` can override it.
 function carriedOver(args: ReadonlyArray<string>): ReadonlyArray<string> {
   return args.map((arg) => (arg === "--web-cwd" ? "--cwd" : arg));
 }
@@ -93,7 +87,6 @@ async function uninstall(): Promise<void> {
 
 async function buildClient(): Promise<void> {
   const at = await Supervisor.detectInstall();
-  // Probe `index.html`, not the directory: a half-emptied `dist/client` is still a broken bundle.
   const bundled = await Bun.file(
     join(DEFAULT_CLIENT_DIR, "index.html")
   ).exists();