@haemmid/pi-processes 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning for public releases.
 
+## [0.9.3] - 2026-07-02
+
+### Fixed
+
+- `restart` waits for old process to fully exit before starting replacement;
+  does not start a new process if the old one does not exit within timeout.
+- `restart` error message now shows the actual signal used (SIGTERM vs SIGKILL)
+  depending on `force` parameter.
+- Ambiguous name errors now include exact process IDs in the suggestion.
+- Added manager-level regression tests for `restart`: no premature spawn,
+  timeout handling, force=SIGKILL, post-restart resolve, ambiguous name rejection.
+
+## [0.9.2] - 2026-07-02
+
+### Added
+
+- `ensure` action for idempotent dev-server workflows.
+- `ensure` reuses existing process when name+command+cwd match.
+- `ensure` returns conflict error when name matches but configuration differs.
+- `ensure` returns next commands (output/logs/restart/kill by name).
+
+### Changed
+
+- Version bumped to 0.9.2.
+
 ## [0.9.1] - 2026-07-02
 
 ### Added

package/README.md

@@ -94,7 +94,7 @@ For Astro/Vite dev servers, ask the agent:
 
 ```text
 Use the process tool for the Astro dev server.
-Start `npm run dev -- --host 0.0.0.0` as `my-site:astro`.
+Ensure `npm run dev -- --host 0.0.0.0` is running as `my-site:astro`.
 Use `process output` when you need logs.
 Do not restart after ordinary .astro, .ts, or .css edits.
 Restart only after package/config/env changes or if the server exits.
@@ -104,10 +104,10 @@ Typical tool flow:
 
 ```text
 process list
-process start "npm run dev -- --host 0.0.0.0" name="my-site:astro"
-process output id="my-site:astro"
+process ensure "npm run dev -- --host 0.0.0.0" name="my-site:astro"
+process output name="my-site:astro"
 process restart "npm run dev -- --host 0.0.0.0" name="my-site:astro"
