palmier 0.8.1 → 0.8.3

package/src/platform/windows.ts

@@ -33,32 +33,25 @@ export function scheduleValueToXml(scheduleType: "crons" | "specific_times", val
   if (parts.length !== 5) throw new Error(`Invalid cron expression: ${value}`);
   const [minute, hour, dayOfMonth, , dayOfWeek] = parts;
   const st = `${hour.padStart(2, "0")}:${minute.padStart(2, "0")}:00`;
-  // StartBoundary needs a full date; use a past date as the anchor
+  // StartBoundary needs a full date; anchor to a past one.
   const base = `2000-01-01T${st}`;
 
-  // Hourly
   if (hour === "*") {
     return `<TimeTrigger><StartBoundary>${base}</StartBoundary><Repetition><Interval>PT1H</Interval></Repetition></TimeTrigger>`;
   }
 
-  // Weekly
   if (dayOfMonth === "*" && dayOfWeek !== "*") {
     const day = DOW_NAMES[Number(dayOfWeek)] ?? "Monday";
     return `<CalendarTrigger><StartBoundary>${base}</StartBoundary><ScheduleByWeek><DaysOfWeek><${day} /></DaysOfWeek><WeeksInterval>1</WeeksInterval></ScheduleByWeek></CalendarTrigger>`;
   }
 
-  // Monthly
   if (dayOfMonth !== "*" && dayOfWeek === "*") {
     return `<CalendarTrigger><StartBoundary>${base}</StartBoundary><ScheduleByMonth><DaysOfMonth><Day>${dayOfMonth}</Day></DaysOfMonth><Months><January /><February /><March /><April /><May /><June /><July /><August /><September /><October /><November /><December /></Months></ScheduleByMonth></CalendarTrigger>`;
   }
 
-  // Daily
   return `<CalendarTrigger><StartBoundary>${base}</StartBoundary><ScheduleByDay><DaysInterval>1</DaysInterval></ScheduleByDay></CalendarTrigger>`;
 }
 
