palmier 0.3.1 → 0.3.2

package/README.md

@@ -132,6 +132,15 @@ palmier restart
 - **Real-time updates** — task status changes (started, finished, failed) are pushed to connected PWA clients via NATS pub/sub (server mode) and/or SSE (LAN mode).
 - **MCP server** (`palmier mcpserver`) exposes platform tools (e.g., `send-push-notification`) to AI agents like Claude Code over stdio.
 
+## NATS Subjects
+
+| Subject | Direction | Description |
+|---|---|---|
+| `host.<hostId>.rpc.<method>` | Client → Host | RPC request/reply (e.g., `task.list`, `task.create`) |
+| `host-event.<hostId>.<taskId>` | Host → Client | Real-time task events (`running-state`, `confirm-request`, `permission-request`, `input-request`) |
+| `host.<hostId>.push.send` | Host → Server | Request server to deliver a push notification |
+| `pair.<code>` | Client → Host | OTP pairing request/reply |
+
 ## Project Structure
 
 ```
@@ -144,16 +153,19 @@ src/
   spawn-command.ts    # Shared helper for spawning CLI tools
   task.ts             # Task file management
   types.ts            # Shared type definitions
+  pairing.ts          # OTP code generation and expiry constant
+  lan-lock.ts         # LAN lockfile path and port reader
+  events.ts           # Event broadcasting (NATS pub/sub or HTTP SSE)
   agents/
     agent.ts          # AgentTool interface, registry, and agent detection
     claude.ts         # Claude Code agent implementation
     gemini.ts         # Gemini CLI agent implementation
     codex.ts          # Codex CLI agent implementation
     openclaw.ts       # OpenClaw agent implementation
-  events.ts           # Event broadcasting (NATS pub/sub or HTTP SSE)
   commands/
     init.ts           # Interactive setup wizard (auto-pair)
     pair.ts           # OTP code generation and pairing handler
+    lan.ts            # On-demand LAN server
     sessions.ts       # Session token management CLI (list, revoke, revoke-all)
     info.ts           # Print host connection info
     agents.ts         # Re-detect installed agent CLIs

package/dist/agents/claude.js

@@ -1,8 +1,6 @@
 import { execSync } from "child_process";
 import { AGENT_INSTRUCTIONS } from "./shared-prompt.js";
-// execSync's shell option takes a string (shell path), not boolean.
-// On Windows we need a shell so .cmd shims resolve correctly.
-const SHELL = process.platform === "win32" ? "cmd.exe" : undefined;
+import { SHELL } from "../platform/index.js";
 export class ClaudeAgent {
     getPlanGenerationCommandLine(prompt) {
         return {

package/dist/agents/codex.js

@@ -1,10 +1,8 @@
 import { execSync } from "child_process";
 import { AGENT_INSTRUCTIONS } from "./shared-prompt.js";
-// On Windows we need a shell so .cmd shims resolve correctly.
-const SHELL = process.platform === "win32" ? "cmd.exe" : undefined;
+import { SHELL } from "../platform/index.js";
 export class CodexAgent {
     getPlanGenerationCommandLine(prompt) {
-        // TODO: fill in
         return {
             command: "codex",
             args: ["exec", "--skip-git-repo-check", prompt],
@@ -12,8 +10,7 @@ export class CodexAgent {
     }
     getTaskRunCommandLine(task, retryPrompt, extraPermissions) {
         const prompt = AGENT_INSTRUCTIONS + "\n\n" + (retryPrompt ?? (task.body || task.frontmatter.user_prompt));
-        // TODO: Update sandbox to workspace-write once https://github.com/openai/codex/issues/12572
-        // is fixed.
+        // Using danger-full-access until workspace-write is fixed: https://github.com/openai/codex/issues/12572
         const args = ["exec", "--full-auto", "--skip-git-repo-check", "--sandbox", "danger-full-access"];
         const allPerms = [...(task.frontmatter.permissions ?? []), ...(extraPermissions ?? [])];
         for (const p of allPerms) {

package/dist/agents/gemini.js

@@ -1,10 +1,8 @@
 import { execSync } from "child_process";
 import { AGENT_INSTRUCTIONS } from "./shared-prompt.js";
-// On Windows we need a shell so .cmd shims resolve correctly.
-const SHELL = process.platform === "win32" ? "cmd.exe" : undefined;
+import { SHELL } from "../platform/index.js";
 export class GeminiAgent {
     getPlanGenerationCommandLine(prompt) {
-        // TODO: fill in
         return {
             command: "gemini",
             args: ["--approval-mode", "auto_edit", "--prompt", prompt],

package/dist/commands/init.js

@@ -58,7 +58,6 @@ export async function initCommand() {
         const config = {
             hostId: registerResponse.hostId,
             projectRoot: process.cwd(),
-            nats: true,
             natsUrl: registerResponse.natsUrl,
             natsWsUrl: registerResponse.natsWsUrl,
             natsToken: registerResponse.natsToken,

package/dist/commands/lan.js

@@ -1,19 +1,12 @@
 import * as fs from "fs";
-import * as path from "path";
 import { loadConfig, CONFIG_DIR } from "../config.js";
 import { createRpcHandler } from "../rpc-handler.js";
 import { startHttpTransport, detectLanIp } from "../transports/http-transport.js";
-const LAN_LOCKFILE = path.join(CONFIG_DIR, "lan.json");
+import { generatePairingCode } from "../pairing.js";
+import { LAN_LOCKFILE } from "../lan-lock.js";
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
-const CODE_CHARS = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
-const CODE_LENGTH = 6;
-function generateCode() {
-    const bytes = new Uint8Array(CODE_LENGTH);
-    crypto.getRandomValues(bytes);
-    return Array.from(bytes, (b) => CODE_CHARS[b % CODE_CHARS.length]).join("");
-}
 function writeLockfile(port) {
     fs.mkdirSync(CONFIG_DIR, { recursive: true });
     fs.writeFileSync(LAN_LOCKFILE, JSON.stringify({ port, pid: process.pid }), "utf-8");
@@ -32,7 +25,7 @@ export async function lanCommand(opts) {
     const config = loadConfig();
     const port = opts.port;
     const ip = detectLanIp();
-    const code = generateCode();
+    const code = generatePairingCode();
     const handleRpc = createRpcHandler(config);
     // Write lockfile so other palmier processes can discover us
     writeLockfile(port);

package/dist/commands/pair.js

@@ -1,19 +1,10 @@
-import * as fs from "fs";
-import * as path from "path";
 import * as http from "node:http";
 import { StringCodec } from "nats";
-import { loadConfig, CONFIG_DIR } from "../config.js";
+import { loadConfig } from "../config.js";
 import { connectNats } from "../nats-client.js";
 import { addSession } from "../session-store.js";
-const CODE_CHARS = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"; // no O/0/I/1/L
-const CODE_LENGTH = 6;
-const EXPIRY_MS = 5 * 60 * 1000; // 5 minutes
-const LAN_LOCKFILE = path.join(CONFIG_DIR, "lan.json");
-function generateCode() {
-    const bytes = new Uint8Array(CODE_LENGTH);
-    crypto.getRandomValues(bytes);
-    return Array.from(bytes, (b) => CODE_CHARS[b % CODE_CHARS.length]).join("");
-}
+import { generatePairingCode, PAIRING_EXPIRY_MS } from "../pairing.js";
+import { getLanPort } from "../lan-lock.js";
 function buildPairResponse(config, label) {
     const session = addSession(label);
     return {
@@ -25,7 +16,7 @@ function buildPairResponse(config, label) {
  * POST to the running LAN server and long-poll until paired or expired.
  */
 function lanPairRegister(port, code) {
-    const body = JSON.stringify({ code, expiryMs: EXPIRY_MS });
+    const body = JSON.stringify({ code, expiryMs: PAIRING_EXPIRY_MS });
     return new Promise((resolve) => {
         const req = http.request({
             hostname: "127.0.0.1",
@@ -33,7 +24,7 @@ function lanPairRegister(port, code) {
             path: "/internal/pair-register",
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            timeout: EXPIRY_MS + 5000,
+            timeout: PAIRING_EXPIRY_MS + 5000,
         }, (res) => {
             const chunks = [];
             res.on("data", (chunk) => chunks.push(chunk));
@@ -52,25 +43,13 @@ function lanPairRegister(port, code) {
         req.end(body);
     });
 }
-/**
- * Read the LAN lockfile to check if `palmier lan` is running.
- */
-function getLanPort() {
-    try {
-        const raw = fs.readFileSync(LAN_LOCKFILE, "utf-8");
-        return JSON.parse(raw).port;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Generate an OTP code and wait for a PWA client to pair.
  * Listens on NATS always, and also on the LAN server if `palmier lan` is running.
  */
 export async function pairCommand() {
     const config = loadConfig();
-    const code = generateCode();
+    const code = generatePairingCode();
     let paired = false;
     function onPaired() {
         paired = true;
@@ -125,7 +104,7 @@ export async function pairCommand() {
     const start = Date.now();
     await new Promise((resolve) => {
         const interval = setInterval(() => {
-            if (paired || Date.now() - start >= EXPIRY_MS) {
+            if (paired || Date.now() - start >= PAIRING_EXPIRY_MS) {
                 clearInterval(interval);
                 resolve();
             }

package/dist/commands/run.js

@@ -194,16 +194,13 @@ async function runCommandTriggeredMode(ctx) {
         cwd: ctx.taskDir,
         env: { ...ctx.guiEnv, PALMIER_TASK_ID: ctx.task.frontmatter.id },
     });
-    // Stats
     let linesProcessed = 0;
     let invocationsSucceeded = 0;
     let invocationsFailed = 0;
-    // Bounded queue for incoming lines
     const lineQueue = [];
     let processing = false;
     let commandExited = false;
     let resolveWhenDone;
-    // Rolling log of per-line agent outputs
     const logPath = path.join(ctx.taskDir, "command-output.log");
     function appendLog(line, agentOutput, outcome) {
         const entry = `[${new Date().toISOString()}] (${outcome}) input: ${line}\n${agentOutput}\n---\n`;
@@ -259,11 +256,10 @@ async function runCommandTriggeredMode(ctx) {
             }
         }
     }
-    // Read stdout line by line
     const rl = readline.createInterface({ input: child.stdout });
     rl.on("line", (line) => {
         if (!line.trim())
-            return; // skip empty lines
+            return;
         if (lineQueue.length >= MAX_QUEUE_SIZE) {
             console.warn(`[command-triggered] Queue full, dropping oldest line.`);
             lineQueue.shift();
@@ -274,7 +270,6 @@ async function runCommandTriggeredMode(ctx) {
             invocationsFailed++;
         });
     });
-    // Log stderr
     child.stderr?.on("data", (d) => process.stderr.write(d));
     // Wait for command to exit
     const exitCode = await new Promise((resolve) => {
@@ -305,9 +300,7 @@ async function runCommandTriggeredMode(ctx) {
         `Agent invocations succeeded: ${invocationsSucceeded}`,
         `Agent invocations failed: ${invocationsFailed}`,
     ].join("\n");
-    // Command-triggered tasks run until the command exits — any exit is a normal finish.
-    const outcome = "finished";
-    return { outcome, endTime, output: summary };
+    return { outcome: "finished", endTime, output: summary };
 }
 async function publishTaskEvent(nc, config, taskDir, taskId, eventType, taskName) {
     writeTaskStatus(taskDir, {
@@ -329,32 +322,39 @@ async function publishConfirmResolved(nc, config, taskId, status) {
         status,
     });
 }
-async function requestPermission(nc, config, task, taskDir, requiredPermissions) {
-    const taskId = task.frontmatter.id;
+/**
+ * Watch status.json until user_input is populated by an RPC call, then resolve.
+ * All interactive request flows (confirmation, permission, user input) share this.
+ */
+function waitForUserInput(taskDir) {
     const statusPath = path.join(taskDir, "status.json");
-    const currentStatus = readTaskStatus(taskDir);
-    writeTaskStatus(taskDir, { ...currentStatus, pending_permission: requiredPermissions });
-    await publishHostEvent(nc, config.hostId, taskId, {
-        event_type: "permission-request",
-        host_id: config.hostId,
-        required_permissions: requiredPermissions,
-        name: task.frontmatter.name,
-    });
     return new Promise((resolve) => {
         const watcher = fs.watch(statusPath, () => {
             const status = readTaskStatus(taskDir);
             if (!status || !status.user_input?.length)
                 return;
             watcher.close();
-            const response = status.user_input[0];
-            writeTaskStatus(taskDir, {
-                running_state: response === "aborted" ? "aborted" : "started",
-                time_stamp: Date.now(),
-            });
-            resolve(response);
+            resolve(status.user_input);
         });
     });
 }
+async function requestPermission(nc, config, task, taskDir, requiredPermissions) {
+    const currentStatus = readTaskStatus(taskDir);
+    writeTaskStatus(taskDir, { ...currentStatus, pending_permission: requiredPermissions });
+    await publishHostEvent(nc, config.hostId, task.frontmatter.id, {
+        event_type: "permission-request",
+        host_id: config.hostId,
+        required_permissions: requiredPermissions,
+        name: task.frontmatter.name,
+    });
+    const userInput = await waitForUserInput(taskDir);
+    const response = userInput[0];
+    writeTaskStatus(taskDir, {
+        running_state: response === "aborted" ? "aborted" : "started",
+        time_stamp: Date.now(),
+    });
+    return response;
+}
 async function publishPermissionResolved(nc, config, taskId, status) {
     await publishHostEvent(nc, config.hostId, taskId, {
         event_type: "permission-resolved",
@@ -363,33 +363,21 @@ async function publishPermissionResolved(nc, config, taskId, status) {
     });
 }
 async function requestUserInput(nc, config, task, taskDir, inputDescriptions) {
-    const taskId = task.frontmatter.id;
-    const statusPath = path.join(taskDir, "status.json");
     const currentStatus = readTaskStatus(taskDir);
     writeTaskStatus(taskDir, { ...currentStatus, pending_input: inputDescriptions });
-    await publishHostEvent(nc, config.hostId, taskId, {
+    await publishHostEvent(nc, config.hostId, task.frontmatter.id, {
         event_type: "input-request",
         host_id: config.hostId,
         input_descriptions: inputDescriptions,
         name: task.frontmatter.name,
     });
-    return new Promise((resolve) => {
-        const watcher = fs.watch(statusPath, () => {
-            const status = readTaskStatus(taskDir);
-            if (!status || !status.user_input?.length)
-                return;
-            watcher.close();
-            const response = status.user_input;
-            if (response.length === 1 && response[0] === "aborted") {
-                writeTaskStatus(taskDir, { running_state: "aborted", time_stamp: Date.now() });
-                resolve("aborted");
-            }
-            else {
-                writeTaskStatus(taskDir, { running_state: "started", time_stamp: Date.now() });
-                resolve(response);
-            }
-        });
-    });
+    const userInput = await waitForUserInput(taskDir);
+    if (userInput.length === 1 && userInput[0] === "aborted") {
+        writeTaskStatus(taskDir, { running_state: "aborted", time_stamp: Date.now() });
+        return "aborted";
+    }
+    writeTaskStatus(taskDir, { running_state: "started", time_stamp: Date.now() });
+    return userInput;
 }
 async function publishInputResolved(nc, config, taskId, status) {
     await publishHostEvent(nc, config.hostId, taskId, {
@@ -399,32 +387,19 @@ async function publishInputResolved(nc, config, taskId, status) {
     });
 }
 async function requestConfirmation(nc, config, task, taskDir) {
-    const taskId = task.frontmatter.id;
-    const statusPath = path.join(taskDir, "status.json");
-    // Flag that we're awaiting user confirmation
     const currentStatus = readTaskStatus(taskDir);
     writeTaskStatus(taskDir, { ...currentStatus, pending_confirmation: true });
-    // Publish confirmation request via NATS and/or HTTP SSE
-    await publishHostEvent(nc, config.hostId, taskId, {
+    await publishHostEvent(nc, config.hostId, task.frontmatter.id, {
         event_type: "confirm-request",
         host_id: config.hostId,
     });
-    // Wait for task.user_input RPC to set user_input in status.json
-    return new Promise((resolve) => {
-        const watcher = fs.watch(statusPath, () => {
-            const status = readTaskStatus(taskDir);
-            if (!status || !status.user_input?.length)
-                return; // still pending
-            watcher.close();
-            const confirmed = status.user_input[0] === "confirmed";
-            // Clear pending_confirmation/user_input and update running_state
-            writeTaskStatus(taskDir, {
-                running_state: confirmed ? "started" : "aborted",
-                time_stamp: Date.now(),
-            });
-            resolve(confirmed);
-        });
+    const userInput = await waitForUserInput(taskDir);
+    const confirmed = userInput[0] === "confirmed";
+    writeTaskStatus(taskDir, {
+        running_state: confirmed ? "started" : "aborted",
+        time_stamp: Date.now(),
     });
+    return confirmed;
 }
 /**
  * Extract report file names from agent output.

package/dist/config.js

@@ -20,7 +20,6 @@ export function loadConfig() {
     if (!config.natsUrl || !config.natsToken) {
         throw new Error("Invalid host config: missing natsUrl or natsToken");
     }
-    config.nats = true;
     return config;
 }
 /**

package/dist/events.js

@@ -1,21 +1,6 @@
-import * as fs from "fs";
-import * as path from "path";
 import { StringCodec } from "nats";
-import { CONFIG_DIR } from "./config.js";
+import { getLanPort } from "./lan-lock.js";
 const sc = StringCodec();
-const LAN_LOCKFILE = path.join(CONFIG_DIR, "lan.json");
-/**
- * Read the LAN lockfile to determine if `palmier lan` is running.
- */
-function getLanPort() {
-    try {
-        const raw = fs.readFileSync(LAN_LOCKFILE, "utf-8");
-        return JSON.parse(raw).port;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Broadcast an event to connected clients via NATS and HTTP SSE (if LAN server is running).
  *

package/dist/lan-lock.d.ts

@@ -0,0 +1,7 @@
+export declare const LAN_LOCKFILE: string;
+/**
+ * Read the LAN lockfile to determine if `palmier lan` is running.
+ * Returns the port number, or null if not running.
+ */
+export declare function getLanPort(): number | null;
+//# sourceMappingURL=lan-lock.d.ts.map

package/dist/lan-lock.js

@@ -0,0 +1,18 @@
+import * as fs from "fs";
+import * as path from "path";
+import { CONFIG_DIR } from "./config.js";
+export const LAN_LOCKFILE = path.join(CONFIG_DIR, "lan.json");
+/**
+ * Read the LAN lockfile to determine if `palmier lan` is running.
+ * Returns the port number, or null if not running.
+ */
+export function getLanPort() {
+    try {
+        const raw = fs.readFileSync(LAN_LOCKFILE, "utf-8");
+        return JSON.parse(raw).port;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=lan-lock.js.map

package/dist/pairing.d.ts

@@ -0,0 +1,3 @@
+export declare const PAIRING_EXPIRY_MS: number;
+export declare function generatePairingCode(): string;
+//# sourceMappingURL=pairing.d.ts.map

package/dist/pairing.js

@@ -0,0 +1,9 @@
+const CODE_CHARS = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"; // no O/0/I/1/L
+const CODE_LENGTH = 6;
+export const PAIRING_EXPIRY_MS = 5 * 60 * 1000; // 5 minutes
+export function generatePairingCode() {
+    const bytes = new Uint8Array(CODE_LENGTH);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => CODE_CHARS[b % CODE_CHARS.length]).join("");
+}
+//# sourceMappingURL=pairing.js.map

package/dist/platform/index.d.ts

@@ -1,4 +1,9 @@
 import type { PlatformService } from "./platform.js";
+/**
+ * On Windows, execSync needs an explicit shell so .cmd shims resolve correctly.
+ * On Unix, undefined lets Node use the default shell.
+ */
+export declare const SHELL: string | undefined;
 export declare function getPlatform(): PlatformService;
 export type { PlatformService } from "./platform.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/platform/index.js

@@ -1,5 +1,10 @@
 import { LinuxPlatform } from "./linux.js";
 import { WindowsPlatform } from "./windows.js";
+/**
+ * On Windows, execSync needs an explicit shell so .cmd shims resolve correctly.
+ * On Unix, undefined lets Node use the default shell.
+ */
+export const SHELL = process.platform === "win32" ? "cmd.exe" : undefined;
 let _instance;
 export function getPlatform() {
     if (!_instance) {

package/dist/types.d.ts

@@ -1,7 +1,6 @@
 export interface HostConfig {
     hostId: string;
     projectRoot: string;
-    nats?: boolean;
     natsUrl?: string;
     natsWsUrl?: string;
     natsToken?: string;
@@ -29,13 +28,33 @@ export interface ParsedTask {
     frontmatter: TaskFrontmatter;
     body: string;
 }
+/**
+ * State machine: started → (pending_confirmation | pending_permission | pending_input) → finished | aborted | failed
+ *
+ * - `started`: task is actively running
+ * - `finished`: agent completed successfully
+ * - `aborted`: user declined confirmation, permission, or input
+ * - `failed`: agent exited with an error
+ */
 export type TaskRunningState = "started" | "finished" | "aborted" | "failed";
+/**
+ * Persisted to `status.json` in the task directory. Updated by the run process
+ * and read by the RPC handler + PWA to track live task state.
+ *
+ * Interactive request flow: the run process sets a `pending_*` field and waits
+ * for `user_input` to be populated by an RPC call (task.user_input). Only one
+ * `pending_*` field is set at a time.
+ */
 export interface TaskStatus {
     running_state: TaskRunningState;
     time_stamp: number;
+    /** Set when the task has `requires_confirmation` and is awaiting user approval. */
     pending_confirmation?: boolean;
+    /** Set when the agent requests permissions not yet granted. Contains the permissions needed. */
     pending_permission?: RequiredPermission[];
+    /** Set when the agent requests user input. Contains descriptions of each requested value. */
     pending_input?: string[];
+    /** Written by the RPC handler to deliver the user's response to the waiting run process. */
     user_input?: string[];
 }
 export interface HistoryEntry {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "palmier",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Palmier host CLI - provisions, executes tasks, and serves NATS RPC",
   "license": "Apache-2.0",
   "author": "Hongxu Cai",

package/src/agents/claude.ts

@@ -2,10 +2,7 @@ import type { ParsedTask, RequiredPermission } from "../types.js";
 import { execSync } from "child_process";
 import type { AgentTool, CommandLine } from "./agent.js";
 import { AGENT_INSTRUCTIONS } from "./shared-prompt.js";
-
-// execSync's shell option takes a string (shell path), not boolean.
-// On Windows we need a shell so .cmd shims resolve correctly.
-const SHELL = process.platform === "win32" ? "cmd.exe" : undefined;
+import { SHELL } from "../platform/index.js";
 
 export class ClaudeAgent implements AgentTool {
   getPlanGenerationCommandLine(prompt: string): CommandLine {

package/src/agents/codex.ts

@@ -2,13 +2,10 @@ import type { ParsedTask, RequiredPermission } from "../types.js";
 import { execSync } from "child_process";
 import type { AgentTool, CommandLine } from "./agent.js";
 import { AGENT_INSTRUCTIONS } from "./shared-prompt.js";
-
-// On Windows we need a shell so .cmd shims resolve correctly.
-const SHELL = process.platform === "win32" ? "cmd.exe" : undefined;
+import { SHELL } from "../platform/index.js";
 
 export class CodexAgent implements AgentTool {
   getPlanGenerationCommandLine(prompt: string): CommandLine {
-    // TODO: fill in
     return {
       command: "codex",
       args: ["exec", "--skip-git-repo-check", prompt],
@@ -17,8 +14,7 @@ export class CodexAgent implements AgentTool {
 
   getTaskRunCommandLine(task: ParsedTask, retryPrompt?: string, extraPermissions?: RequiredPermission[]): CommandLine {
     const prompt = AGENT_INSTRUCTIONS + "\n\n" + (retryPrompt ?? (task.body || task.frontmatter.user_prompt));
-    // TODO: Update sandbox to workspace-write once https://github.com/openai/codex/issues/12572
-    // is fixed.
+    // Using danger-full-access until workspace-write is fixed: https://github.com/openai/codex/issues/12572
     const args = ["exec", "--full-auto", "--skip-git-repo-check", "--sandbox", "danger-full-access"];
 
     const allPerms = [...(task.frontmatter.permissions ?? []), ...(extraPermissions ?? [])];

package/src/agents/gemini.ts

@@ -2,13 +2,10 @@ import type { ParsedTask, RequiredPermission } from "../types.js";
 import { execSync } from "child_process";
 import type { AgentTool, CommandLine } from "./agent.js";
 import { AGENT_INSTRUCTIONS } from "./shared-prompt.js";
-
-// On Windows we need a shell so .cmd shims resolve correctly.
-const SHELL = process.platform === "win32" ? "cmd.exe" : undefined;
+import { SHELL } from "../platform/index.js";
 
 export class GeminiAgent implements AgentTool {
   getPlanGenerationCommandLine(prompt: string): CommandLine {
-    // TODO: fill in
     return {
       command: "gemini",
       args: ["--approval-mode", "auto_edit", "--prompt", prompt],

package/src/commands/init.ts

@@ -67,7 +67,6 @@ export async function initCommand(): Promise<void> {
     const config: HostConfig = {
       hostId: registerResponse.hostId,
       projectRoot: process.cwd(),
-      nats: true,
       natsUrl: registerResponse.natsUrl,
       natsWsUrl: registerResponse.natsWsUrl,
       natsToken: registerResponse.natsToken,

package/src/commands/lan.ts

@@ -1,24 +1,14 @@
 import * as fs from "fs";
-import * as path from "path";
 import { loadConfig, CONFIG_DIR } from "../config.js";
 import { createRpcHandler } from "../rpc-handler.js";
 import { startHttpTransport, detectLanIp } from "../transports/http-transport.js";
-
-const LAN_LOCKFILE = path.join(CONFIG_DIR, "lan.json");
+import { generatePairingCode } from "../pairing.js";
+import { LAN_LOCKFILE } from "../lan-lock.js";
 
 const bold = (s: string) => `\x1b[1m${s}\x1b[0m`;
 const cyan = (s: string) => `\x1b[36m${s}\x1b[0m`;
 const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
 
-const CODE_CHARS = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
-const CODE_LENGTH = 6;
-
-function generateCode(): string {
-  const bytes = new Uint8Array(CODE_LENGTH);
-  crypto.getRandomValues(bytes);
-  return Array.from(bytes, (b) => CODE_CHARS[b % CODE_CHARS.length]).join("");
-}
-
 function writeLockfile(port: number): void {
   fs.mkdirSync(CONFIG_DIR, { recursive: true });
   fs.writeFileSync(LAN_LOCKFILE, JSON.stringify({ port, pid: process.pid }), "utf-8");
@@ -36,7 +26,7 @@ export async function lanCommand(opts: { port: number }): Promise<void> {
   const config = loadConfig();
   const port = opts.port;
   const ip = detectLanIp();
-  const code = generateCode();
+  const code = generatePairingCode();
 
   const handleRpc = createRpcHandler(config);
 

package/src/commands/pair.ts

@@ -1,23 +1,12 @@
-import * as fs from "fs";
-import * as path from "path";
 import * as http from "node:http";
 import { StringCodec } from "nats";
-import { loadConfig, CONFIG_DIR } from "../config.js";
+import { loadConfig } from "../config.js";
 import { connectNats } from "../nats-client.js";
 import { addSession } from "../session-store.js";
+import { generatePairingCode, PAIRING_EXPIRY_MS } from "../pairing.js";
+import { getLanPort } from "../lan-lock.js";
 import type { HostConfig } from "../types.js";
 
-const CODE_CHARS = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"; // no O/0/I/1/L
-const CODE_LENGTH = 6;
-const EXPIRY_MS = 5 * 60 * 1000; // 5 minutes
-const LAN_LOCKFILE = path.join(CONFIG_DIR, "lan.json");
-
-function generateCode(): string {
-  const bytes = new Uint8Array(CODE_LENGTH);
-  crypto.getRandomValues(bytes);
-  return Array.from(bytes, (b) => CODE_CHARS[b % CODE_CHARS.length]).join("");
-}
-
 function buildPairResponse(config: HostConfig, label?: string) {
   const session = addSession(label);
   return {
@@ -30,7 +19,7 @@ function buildPairResponse(config: HostConfig, label?: string) {
  * POST to the running LAN server and long-poll until paired or expired.
  */
 function lanPairRegister(port: number, code: string): Promise<boolean> {
-  const body = JSON.stringify({ code, expiryMs: EXPIRY_MS });
+  const body = JSON.stringify({ code, expiryMs: PAIRING_EXPIRY_MS });
 
   return new Promise((resolve) => {
     const req = http.request(
@@ -40,7 +29,7 @@ function lanPairRegister(port: number, code: string): Promise<boolean> {
         path: "/internal/pair-register",
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        timeout: EXPIRY_MS + 5000,
+        timeout: PAIRING_EXPIRY_MS + 5000,
       },
       (res) => {
         const chunks: Buffer[] = [];
@@ -62,23 +51,13 @@ function lanPairRegister(port: number, code: string): Promise<boolean> {
   });
 }
 
-/**
- * Read the LAN lockfile to check if `palmier lan` is running.
- */
-function getLanPort(): number | null {
-  try {
-    const raw = fs.readFileSync(LAN_LOCKFILE, "utf-8");
-    return (JSON.parse(raw) as { port: number }).port;
-  } catch { return null; }
-}
-
 /**
  * Generate an OTP code and wait for a PWA client to pair.
  * Listens on NATS always, and also on the LAN server if `palmier lan` is running.
  */
 export async function pairCommand(): Promise<void> {
   const config = loadConfig();
-  const code = generateCode();
+  const code = generatePairingCode();
 
   let paired = false;
 
@@ -140,7 +119,7 @@ export async function pairCommand(): Promise<void> {
   const start = Date.now();
   await new Promise<void>((resolve) => {
     const interval = setInterval(() => {
-      if (paired || Date.now() - start >= EXPIRY_MS) {
+      if (paired || Date.now() - start >= PAIRING_EXPIRY_MS) {
         clearInterval(interval);
         resolve();
       }

package/src/commands/run.ts

@@ -264,18 +264,15 @@ async function runCommandTriggeredMode(
     env: { ...ctx.guiEnv, PALMIER_TASK_ID: ctx.task.frontmatter.id },
   });
 
-  // Stats
   let linesProcessed = 0;
   let invocationsSucceeded = 0;
   let invocationsFailed = 0;
 
-  // Bounded queue for incoming lines
   const lineQueue: string[] = [];
   let processing = false;
   let commandExited = false;
   let resolveWhenDone: (() => void) | undefined;
 
-  // Rolling log of per-line agent outputs
   const logPath = path.join(ctx.taskDir, "command-output.log");
   function appendLog(line: string, agentOutput: string, outcome: string) {
     const entry = `[${new Date().toISOString()}] (${outcome}) input: ${line}\n${agentOutput}\n---\n`;
@@ -333,10 +330,9 @@ async function runCommandTriggeredMode(
     }
   }
 
-  // Read stdout line by line
   const rl = readline.createInterface({ input: child.stdout! });
   rl.on("line", (line: string) => {
-    if (!line.trim()) return; // skip empty lines
+    if (!line.trim()) return;
     if (lineQueue.length >= MAX_QUEUE_SIZE) {
       console.warn(`[command-triggered] Queue full, dropping oldest line.`);
       lineQueue.shift();
@@ -348,7 +344,6 @@ async function runCommandTriggeredMode(
     });
   });
 
-  // Log stderr
   child.stderr?.on("data", (d: Buffer) => process.stderr.write(d));
 
   // Wait for command to exit
@@ -383,9 +378,7 @@ async function runCommandTriggeredMode(
     `Agent invocations failed: ${invocationsFailed}`,
   ].join("\n");
 
-  // Command-triggered tasks run until the command exits — any exit is a normal finish.
-  const outcome: TaskRunningState = "finished";
-  return { outcome, endTime, output: summary };
+  return { outcome: "finished", endTime, output: summary };
 }
 
 async function publishTaskEvent(
@@ -422,6 +415,22 @@ async function publishConfirmResolved(
   });
 }
 
+/**
+ * Watch status.json until user_input is populated by an RPC call, then resolve.
+ * All interactive request flows (confirmation, permission, user input) share this.
+ */
+function waitForUserInput(taskDir: string): Promise<string[]> {
+  const statusPath = path.join(taskDir, "status.json");
+  return new Promise<string[]>((resolve) => {
+    const watcher = fs.watch(statusPath, () => {
+      const status = readTaskStatus(taskDir);
+      if (!status || !status.user_input?.length) return;
+      watcher.close();
+      resolve(status.user_input);
+    });
+  });
+}
+
 async function requestPermission(
   nc: NatsConnection | undefined,
   config: HostConfig,
@@ -429,32 +438,23 @@ async function requestPermission(
   taskDir: string,
   requiredPermissions: RequiredPermission[],
 ): Promise<"granted" | "granted_all" | "aborted"> {
-  const taskId = task.frontmatter.id;
-  const statusPath = path.join(taskDir, "status.json");
-
   const currentStatus = readTaskStatus(taskDir)!;
   writeTaskStatus(taskDir, { ...currentStatus, pending_permission: requiredPermissions });
 
-  await publishHostEvent(nc, config.hostId, taskId, {
+  await publishHostEvent(nc, config.hostId, task.frontmatter.id, {
     event_type: "permission-request",
     host_id: config.hostId,
     required_permissions: requiredPermissions,
     name: task.frontmatter.name,
   });
 
-  return new Promise<"granted" | "granted_all" | "aborted">((resolve) => {
-    const watcher = fs.watch(statusPath, () => {
-      const status = readTaskStatus(taskDir);
-      if (!status || !status.user_input?.length) return;
-      watcher.close();
-      const response = status.user_input[0] as "granted" | "granted_all" | "aborted";
-      writeTaskStatus(taskDir, {
-        running_state: response === "aborted" ? "aborted" : "started",
-        time_stamp: Date.now(),
-      });
-      resolve(response);
-    });
+  const userInput = await waitForUserInput(taskDir);
+  const response = userInput[0] as "granted" | "granted_all" | "aborted";
+  writeTaskStatus(taskDir, {
+    running_state: response === "aborted" ? "aborted" : "started",
+    time_stamp: Date.now(),
   });
+  return response;
 }
 
 async function publishPermissionResolved(
@@ -477,34 +477,23 @@ async function requestUserInput(
   taskDir: string,
   inputDescriptions: string[],
 ): Promise<string[] | "aborted"> {
-  const taskId = task.frontmatter.id;
-  const statusPath = path.join(taskDir, "status.json");
-
   const currentStatus = readTaskStatus(taskDir)!;
   writeTaskStatus(taskDir, { ...currentStatus, pending_input: inputDescriptions });
 
-  await publishHostEvent(nc, config.hostId, taskId, {
+  await publishHostEvent(nc, config.hostId, task.frontmatter.id, {
     event_type: "input-request",
     host_id: config.hostId,
     input_descriptions: inputDescriptions,
     name: task.frontmatter.name,
   });
 
-  return new Promise<string[] | "aborted">((resolve) => {
-    const watcher = fs.watch(statusPath, () => {
-      const status = readTaskStatus(taskDir);
-      if (!status || !status.user_input?.length) return;
-      watcher.close();
-      const response = status.user_input;
-      if (response.length === 1 && response[0] === "aborted") {
-        writeTaskStatus(taskDir, { running_state: "aborted", time_stamp: Date.now() });
-        resolve("aborted");
-      } else {
-        writeTaskStatus(taskDir, { running_state: "started", time_stamp: Date.now() });
-        resolve(response);
-      }
-    });
-  });
+  const userInput = await waitForUserInput(taskDir);
+  if (userInput.length === 1 && userInput[0] === "aborted") {
+    writeTaskStatus(taskDir, { running_state: "aborted", time_stamp: Date.now() });
+    return "aborted";
+  }
+  writeTaskStatus(taskDir, { running_state: "started", time_stamp: Date.now() });
+  return userInput;
 }
 
 async function publishInputResolved(
@@ -526,34 +515,21 @@ async function requestConfirmation(
   task: ParsedTask,
   taskDir: string,
 ): Promise<boolean> {
-  const taskId = task.frontmatter.id;
-  const statusPath = path.join(taskDir, "status.json");
-
-  // Flag that we're awaiting user confirmation
   const currentStatus = readTaskStatus(taskDir)!;
   writeTaskStatus(taskDir, { ...currentStatus, pending_confirmation: true });
 
-  // Publish confirmation request via NATS and/or HTTP SSE
-  await publishHostEvent(nc, config.hostId, taskId, {
+  await publishHostEvent(nc, config.hostId, task.frontmatter.id, {
     event_type: "confirm-request",
     host_id: config.hostId,
   });
 
-  // Wait for task.user_input RPC to set user_input in status.json
-  return new Promise<boolean>((resolve) => {
-    const watcher = fs.watch(statusPath, () => {
-      const status = readTaskStatus(taskDir);
-      if (!status || !status.user_input?.length) return; // still pending
-      watcher.close();
-      const confirmed = status.user_input[0] === "confirmed";
-      // Clear pending_confirmation/user_input and update running_state
-      writeTaskStatus(taskDir, {
-        running_state: confirmed ? "started" : "aborted",
-        time_stamp: Date.now(),
-      });
-      resolve(confirmed);
-    });
+  const userInput = await waitForUserInput(taskDir);
+  const confirmed = userInput[0] === "confirmed";
+  writeTaskStatus(taskDir, {
+    running_state: confirmed ? "started" : "aborted",
+    time_stamp: Date.now(),
   });
+  return confirmed;
 }
 
 /**

package/src/config.ts

@@ -29,7 +29,6 @@ export function loadConfig(): HostConfig {
     throw new Error("Invalid host config: missing natsUrl or natsToken");
   }
 
-  config.nats = true;
   return config;
 }
 

package/src/events.ts

@@ -1,20 +1,7 @@
-import * as fs from "fs";
-import * as path from "path";
 import { StringCodec, type NatsConnection } from "nats";
-import { CONFIG_DIR } from "./config.js";
+import { getLanPort } from "./lan-lock.js";
 
 const sc = StringCodec();
-const LAN_LOCKFILE = path.join(CONFIG_DIR, "lan.json");
-
-/**
- * Read the LAN lockfile to determine if `palmier lan` is running.
- */
-function getLanPort(): number | null {
-  try {
-    const raw = fs.readFileSync(LAN_LOCKFILE, "utf-8");
-    return (JSON.parse(raw) as { port: number }).port;
-  } catch { return null; }
-}
 
 /**
  * Broadcast an event to connected clients via NATS and HTTP SSE (if LAN server is running).

package/src/lan-lock.ts

@@ -0,0 +1,16 @@
+import * as fs from "fs";
+import * as path from "path";
+import { CONFIG_DIR } from "./config.js";
+
+export const LAN_LOCKFILE = path.join(CONFIG_DIR, "lan.json");
+
+/**
+ * Read the LAN lockfile to determine if `palmier lan` is running.
+ * Returns the port number, or null if not running.
+ */
+export function getLanPort(): number | null {
+  try {
+    const raw = fs.readFileSync(LAN_LOCKFILE, "utf-8");
+    return (JSON.parse(raw) as { port: number }).port;
+  } catch { return null; }
+}

package/src/pairing.ts

@@ -0,0 +1,10 @@
+const CODE_CHARS = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"; // no O/0/I/1/L
+const CODE_LENGTH = 6;
+
+export const PAIRING_EXPIRY_MS = 5 * 60 * 1000; // 5 minutes
+
+export function generatePairingCode(): string {
+  const bytes = new Uint8Array(CODE_LENGTH);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => CODE_CHARS[b % CODE_CHARS.length]).join("");
+}

package/src/platform/index.ts

@@ -2,6 +2,12 @@ import type { PlatformService } from "./platform.js";
 import { LinuxPlatform } from "./linux.js";
 import { WindowsPlatform } from "./windows.js";
 
+/**
+ * On Windows, execSync needs an explicit shell so .cmd shims resolve correctly.
+ * On Unix, undefined lets Node use the default shell.
+ */
+export const SHELL: string | undefined = process.platform === "win32" ? "cmd.exe" : undefined;
+
 let _instance: PlatformService | undefined;
 
 export function getPlatform(): PlatformService {

package/src/types.ts

@@ -2,8 +2,6 @@ export interface HostConfig {
   hostId: string;
   projectRoot: string;
 
-  // NATS (always enabled)
-  nats?: boolean;
   natsUrl?: string;
   natsWsUrl?: string;
   natsToken?: string;
@@ -34,14 +32,34 @@ export interface ParsedTask {
   body: string;
 }
 
+/**
+ * State machine: started → (pending_confirmation | pending_permission | pending_input) → finished | aborted | failed
+ *
+ * - `started`: task is actively running
+ * - `finished`: agent completed successfully
+ * - `aborted`: user declined confirmation, permission, or input
+ * - `failed`: agent exited with an error
+ */
 export type TaskRunningState = "started" | "finished" | "aborted" | "failed";
 
+/**
+ * Persisted to `status.json` in the task directory. Updated by the run process
+ * and read by the RPC handler + PWA to track live task state.
+ *
+ * Interactive request flow: the run process sets a `pending_*` field and waits
+ * for `user_input` to be populated by an RPC call (task.user_input). Only one
+ * `pending_*` field is set at a time.
+ */
 export interface TaskStatus {
   running_state: TaskRunningState;
   time_stamp: number;
+  /** Set when the task has `requires_confirmation` and is awaiting user approval. */
   pending_confirmation?: boolean;
+  /** Set when the agent requests permissions not yet granted. Contains the permissions needed. */
   pending_permission?: RequiredPermission[];
+  /** Set when the agent requests user input. Contains descriptions of each requested value. */
   pending_input?: string[];
+  /** Written by the RPC handler to deliver the user's response to the waiting run process. */
   user_input?: string[];
 }