-process kill id="my-site:astro"
+process kill name="my-site:astro"
 ```
 
 ## Demo
@@ -156,7 +156,8 @@ The tool is named `process`.
 
 | Action | Description |
 |--------|-------------|
-| `start` | Start a managed process. |
+| `start` | Start a managed process (refuses if a live process with the same name exists). |
+| `ensure` | Idempotent start: reuse existing process if name+command+cwd match, start new otherwise. |
 | `restart` | Kill existing process and start a new one (safe: await kill → start). |
 | `list` | List managed processes. |
 | `output` | Return a one-off tailed stdout/stderr snapshot. |
@@ -170,6 +171,8 @@ The tool is named `process`.
 process start "pnpm dev" name="backend-dev"
 process start "pnpm test --watch" name="tests"
 process start "pnpm dev" name="backend-dev" cwd="/path/to/project"
+process ensure "pnpm dev" name="backend-dev"
+process ensure "pnpm dev" name="backend-dev" cwd="/path/to/project"
 process restart "pnpm dev" name="backend-dev"
 process restart "pnpm dev" name="backend-dev" force=true
 process list
@@ -184,13 +187,16 @@ process clear
 
 ### Field rules
 
-- `start`/`restart` require `command` and `name`.
+- `start`/`ensure`/`restart` require `command` and `name`.
 - `output`, `logs`, and `kill` accept either `id` (exact process ID) or `name` (process name).
 - `kill` accepts `force=true` to send `SIGKILL` instead of `SIGTERM`.
-- `start` refuses if a process with the same name is already running.
+- `start` refuses if a live process with the same name is already running.
+- `ensure` reuses existing process when name+command+cwd match; returns conflict error otherwise.
 - `restart` safely kills the existing process (awaited) before starting a new one.
 - `restart` accepts `force=true` to send `SIGKILL` instead of `SIGTERM`.
-- `start`/`restart` accept `cwd` to override the working directory (defaults to session cwd).
+- `restart` waits for the old process to exit; if it does not exit within the
+  timeout, the replacement is not started. Use `force=true` or inspect logs.
+- `start`/`ensure`/`restart` accept `cwd` to override the working directory (defaults to session cwd).
 - `output`, `logs`, and `kill` return an error if both `id` and `name` are provided.
 
 ## Killing processes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haemmid/pi-processes",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Agent-facing background process manager for Pi and pi-web automation workflows.",
   "license": "MIT",
   "type": "module",

package/src/manager.ts

@@ -235,6 +235,76 @@ export class ProcessManager {
     return this.toProcessInfo(managed);
   }
 
+  /**
+   * Restart a process by name: kill existing (awaited), then start new.
+   *
+   * - Waits for existing process to exit (polls every 500ms, up to timeoutMs).
+   * - Returns null if existing process does not exit after timeout.
+   * - Returns null if a different live process with the same name appears.
+   * - Returns new ProcessInfo on success.
+   */
+  async restart(
+    name: string,
+    command: string,
+    cwd: string,
+    opts?: { force?: boolean; timeoutMs?: number },
+  ): Promise<ProcessInfo | null> {
+    const existing = this.resolve(name);
+    if (!existing.ok) {
+      return null;
+    }
+
+    // Kill existing process
+    const killResult = await this.kill(existing.info.id, {
+      signal: opts?.force ? "SIGKILL" : "SIGTERM",
+      timeoutMs: opts?.timeoutMs ?? 5000,
+    });
+
+    if (!killResult.ok) {
+      // Process did not exit — return null so caller can decide
+      return null;
+    }
+
+    // Verify no other live process with this name appeared
+    const liveMatch = Array.from(this.processes.values()).find(
+      (proc) => proc.name === name && LIVE_STATUSES.has(proc.status),
+    );
+    if (liveMatch) {
+      return null;
+    }
+
+    // Start new process
+    return this.start(name, command, cwd);
+  }
+
+  /**
+   * Ensure a process is running with the given name, command, and cwd.
+   *
+   * - If a live process with the same name + cwd exists → return it.
+   * - If a live process with the same name exists but different cwd/command →
+   *   return null (conflict).
+   * - If no live process with this name exists → start a new one.
+   * - Finished processes with the same name are ignored.
+   */
+  ensure(name: string, command: string, cwd: string): ProcessInfo | null {
+    // Find live process with this name
+    const liveMatch = Array.from(this.processes.values()).find(
+      (proc) => proc.name === name && LIVE_STATUSES.has(proc.status),
+    );
+
+    if (liveMatch) {
+      // Same name, same cwd → reuse
+      if (liveMatch.cwd === cwd && liveMatch.command === command) {
+        return this.toProcessInfo(liveMatch);
+      }
+      // Same name, different cwd/command → conflict
+      return null;
+    }
+
+    // No live match → start new
+    return this.start(name, command, cwd);
+  }
+
   list(): ProcessInfo[] {
     return Array.from(this.processes.values())
       .map((p) => this.toProcessInfo(p))

package/src/tools/actions/ensure.ts

@@ -0,0 +1,87 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+import { formatTimestamp, sanitizeLine } from "../../utils";
+import { buildNextCommands } from "./utils";
+
+interface EnsureParams {
+  name?: string;
+  command?: string;
+  cwd?: string;
+}
+
+export function executeEnsure(
+  params: EnsureParams,
+  manager: ProcessManager,
+  ctx: ExtensionContext,
+): ExecuteResult {
+  if (!params.name) {
+    return {
+      content: [{ type: "text", text: "Missing required parameter: name" }],
+      details: {
+        action: "ensure",
+        success: false,
+        message: "Missing required parameter: name",
+      },
+    };
+  }
+  if (!params.command) {
+    return {
+      content: [{ type: "text", text: "Missing required parameter: command" }],
+      details: {
+        action: "ensure",
+        success: false,
+        message: "Missing required parameter: command",
+      },
+    };
+  }
+
+  const proc = manager.ensure(
+    params.name,
+    params.command,
+    params.cwd ?? ctx.cwd,
+  );
+
+  if (proc === null) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `A process named "${params.name}" is already running with a different command or cwd. Use process kill first, or process restart to replace it.`,
+        },
+      ],
+      details: {
+        action: "ensure",
+        success: false,
+        message: `A process named "${params.name}" is already running with a different configuration.`,
+      },
+    };
+  }
+
+  const startedAt = formatTimestamp(proc.startTime);
+
+  // Check if this was an existing process or newly started
+  const isNew = proc.pid > 0;
+  const message = isNew
+    ? [
+        `Started "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})`,
+        `Started at: ${startedAt}`,
+        `Logs: ${proc.stdoutFile}`,
+        buildNextCommands(proc.name),
+      ].join("\n")
+    : [
+        `Already running "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})`,
+        `Reusing existing managed process.`,
+        buildNextCommands(proc.name),
+      ].join("\n");
+
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action: "ensure",
+      success: true,
+      message,
+      process: proc,
+    },
+  };
+}

package/src/tools/actions/index.ts

@@ -2,6 +2,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ExecuteResult } from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { executeClear } from "./clear";
+import { executeEnsure } from "./ensure";
 import { executeKill } from "./kill";
 import { executeList } from "./list";
 import { executeLogs } from "./logs";