-/**
- * Build a complete Task Scheduler XML definition.
- */
 export function buildTaskXml(tr: string, triggers: string[], foreground?: boolean): string {
   const [command, ...argParts] = tr.match(/"[^"]*"|[^\s]+/g) ?? [];
   const commandStr = command?.replace(/"/g, "") ?? "";
@@ -98,10 +91,7 @@ export class WindowsPlatform implements PlatformService {
   installDaemon(config: HostConfig): void {
     const script = process.argv[1] || "palmier";
 
-    // Create the Task Scheduler entry for the daemon (BootTrigger starts it at system boot)
     this.ensureDaemonTask(script);
-
-    // Start the daemon now
     this.startDaemonTask();
 
     console.log("\nHost initialization complete!");
@@ -110,12 +100,11 @@ export class WindowsPlatform implements PlatformService {
   uninstallDaemon(): void {
     const tn = `\\Palmier\\${DAEMON_TASK_NAME}`;
 
-    // Stop the daemon via Task Scheduler
     try {
       execFileSync("schtasks", ["/end", "/tn", tn], { encoding: "utf-8", windowsHide: true, stdio: "pipe" });
     } catch { /* task may not be running */ }
 
-    // Remove daemon scheduled task (elevated — S4U task requires elevation to delete)
+    // Deleting an S4U task requires elevation.
     try {
       execFileSync("powershell", [
         "-Command", `Start-Process -Verb RunAs -Wait -FilePath schtasks -ArgumentList '/delete /tn "${tn}" /f'`,
@@ -123,7 +112,6 @@ export class WindowsPlatform implements PlatformService {
       console.log("Daemon task removed.");
     } catch { /* task may not exist */ }
 
-    // Remove all Palmier task timers
     try {
       const out = execFileSync("schtasks", ["/query", "/fo", "CSV", "/nh"], { encoding: "utf-8", windowsHide: true, stdio: "pipe" });
       for (const line of out.split("\n")) {
@@ -142,16 +130,14 @@ export class WindowsPlatform implements PlatformService {
   async restartDaemon(): Promise<void> {
     const tn = `\\Palmier\\${DAEMON_TASK_NAME}`;
 
-    // Stop the daemon via Task Scheduler
     try {
       execFileSync("schtasks", ["/end", "/tn", tn], { encoding: "utf-8", windowsHide: true, stdio: "pipe" });
     } catch { /* task may not be running */ }
 
-    // Start it again
     this.startDaemonTask();
   }
 
-  /** Create or update the Task Scheduler entry for the daemon (requires elevation for S4U). */
+  /** S4U LogonType requires elevation to create. */
   private ensureDaemonTask(script: string): void {
     const tn = `\\Palmier\\${DAEMON_TASK_NAME}`;
     const tr = `"${process.execPath}" "${script}" serve`;
@@ -160,7 +146,7 @@ export class WindowsPlatform implements PlatformService {
     try {
       const bom = Buffer.from([0xFF, 0xFE]);
       fs.writeFileSync(xmlPath, Buffer.concat([bom, Buffer.from(xml, "utf16le")]));
-      // S4U LogonType requires elevation — spawn schtasks via RunAs
+      // S4U requires elevation — spawn schtasks via RunAs.
       const args = `/create /tn "${tn}" /xml "${xmlPath}" /f`;
       execFileSync("powershell", [
         "-Command", `Start-Process -Verb RunAs -Wait -FilePath schtasks -ArgumentList '${args}'`,
@@ -174,7 +160,7 @@ export class WindowsPlatform implements PlatformService {
 
   }
 
-  /** Start the daemon via Task Scheduler (runs outside any session's job object). */
+  /** Starting via Task Scheduler runs the daemon outside any session's job object. */
   private startDaemonTask(): void {
     const tn = `\\Palmier\\${DAEMON_TASK_NAME}`;
     try {
@@ -192,9 +178,8 @@ export class WindowsPlatform implements PlatformService {
     const script = process.argv[1] || "palmier";
     const tr = `"${process.execPath}" "${script}" run ${taskId}`;
 
-    // Build trigger XML elements. Event-based schedule types (on_new_notification,
-    // on_new_sms) carry no values and are driven by the run process, not the OS
-    // scheduler — they intentionally produce only the dummy trigger below.
+    // Event-based schedule types (on_new_notification/on_new_sms) are driven by
+    // the run process, not the OS scheduler — they fall through to the dummy trigger.
     const triggerElements: string[] = [];
     const scheduleType = task.frontmatter.schedule_type;
     const scheduleValues = task.frontmatter.schedule_values;
@@ -208,19 +193,19 @@ export class WindowsPlatform implements PlatformService {
         }
       }
     }
-    // Always include a dummy trigger so startTask (/run) works
+    // Dummy trigger so schtasks /run still works.
     if (triggerElements.length === 0) {
       triggerElements.push(`<TimeTrigger><StartBoundary>2000-01-01T00:00:00</StartBoundary></TimeTrigger>`);
     }
 
-    // Write XML and register via schtasks — gives us full control over
-    // settings like MultipleInstancesPolicy that schtasks flags don't expose.
-    // S4U LogonType ensures no console window (unless foreground_mode is set).
-    // Works without elevation because the daemon (which calls this) runs elevated.
+    // XML registration (vs schtasks flags) gives us access to settings like
+    // MultipleInstancesPolicy. S4U keeps the console hidden unless
+    // foreground_mode is set. Works unelevated because the caller (daemon)
+    // runs elevated.
     const xml = buildTaskXml(tr, triggerElements, task.frontmatter.foreground_mode);
     const xmlPath = path.join(CONFIG_DIR, `task-${taskId}.xml`);
     try {
-      // schtasks /xml requires UTF-16LE with BOM
+      // schtasks /xml requires UTF-16LE with BOM.
       const bom = Buffer.from([0xFF, 0xFE]);
       fs.writeFileSync(xmlPath, Buffer.concat([bom, Buffer.from(xml, "utf16le")]));
       execFileSync("schtasks", [
@@ -239,9 +224,7 @@ export class WindowsPlatform implements PlatformService {
     const tn = schtasksTaskName(taskId);
     try {
       execFileSync("schtasks", ["/delete", "/tn", tn, "/f"], { encoding: "utf-8", windowsHide: true });
-    } catch {
-      // Task might not exist — that's fine
-    }
+    } catch { /* task may not exist */ }
   }
 
   async startTask(taskId: string): Promise<void> {
@@ -255,8 +238,8 @@ export class WindowsPlatform implements PlatformService {
   }
 
   async stopTask(taskId: string): Promise<void> {
-    // Try to kill the entire process tree via the PID recorded in status.json.
-    // schtasks /end only kills the top-level process, leaving agent children orphaned.
+    // schtasks /end leaves agent children orphaned, so kill the process tree
+    // via the PID recorded in status.json first.
     try {
       const taskDir = getTaskDir(loadConfig().projectRoot, taskId);
       const status = readTaskStatus(taskDir);
@@ -265,10 +248,9 @@ export class WindowsPlatform implements PlatformService {
         return;
       }
     } catch {
-      // PID may be stale or config unavailable; fall through to schtasks /end
+      // PID may be stale or config unavailable; fall through to schtasks /end.
     }
 
-    // Fallback: schtasks /end (kills top-level process only)
     const tn = schtasksTaskName(taskId);
     try {
       execFileSync("schtasks", ["/end", "/tn", tn], { encoding: "utf-8", windowsHide: true });
@@ -279,7 +261,6 @@ export class WindowsPlatform implements PlatformService {
   }
 
   isTaskRunning(taskId: string): boolean {
-    // Check Task Scheduler first (for scheduled/on-demand runs)
     const tn = schtasksTaskName(taskId);
     try {
       const out = execFileSync("schtasks", ["/query", "/tn", tn, "/fo", "CSV", "/nh"], {
@@ -289,18 +270,17 @@ export class WindowsPlatform implements PlatformService {
       if (out.includes('"Running"')) return true;
     } catch { /* task may not exist in scheduler */ }
 
-    // Fall back to PID check (for follow-up runs spawned directly, not via schtasks)
+    // Follow-up runs are spawned directly (not via schtasks), so check PID too.
     try {
       const taskDir = getTaskDir(loadConfig().projectRoot, taskId);
       const status = readTaskStatus(taskDir);
       if (status?.pid) {
-        // tasklist exits 0 if the PID is found
         execFileSync("tasklist", ["/fi", `PID eq ${status.pid}`, "/nh"], {
           encoding: "utf-8",
           windowsHide: true,
           stdio: "pipe",
         });
-        // tasklist always exits 0; check if output contains the PID
+        // tasklist always exits 0, so match the output for the PID.
         const out = execFileSync("tasklist", ["/fi", `PID eq ${status.pid}`, "/fo", "CSV", "/nh"], {
           encoding: "utf-8",
           windowsHide: true,
@@ -314,7 +294,6 @@ export class WindowsPlatform implements PlatformService {
   }
 
   getGuiEnv(): Record<string, string> {
-    // Windows GUI is always available — no special env vars needed
     return {};
   }
 }

package/src/rpc-handler.ts

@@ -12,14 +12,12 @@ import { getAgent } from "./agents/agent.js";
 import { validateClient } from "./client-store.js";
 import { publishHostEvent } from "./events.js";
 import { getCapabilityDevice, setCapabilityDevice, clearCapabilityDevice, type DeviceCapability } from "./device-capabilities.js";
+import { listApps } from "./app-registry.js";
 import { currentVersion, performUpdate } from "./update-checker.js";
 import { parseReportFiles, parseTaskOutcome, stripPalmierMarkers } from "./commands/run.js";
 import { clearTaskQueue } from "./event-queues.js";
 import type { HostConfig, ParsedTask, RpcMessage, ConversationMessage } from "./types.js";
 
-/**
- * Parse RESULT frontmatter and conversation messages.
- */
 export function parseResultFrontmatter(raw: string): Record<string, unknown> {
   const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
   if (!fmMatch) return { messages: [] };
@@ -33,19 +31,16 @@ export function parseResultFrontmatter(raw: string): Record<string, unknown> {
 
   const messages = parseConversationMessages(fmMatch[2]);
 
-  // Derive state from status messages — just look at the last one
   const statusMessages = messages.filter((m: ConversationMessage) => m.role === "status");
   const lastStatus = statusMessages[statusMessages.length - 1];
   const startedMsg = statusMessages.find((m: ConversationMessage) => m.type === "started");
   const terminalStates = ["finished", "failed", "aborted"];
   const terminalMsg = [...statusMessages].reverse().find((m: ConversationMessage) => terminalStates.includes(m.type ?? ""));
 
-  // If last status is "started" (or continuation like "confirmation"/"monitoring"),
-  // determine if it's a task run or follow-up
   const activeStates = ["started", "monitoring", "confirmation"];
   let runningState: string | undefined;
   if (lastStatus?.type === "monitoring") {
-    // Only show monitoring if no assistant/user message came after it
+    // Show "monitoring" only if no assistant/user message followed it.
     const lastStatusIdx = messages.lastIndexOf(lastStatus);
     const hasMessageAfter = messages.slice(lastStatusIdx + 1).some((m: ConversationMessage) => m.role === "assistant" || m.role === "user");
     runningState = hasMessageAfter ? "started" : "monitoring";
@@ -65,16 +60,13 @@ export function parseResultFrontmatter(raw: string): Record<string, unknown> {
   };
 }
 
-/**
- * Parse conversation messages from the body of a RESULT file.
- */
 function parseConversationMessages(body: string): ConversationMessage[] {
   const delimiterRegex = /<!-- palmier:message\s+(.*?)\s*-->/g;
   const messages: ConversationMessage[] = [];
   const matches = [...body.matchAll(delimiterRegex)];
 
   if (matches.length === 0) {
-    // No delimiters — treat entire body as single assistant message if non-empty
+    // No delimiters — treat entire body as a single assistant message.
     const content = body.trim();
     if (content) {
       messages.push({ role: "assistant", time: 0, content });
@@ -106,10 +98,6 @@ function parseAttr(attrs: string, name: string): string | undefined {
   return match ? match[1] : undefined;
 }
 
-/**
- * Generate a concise task name from a user prompt using the given agent.
- * Falls back to the raw prompt on failure.
- */
 async function generateName(
   projectRoot: string,
   userPrompt: string,
@@ -136,9 +124,6 @@ async function generateName(
 /** Active follow-up child processes, keyed by "taskId:runId". */
 const activeFollowups = new Map<string, ChildProcess>();
 
-/**
- * Create a transport-agnostic RPC handler bound to the given config.
- */
 export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
   function flattenTask(task: ParsedTask) {
     const taskDir = getTaskDir(config.projectRoot, task.frontmatter.id);
@@ -150,8 +135,8 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
   }
 
   async function handleRpc(request: RpcMessage): Promise<unknown> {
-    // Client token validation: skip for trusted localhost requests and
-    // task.user_input (server-originated push responses; gated by getPending instead)
+    // task.user_input comes from server-originated push responses; it's gated
+    // by getPending() rather than a client token.
     const skipAuth = request.method === "task.user_input";
     if (!skipAuth && !request.localhost && (!request.clientToken || !validateClient(request.clientToken))) {
       return { error: "Unauthorized" };
@@ -159,11 +144,8 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
 
     switch (request.method) {
       case "host.info": {
-        // Bootstrap metadata the PWA needs on connect, independent of which tab
-        // is active. Includes any prompts already waiting so a reconnecting
-        // PWA can render their modals without replaying events.
         const capabilities: Record<string, string | null> = {};
-        for (const capability of ["location", "notifications", "sms", "contacts", "calendar", "alert", "battery", "dnd", "send-email"] as const) {
+        for (const capability of ["location", "notifications", "sms-read", "sms-send", "contacts", "calendar", "alarm", "battery", "dnd", "send-email"] as const) {
           capabilities[capability] = getCapabilityDevice(capability)?.clientToken ?? null;
         }
         return {
@@ -250,11 +232,9 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
         const taskDir = getTaskDir(config.projectRoot, params.id);
         const existing = parseTaskFile(taskDir);
 
-        // Detect whether name needs regeneration
         const promptChanged = params.user_prompt !== undefined && params.user_prompt !== existing.frontmatter.user_prompt;
         const agentChanged = params.agent !== undefined && params.agent !== existing.frontmatter.agent;
 
-        // Merge updates
         if (params.user_prompt !== undefined) existing.frontmatter.user_prompt = params.user_prompt;
         if (params.agent !== undefined) existing.frontmatter.agent = params.agent;
         if (params.schedule_type !== undefined) {
@@ -287,7 +267,6 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
           }
         }
 
-        // Regenerate name when prompt or agent changes
         if (promptChanged || agentChanged) {
           existing.frontmatter.name = existing.frontmatter.user_prompt.length <= 50
             ? existing.frontmatter.user_prompt
@@ -296,8 +275,8 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
 
         writeTaskFile(taskDir, existing);
 
-        // Update timers — installTaskTimer overwrites in-place (schtasks /f,
-        // systemd unit rewrite) without killing a running task process.
+        // installTaskTimer overwrites in-place (schtasks /f, systemd unit rewrite)
+        // without killing a running task process.
         getPlatform().installTaskTimer(config, existing);
 
         return flattenTask(existing);
@@ -341,13 +320,11 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
         };
 
         writeTaskFile(taskDir, task);
-        // Do NOT append to tasks.jsonl — this is a one-off run
+        // One-off run: do NOT append to tasks.jsonl.
 
-        // Create initial result file so it appears in runs list immediately
         const runId = createRunDir(taskDir, name, Date.now(), params.agent);
         appendHistory(config.projectRoot, { task_id: id, run_id: runId });
 
-        // Spawn `palmier run <id>` directly as a detached process
         const script = process.argv[1] || "palmier";
         const child = spawn(process.execPath, [script, "run", id], {
           detached: true,
@@ -365,13 +342,11 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
           const runTaskDir = getTaskDir(config.projectRoot, params.id);
           const platform = getPlatform();
 
-          // If the task is already running, kill the stale process and start fresh
           if (platform.isTaskRunning(params.id)) {
             console.log(`[task.run] Task ${params.id} is already running, killing stale process`);
             await platform.stopTask(params.id);
           }
 
-          // Create initial result file so it appears in runs list immediately
           const runTask = parseTaskFile(runTaskDir);
           const taskRunId = createRunDir(runTaskDir, runTask.frontmatter.name, Date.now(), runTask.frontmatter.agent);
           appendHistory(config.projectRoot, { task_id: params.id, run_id: taskRunId });
@@ -399,7 +374,6 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
         const followupTask = parseTaskFile(followupTaskDir);
         const followupRunDir = getRunDir(followupTaskDir, params.run_id);
 
-        // Append user message + started status
         appendRunMessage(followupTaskDir, params.run_id, {
           role: "user",
           time: Date.now(),
@@ -413,13 +387,11 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
         });
         await publishHostEvent(nc, config.hostId, params.id, { event_type: "result-updated", run_id: params.run_id });
 
-        // Fire-and-forget: invoke agent inline as a child of the serve process
         const followupAgent = getAgent(followupTask.frontmatter.agent);
         const { command: cmd, args: cmdArgs, stdin, env: followupAgentEnv } = followupAgent.getTaskRunCommandLine(
           followupTask, params.message, followupTask.frontmatter.yolo_mode ? "yolo" : followupTask.frontmatter.permissions,
         );
 
-        // Spawn directly via crossSpawn so we can track and kill the child
         const child = crossSpawn(cmd, cmdArgs, {
           cwd: followupRunDir,
           stdio: [stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
@@ -429,14 +401,13 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
         if (stdin != null) child.stdin!.end(stdin);
         activeFollowups.set(followupKey, child);
 
-        // Collect output
         const chunks: Buffer[] = [];
         child.stdout?.on("data", (d: Buffer) => chunks.push(d));
         child.stderr?.on("data", (d: Buffer) => process.stderr.write(d));
 
         child.on("close", async (code: number | null) => {
           activeFollowups.delete(followupKey);
-          // If killed by stop_followup, the stopped status is already written
+          // stop_followup already wrote the stopped status.
           if (child.killed) return;
 
           const output = Buffer.concat(chunks).toString("utf-8");
@@ -484,7 +455,6 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
           return { error: "No active follow-up for this run" };
         }
 
-        // Kill the child process tree
         if (process.platform === "win32" && child.pid) {
           try {
             const { execFileSync } = await import("child_process");
@@ -494,7 +464,7 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
           child.kill();
         }
 
-        // Append stopped status (child.killed prevents the close handler from writing)
+        // child.killed stops the close handler from double-writing the status.
         const stopTaskDir = getTaskDir(config.projectRoot, params.id);
         appendRunMessage(stopTaskDir, params.run_id, {
           role: "status",
@@ -510,17 +480,16 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
       case "task.abort": {
         const params = request.params as { id: string };
         const abortTaskDir = getTaskDir(config.projectRoot, params.id);
-        // Read the PID before overwriting status — stopTask needs it to
-        // kill the entire process tree on Windows.
+        // Read PID before overwriting — stopTask needs it to kill the
+        // process tree on Windows.
         const abortPrevStatus = readTaskStatus(abortTaskDir);
-        // Write abort status BEFORE killing so the dying process's signal
-        // handler can detect this was RPC-initiated and skip publishing.
+        // Write abort status before killing so the dying process's signal
+        // handler sees this was RPC-initiated and skips publishing.
         writeTaskStatus(abortTaskDir, {
           running_state: "aborted",
           time_stamp: Date.now(),
           ...(abortPrevStatus?.pid ? { pid: abortPrevStatus.pid } : {}),
         });
-        // Append aborted status to the latest run
         try {
           const runDirs = fs.readdirSync(abortTaskDir)
             .filter((f) => /^\d+$/.test(f) && fs.existsSync(path.join(abortTaskDir, f, "TASKRUN.md")))
@@ -543,7 +512,6 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
           console.error(`task.abort failed for ${params.id}: ${e.stderr || e.message}`);
           return { error: `Failed to abort task: ${e.stderr || e.message}` };
         }
-        // Notify connected clients (NATS + HTTP SSE if LAN server is running)
         const abortPayload: Record<string, unknown> = { event_type: "running-state", running_state: "aborted" };
         await publishHostEvent(nc, config.hostId, params.id, abortPayload);
         return { ok: true, task_id: params.id };
@@ -694,6 +662,10 @@ export function createRpcHandler(config: HostConfig, nc?: NatsConnection) {
         return { ok: true };
       }
 
+      case "device.notifications.apps": {
+        return { apps: listApps() };
+      }
+
       default:
         return { error: `Unknown method: ${request.method}` };
     }

package/src/spawn-command.ts

@@ -18,19 +18,12 @@ export interface SpawnStreamingOptions {
 }
 
 /**
- * Spawn a command with shell interpretation, returning the ChildProcess
- * with stdout piped for line-by-line reading.
- *
- * Unlike spawnCommand(), this does NOT collect output into a buffer —
- * the caller reads from child.stdout directly (e.g. via readline).
- *
- * shell: true is required so users can write piped commands like
- * "tail -f log | grep ERROR".
- *
- * stdin is "pipe" (kept open, never written to) rather than "ignore"
- * (/dev/null). Some long-running commands exit when stdin is closed/EOF.
- * This differs from spawnCommand() which uses "ignore" because agent
- * CLIs like `claude -p` hang on an open stdin pipe.
+ * Spawn with shell interpretation for piped commands like "tail -f log | grep".
+ * Returns the ChildProcess with stdout piped so the caller can read it directly
+ * (contrast with spawnCommand which buffers). stdin is "pipe" (held open, not
+ * written to): some long-running commands exit on stdin EOF. Agent CLIs like
+ * `claude -p` conversely hang on an open stdin, which is why spawnCommand
+ * defaults to "ignore".
  */
 export function spawnStreamingCommand(
   command: string,
@@ -60,18 +53,10 @@ export interface SpawnCommandOptions {
 }
 
 /**
- * Spawn a command with additional arguments.
- *
- * Uses cross-spawn to correctly resolve .cmd shims and escape arguments
- * on Windows without shell: true (which mishandles special characters).
- *
- * On other platforms the command is executed directly (no shell), so no
- * escaping is needed.
- *
- * stdin is set to "ignore" by default (equivalent to < /dev/null) because
- * tools like `claude -p` hang indefinitely on an open stdin pipe.
- * When opts.stdin is provided, stdin is set to "pipe" and the string is
- * written to the process before closing the pipe.
+ * cross-spawn resolves .cmd shims and escapes args on Windows without shell:true
+ * (which mishandles special characters). stdin defaults to "ignore" because
+ * tools like `claude -p` hang on an open stdin pipe; pass opts.stdin to write
+ * a string and then close the pipe.
  */
 export interface SpawnCommandResult {
   output: string;
@@ -84,8 +69,7 @@ export function spawnCommand(
   opts: SpawnCommandOptions,
 ): Promise<SpawnCommandResult> {
   return new Promise<SpawnCommandResult>((resolve, reject) => {
-    // Collapse newlines to spaces — cmd.exe can't handle literal newlines
-    // in arguments, and CLI prompts don't need them.
+    // cmd.exe can't handle literal newlines in arguments.
     const finalArgs = process.platform === "win32"
       ? args.map((a) => a.replace(/[\r\n]+/g, " "))
       : args;