palmier 0.8.0 → 0.8.3

package/dist/mcp-tools.js

@@ -400,9 +400,9 @@ const sendSmsTool = {
     async handler(args, ctx) {
         if (!ctx.nc)
             throw new ToolError("Not connected to server (NATS unavailable)", 503);
-        const device = getCapabilityDevice("sms");
+        const device = getCapabilityDevice("sms-send");
         if (!device)
-            throw new ToolError("No device has SMS access enabled", 400);
+            throw new ToolError("No device has SMS Send enabled", 400);
         const { to, body } = args;
         if (!to || !body)
             throw new ToolError("to and body are required", 400);
@@ -433,10 +433,10 @@ const sendSmsTool = {
         return result;
     },
 };
-const sendAlertTool = {
-    name: "send-alert",
+const sendAlarmTool = {
+    name: "send-alarm",
     description: [
-        "Send an alert to the user's mobile device with an alarm sound and full-screen popup.",
+        "Trigger an alarm on the user's mobile device with an alarm sound and full-screen popup.",
         "Use this to urgently get the user's attention. The device will play an alarm sound and show a full-screen dialog even on the lock screen.",
         "Blocks until the device responds (up to 30 seconds).",
         'Response: `{"ok": true}` on success, or `{"error": "..."}` on failure.',
@@ -444,17 +444,17 @@ const sendAlertTool = {
     inputSchema: {
         type: "object",
         properties: {
-            title: { type: "string", description: "Alert title" },
-            description: { type: "string", description: "Alert description/details" },
+            title: { type: "string", description: "Alarm title" },
+            description: { type: "string", description: "Alarm description/details" },
         },
         required: ["title"],
     },
     async handler(args, ctx) {
         if (!ctx.nc)
             throw new ToolError("Not connected to server (NATS unavailable)", 503);
-        const device = getCapabilityDevice("alert");
+        const device = getCapabilityDevice("alarm");
         if (!device)
-            throw new ToolError("No device has alert access enabled", 400);
+            throw new ToolError("No device has alarm access enabled", 400);
         const { title, description } = args;
         if (!title)
             throw new ToolError("title is required", 400);
@@ -465,12 +465,12 @@ const sendAlertTool = {
         };
         if (description)
             payload.description = description;
-        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.alert`, sc.encode(JSON.stringify(payload)), { timeout: 5_000 });
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.alarm`, sc.encode(JSON.stringify(payload)), { timeout: 5_000 });
         const ack = JSON.parse(sc.decode(ackReply.data));
         if (ack.error)
             throw new ToolError(ack.error, 502);
         const responsePromise = new Promise((resolve, reject) => {
-            const sub = ctx.nc.subscribe(`host.${ctx.config.hostId}.alert.${ctx.sessionId}`, { max: 1 });
+            const sub = ctx.nc.subscribe(`host.${ctx.config.hostId}.alarm.${ctx.sessionId}`, { max: 1 });
             const timer = setTimeout(() => {
                 sub.unsubscribe();
                 reject(new ToolError("Device did not respond within 30 seconds", 504));
@@ -597,9 +597,9 @@ const sendEmailTool = {
     async handler(args, ctx) {
         if (!ctx.nc)
             throw new ToolError("Not connected to server (NATS unavailable)", 503);
-        const device = getCapabilityDevice("email");
+        const device = getCapabilityDevice("send-email");
         if (!device)
-            throw new ToolError("No device has email access enabled", 400);
+            throw new ToolError("No device has send-email access enabled", 400);
         const { to, subject, body, cc, bcc } = args;
         if (!to)
             throw new ToolError("to is required", 400);
@@ -639,7 +639,7 @@ const sendEmailTool = {
         return result;
     },
 };
-export const agentTools = [notifyTool, requestInputTool, requestConfirmationTool, deviceGeolocationTool, readContactsTool, createContactTool, readCalendarTool, createCalendarEventTool, sendSmsTool, sendEmailTool, sendAlertTool, readBatteryTool, setRingerModeTool];
+export const agentTools = [notifyTool, requestInputTool, requestConfirmationTool, deviceGeolocationTool, readContactsTool, createContactTool, readCalendarTool, createCalendarEventTool, sendSmsTool, sendEmailTool, sendAlarmTool, readBatteryTool, setRingerModeTool];
 export const agentToolMap = new Map(agentTools.map((t) => [t.name, t]));
 const deviceNotificationsResource = {
     uri: "notifications://device",
@@ -667,9 +667,6 @@ const deviceSmsResource = {
 };
 export const agentResources = [deviceNotificationsResource, deviceSmsResource];
 export const agentResourceMap = new Map(agentResources.map((r) => [r.uri, r]));
-/**
- * Generate the HTTP Endpoints markdown section for agent-instructions.md from the tool registry.
- */
 export function generateEndpointDocs(port, taskId, tools = agentTools, resources = agentResources) {
     const baseUrl = `http://localhost:${port}`;
     const lines = [
@@ -680,7 +677,6 @@ export function generateEndpointDocs(port, taskId, tools = agentTools, resources
         const schema = tool.inputSchema;
         const props = schema.properties ?? {};
         const required = new Set(schema.required ?? []);
-        // Build example JSON (body only, no taskId)
         const example = {};
         for (const [key, prop] of Object.entries(props)) {
             if (prop.type === "array")

package/dist/nats-client.d.ts

@@ -1,7 +1,4 @@
 import { type NatsConnection } from "nats";
 import type { HostConfig } from "./types.js";
-/**
- * Connect to NATS using the host config's JWT credentials.
- */
 export declare function connectNats(config: HostConfig): Promise<NatsConnection>;
 //# sourceMappingURL=nats-client.d.ts.map

package/dist/nats-client.js

@@ -1,7 +1,4 @@
 import { connect, jwtAuthenticator } from "nats";
-/**
- * Connect to NATS using the host config's JWT credentials.
- */
 export async function connectNats(config) {
     if (!config.natsJwt || !config.natsNkeySeed) {
         throw new Error("NATS JWT credentials not configured. Re-run palmier init.");
@@ -10,7 +7,7 @@ export async function connectNats(config) {
         servers: config.natsUrl,
         authenticator: jwtAuthenticator(config.natsJwt, new TextEncoder().encode(config.natsNkeySeed)),
     });
-    // Do not log anything as that will pollute stdout for mcp server.
+    // Do not log — it would pollute stdout for the MCP server.
     return nc;
 }
 //# sourceMappingURL=nats-client.js.map

package/dist/pending-requests.d.ts

@@ -17,29 +17,15 @@ export interface PendingRequest {
     meta?: PendingRequestMeta;
 }
 /**
- * Register a pending request keyed by either a sessionId (confirmation / input)
- * or a taskId (permission). The `meta` is surfaced to PWAs that connect after
- * the request was opened, so their modals can render without replaying events.
- * Only one pending request per key at a time.
+ * Key is sessionId for confirmation/input, taskId for permission. Only one
+ * pending request per key at a time. `meta` is surfaced via host.info so a
+ * freshly-connected PWA can render the modal without replaying events.
  */
 export declare function registerPending(key: string, type: PendingRequest["type"], params?: PendingRequest["params"], meta?: PendingRequestMeta): Promise<string[]>;
-/**
- * Resolve a pending request with the user's response.
- * Returns true if a pending request was found and resolved.
- */
 export declare function resolvePending(key: string, value: string[]): boolean;
-/**
- * Get the current pending request for a key (if any).
- */
 export declare function getPending(key: string): PendingRequest | undefined;
-/**
- * Remove a pending request without resolving it.
- */
 export declare function removePending(key: string): void;
-/**
- * List all currently-pending requests, stripped of the unserializable `resolve`
- * callback. Used by `host.info` so the PWA can seed its modal state on connect.
- */
+/** Pending requests stripped of the unserializable `resolve` callback. */
 export declare function listPending(): Array<{
     key: string;
     type: PendingRequest["type"];

package/dist/pending-requests.js

@@ -1,9 +1,8 @@
 const pending = new Map();
 /**
- * Register a pending request keyed by either a sessionId (confirmation / input)
- * or a taskId (permission). The `meta` is surfaced to PWAs that connect after
- * the request was opened, so their modals can render without replaying events.
- * Only one pending request per key at a time.
+ * Key is sessionId for confirmation/input, taskId for permission. Only one
+ * pending request per key at a time. `meta` is surfaced via host.info so a
+ * freshly-connected PWA can render the modal without replaying events.
  */
 export function registerPending(key, type, params, meta) {
     if (pending.has(key)) {
@@ -13,10 +12,6 @@ export function registerPending(key, type, params, meta) {
         pending.set(key, { type, resolve, params, meta });
     });
 }
-/**
- * Resolve a pending request with the user's response.
- * Returns true if a pending request was found and resolved.
- */
 export function resolvePending(key, value) {
     const entry = pending.get(key);
     if (!entry)
@@ -25,22 +20,13 @@ export function resolvePending(key, value) {
     entry.resolve(value);
     return true;
 }
-/**
- * Get the current pending request for a key (if any).
- */
 export function getPending(key) {
     return pending.get(key);
 }
-/**
- * Remove a pending request without resolving it.
- */
 export function removePending(key) {
     pending.delete(key);
 }
-/**
- * List all currently-pending requests, stripped of the unserializable `resolve`
- * callback. Used by `host.info` so the PWA can seed its modal state on connect.
- */
+/** Pending requests stripped of the unserializable `resolve` callback. */
 export function listPending() {
     return [...pending.entries()].map(([key, entry]) => ({
         key,

package/dist/platform/index.d.ts

@@ -1,8 +1,5 @@
 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.
- */
+/** Windows needs an explicit shell for execSync to resolve .cmd shims. */
 export declare const SHELL: string | undefined;
 export declare function getPlatform(): PlatformService;
 export type { PlatformService } from "./platform.js";

package/dist/platform/index.js

@@ -1,9 +1,6 @@
 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.
- */
+/** Windows needs an explicit shell for execSync to resolve .cmd shims. */
 export const SHELL = process.platform === "win32" ? "cmd.exe" : undefined;
 let _instance;
 export function getPlatform() {

package/dist/platform/linux.d.ts

@@ -1,15 +1,9 @@
 import type { PlatformService } from "./platform.js";
 import type { HostConfig, ParsedTask } from "../types.js";
 /**
- * Convert a cron expression to a systemd OnCalendar string.
- *
- * Only the 4 cron patterns the PWA UI can produce are supported:
- *   hourly:  "0 * * * *"
- *   daily:   "MM HH * * *"
- *   weekly:  "MM HH * * D"
- *   monthly: "MM HH D * *"
- * Arbitrary cron expressions (ranges, lists, steps beyond hourly) are NOT
- * handled because the UI never generates them.
+ * Only the 4 cron patterns the PWA UI produces are supported:
+ *   hourly "0 * * * *", daily "MM HH * * *", weekly "MM HH * * D", monthly "MM HH D * *".
+ * Arbitrary expressions (ranges, lists, sub-hour steps) are not handled.
  */
 export declare function cronToOnCalendar(cron: string): string;
 export declare class LinuxPlatform implements PlatformService {

package/dist/platform/linux.js

@@ -15,15 +15,9 @@ function getServiceName(taskId) {
     return `palmier-task-${taskId}.service`;
 }
 /**
- * Convert a cron expression to a systemd OnCalendar string.
- *
- * Only the 4 cron patterns the PWA UI can produce are supported:
- *   hourly:  "0 * * * *"
- *   daily:   "MM HH * * *"
- *   weekly:  "MM HH * * D"
- *   monthly: "MM HH D * *"
- * Arbitrary cron expressions (ranges, lists, steps beyond hourly) are NOT
- * handled because the UI never generates them.
+ * Only the 4 cron patterns the PWA UI produces are supported:
+ *   hourly "0 * * * *", daily "MM HH * * *", weekly "MM HH * * D", monthly "MM HH D * *".
+ * Arbitrary expressions (ranges, lists, sub-hour steps) are not handled.
  */
 export function cronToOnCalendar(cron) {
     const parts = cron.trim().split(/\s+/);
@@ -31,7 +25,6 @@ export function cronToOnCalendar(cron) {
         throw new Error(`Invalid cron expression (expected 5 fields): ${cron}`);
     }
     const [minute, hour, dayOfMonth, , dayOfWeek] = parts;
-    // Map cron day-of-week numbers to systemd abbreviated names
     const dowMap = {
         "0": "Sun", "1": "Mon", "2": "Tue", "3": "Wed",
         "4": "Thu", "5": "Fri", "6": "Sat", "7": "Sun",
@@ -59,8 +52,8 @@ export class LinuxPlatform {
     installDaemon(config) {
         fs.mkdirSync(UNIT_DIR, { recursive: true });
         const palmierBin = process.argv[1] || "palmier";
-        // Save the user's shell PATH so restartDaemon can use it later
-        // (the daemon itself runs under systemd with a limited PATH).
+        // Save the user's shell PATH so restartDaemon can reuse it later — under
+        // systemd the daemon itself runs with a limited PATH.
         const userPath = process.env.PATH || "/usr/local/bin:/usr/bin:/bin";
         fs.mkdirSync(path.dirname(PATH_FILE), { recursive: true });
         fs.writeFileSync(PATH_FILE, userPath, "utf-8");
@@ -93,7 +86,7 @@ WantedBy=default.target
             console.error(`Warning: failed to enable systemd service: ${err}`);
             console.error("You may need to start it manually: systemctl --user enable --now palmier.service");
         }
-        // Enable lingering so service runs without active login session
+        // Lingering lets the service run without an active login session.
         try {
             execSync(`loginctl enable-linger ${process.env.USER || ""}`, { stdio: "inherit" });
             console.log("Login lingering enabled.");
@@ -109,13 +102,11 @@ WantedBy=default.target
             execSync("systemctl --user disable palmier.service 2>/dev/null", { stdio: "pipe" });
         }
         catch { /* service may not exist */ }
-        // Remove daemon service file
         const servicePath = path.join(UNIT_DIR, "palmier.service");
         try {
             fs.unlinkSync(servicePath);
         }
         catch { /* ignore */ }
-        // Remove all task timers and services
         try {
             const files = fs.readdirSync(UNIT_DIR).filter((f) => f.startsWith("palmier-task-"));
             for (const f of files) {
@@ -142,8 +133,8 @@ WantedBy=default.target
         console.log("Palmier daemon and tasks uninstalled.");
     }
     async restartDaemon() {
-        // If called from a user's terminal, save the current PATH for future use.
-        // If called from the daemon (auto-update), read the saved PATH instead.
+        // From a TTY, snapshot the current PATH; from the daemon (auto-update),
+        // reuse whatever was last saved.
         if (process.stdin.isTTY) {
             fs.mkdirSync(path.dirname(PATH_FILE), { recursive: true });
             fs.writeFileSync(PATH_FILE, process.env.PATH || "", "utf-8");
@@ -181,7 +172,6 @@ Environment=PATH=${process.env.PATH || "/usr/local/bin:/usr/bin:/bin"}
 `;
         fs.writeFileSync(path.join(UNIT_DIR, serviceName), serviceContent, "utf-8");
         daemonReload();
-        // Only create and enable a timer if the schedule exists and is enabled
         if (!task.frontmatter.schedule_enabled)
             return;
         const scheduleType = task.frontmatter.schedule_type;
@@ -248,7 +238,6 @@ WantedBy=timers.target
         await execAsync(`systemctl --user stop ${serviceName}`);
     }
     isTaskRunning(taskId) {
-        // Check systemd first (for scheduled/on-demand runs)
         const serviceName = getServiceName(taskId);
         try {
             const out = execSync(`systemctl --user show -p ActiveState --value ${serviceName}`, { encoding: "utf-8" });
@@ -257,7 +246,7 @@ WantedBy=timers.target
                 return true;
         }
         catch { /* service may not exist */ }
-        // Fall back to PID check (for follow-up runs spawned directly)
+        // Follow-up runs are spawned directly, so check PID too.
         try {
             const taskDir = getTaskDir(loadConfig().projectRoot, taskId);
             const status = readTaskStatus(taskDir);

package/dist/platform/platform.d.ts

@@ -1,8 +1,5 @@
 import type { HostConfig, ParsedTask } from "../types.js";
-/**
- * Abstracts OS-specific daemon, scheduling, and process management.
- * Linux uses systemd; Windows uses Task Scheduler; macOS will use launchd.
- */
+/** Linux: systemd. Windows: Task Scheduler. macOS: launchd (planned). */
 export interface PlatformService {
     /** Install the main `palmier serve` daemon to start at boot. */
     installDaemon(config: HostConfig): void;

package/dist/platform/windows.d.ts

@@ -12,17 +12,14 @@ import type { HostConfig, ParsedTask } from "../types.js";
  *   monthly: "MM HH D * *"
  */
 export declare function scheduleValueToXml(scheduleType: "crons" | "specific_times", value: string): string;
-/**
- * Build a complete Task Scheduler XML definition.
- */
 export declare function buildTaskXml(tr: string, triggers: string[], foreground?: boolean): string;
 export declare class WindowsPlatform implements PlatformService {
     installDaemon(config: HostConfig): void;
     uninstallDaemon(): void;
     restartDaemon(): Promise<void>;
-    /** Create or update the Task Scheduler entry for the daemon (requires elevation for S4U). */
+    /** S4U LogonType requires elevation to create. */
     private ensureDaemonTask;
-    /** 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;
     installTaskTimer(config: HostConfig, task: ParsedTask): void;
     removeTaskTimer(taskId: string): void;

package/dist/platform/windows.js

@@ -26,27 +26,20 @@ export function scheduleValueToXml(scheduleType, value) {
         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, triggers, foreground) {
     const [command, ...argParts] = tr.match(/"[^"]*"|[^\s]+/g) ?? [];
     const commandStr = command?.replace(/"/g, "") ?? "";
@@ -82,20 +75,17 @@ function schtasksTaskName(taskId) {
 export class WindowsPlatform {
     installDaemon(config) {
         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!");
     }
     uninstallDaemon() {
         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'`,
@@ -103,7 +93,6 @@ export class WindowsPlatform {
             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")) {
@@ -126,15 +115,13 @@ export class WindowsPlatform {
     }
     async restartDaemon() {
         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. */
     ensureDaemonTask(script) {
         const tn = `\\Palmier\\${DAEMON_TASK_NAME}`;
         const tr = `"${process.execPath}" "${script}" serve`;
@@ -143,7 +130,7 @@ export class WindowsPlatform {
         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}'`,
@@ -160,7 +147,7 @@ export class WindowsPlatform {
             catch { /* ignore */ }
         }
     }
-    /** 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. */
     startDaemonTask() {
         const tn = `\\Palmier\\${DAEMON_TASK_NAME}`;
         try {
@@ -177,9 +164,8 @@ export class WindowsPlatform {
         const tn = schtasksTaskName(taskId);
         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 = [];
         const scheduleType = task.frontmatter.schedule_type;
         const scheduleValues = task.frontmatter.schedule_values;
@@ -194,18 +180,18 @@ export class WindowsPlatform {
                 }
             }
         }
-        // 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", [
@@ -228,9 +214,7 @@ export class WindowsPlatform {
         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) {
         const tn = schtasksTaskName(taskId);
@@ -243,8 +227,8 @@ export class WindowsPlatform {
         }
     }
     async stopTask(taskId) {
-        // 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);
@@ -254,9 +238,8 @@ export class WindowsPlatform {
             }
         }
         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 });
@@ -267,7 +250,6 @@ export class WindowsPlatform {
         }
     }
     isTaskRunning(taskId) {
-        // Check Task Scheduler first (for scheduled/on-demand runs)
         const tn = schtasksTaskName(taskId);
         try {
             const out = execFileSync("schtasks", ["/query", "/tn", tn, "/fo", "CSV", "/nh"], {
@@ -278,18 +260,17 @@ export class WindowsPlatform {
                 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,
@@ -303,7 +284,6 @@ export class WindowsPlatform {
         return false;
     }
     getGuiEnv() {
-        // Windows GUI is always available — no special env vars needed
         return {};
     }
 }