@@ -26,6 +27,8 @@ export async function executeAction(
   switch (params.action) {
     case "start":
       return executeStart(params, manager, ctx);
+    case "ensure":
+      return executeEnsure(params, manager, ctx);
     case "restart":
       return executeRestart(params, manager, ctx);
     case "list":

package/src/tools/actions/restart.ts

@@ -2,7 +2,6 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ExecuteResult } from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { formatTimestamp, sanitizeLine } from "../../utils";
-import { executeKill } from "./kill";
 import { buildNextCommands } from "./utils";
 
 interface RestartParams {
@@ -56,46 +55,27 @@ export async function executeRestart(
     };
   }
 
-  // Kill existing process (awaited, safe)
-  const killResult = await executeKill(
-    { id: existing.info.id, force: params.force },
-    manager,
-  );
-  if (!killResult.details.success) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Failed to kill existing process: ${killResult.details.message}`,
-        },
-      ],
-      details: {
-        action: "restart",
-        success: false,
-        message: `Failed to kill existing process: ${killResult.details.message}`,
-      },
-    };
-  }
-
-  // Start new process
-  const proc = manager.start(
+  // Restart via manager (atomic: kill → await exit → start)
+  const proc = await manager.restart(
     params.name,
     params.command,
     params.cwd ?? ctx.cwd,
+    { force: params.force },
   );
 
   if (proc === null) {
+    const signal = params.force ? "SIGKILL" : "SIGTERM";
     return {
       content: [
         {
           type: "text",
-          text: `A process named "${params.name}" is already running. Use process kill first.`,
+          text: `Could not restart "${sanitizeLine(params.name)}": previous process did not exit after ${signal}. Use restart force=true or inspect logs.`,
         },
       ],
       details: {
         action: "restart",
         success: false,
-        message: `A process named "${params.name}" is already running.`,
+        message: `Previous process did not exit after ${signal}.`,
       },
     };
   }

package/src/tools/actions/utils.ts

@@ -62,17 +62,22 @@ export function resolveSelector(
     const choices = (resolved.matches ?? [])
       .map((match) => `${match.id} ("${sanitizeLine(match.name)}")`)
       .join(", ");
+    const ids = (resolved.matches ?? []).map((m) => m.id);
+    const suggestion =
+      ids.length === 2
+        ? `Use id="${ids[0]}" or id="${ids[1]}", or inspect process list.`
+        : `Use an exact process ID instead. Matches: ${choices}`;
     return {
       content: [
         {
           type: "text",
-          text: `Process name is ambiguous: "${query}". Use an exact process ID instead. Matches: ${choices}`,
+          text: `Multiple processes named "${query}" found. ${suggestion}`,
         },
       ],
       details: {
         action: "output",
         success: false,
-        message: `Process name is ambiguous: "${query}". Matches: ${choices}`,
+        message: `Multiple processes named "${query}" found. Matches: ${choices}`,
       },
     };
   }

package/src/tools/index.ts

@@ -8,6 +8,7 @@ const ProcessesParams = Type.Object({
   action: Type.Union(
     [
       Type.Literal("start"),
+      Type.Literal("ensure"),
       Type.Literal("list"),
       Type.Literal("output"),
       Type.Literal("logs"),
@@ -17,7 +18,7 @@ const ProcessesParams = Type.Object({
     ],
     {
       description:
-        "Action: start (run command), list (show all), output (get recent output), logs (get log file paths), kill (terminate or force-kill), clear (remove finished), restart (kill existing and start new)",
+        "Action: start (run command), ensure (idempotent start), list (show all), output (get recent output), logs (get log file paths), kill (terminate or force-kill), clear (remove finished), restart (kill existing and start new)",
     },
   ),
   command: Type.Optional(
@@ -55,8 +56,9 @@ export function setupProcessesTools(pi: ExtensionAPI, manager: ProcessManager) {
     label: "Process",
     description: `Manage background processes.
 
-Actions: start, list, output, logs, kill, clear, restart.
-- start/restart require 'name' and 'command' — restart kills existing process first
+Actions: start, ensure, list, output, logs, kill, clear, restart.
+- start/restart/ensure require 'name' and 'command'
+- ensure is an idempotent start: reuses existing process if name+command+cwd match
 - output/logs/kill accept either 'id' (exact process ID) or 'name' (process name)
 - kill supports optional 'force=true' for SIGKILL
 - restart is preferred over start+kill: it safely awaits kill before starting new process