commandmate 0.19.0 → 0.20.0

package/dist/cli/docs/agent-operations.js

@@ -46,8 +46,11 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   Send a message to an agent (async). Starts session automatically if not running.
 
   Options:
-    --agent <id>           Agent type: claude (default), codex, gemini, vibe-local, opencode, copilot, antigravity
-    --instance <id>        Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2). See "Multi-Session" below.
+    --instance <id>        Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2, or codex
+                           for the codex primary instance). The recommended way to name a
+                           target: send / wait / respond / capture / auto-yes all take it.
+    --agent <id>           Ad-hoc CLI tool for an instance the roster does not know:
+                           claude (default), codex, gemini, vibe-local, opencode, copilot, antigravity
     --register             Register the --instance session into the agent-instance roster
     --auto-yes             Enable auto-yes before sending
     --duration <d>         Auto-yes duration: 1h, 3h, 8h (default: 1h)
@@ -58,6 +61,13 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
     WT=$(commandmate ls --id anvil- --quiet)   # disambiguate by repo (id prefix)
     commandmate send "$WT" "Implement this"
 
+  Targeting a non-default agent (Issue #1638): pass --instance, not --agent. Only
+  --instance is accepted by every command -- 'wait --agent' does not exist -- so a
+  workflow that names the agent on 'send' and nothing on 'wait' waits on the wrong
+  session in silence.
+    commandmate send "$WT" "Implement this" --instance codex
+    commandmate wait "$WT" --instance codex
+
 ### commandmate wait <worktree-id...>
   Block until agent completes or prompt is detected.
 
@@ -65,6 +75,7 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
     --timeout <seconds>        Maximum wait time
     --on-prompt <mode>         agent (default) or human
     --stall-timeout <seconds>  Max time without output change
+    --instance <id>            Agent instance to wait on. There is no --agent here.
     --verify                   After completion, run every verification gate
     --require-work             After completion, run only the work-evidence gate
 
@@ -148,6 +159,7 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   commandmate respond <id> "yes"          # Yes/No
   commandmate respond <id> "2"            # Multiple choice (number)
   commandmate respond <id> "custom text"  # Free text
+  commandmate respond <id> "yes" --instance codex-2   # Specific instance
 
   Exit codes:
     0  - Response sent
@@ -156,9 +168,9 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
 ### commandmate capture <worktree-id>
   Get current terminal output.
 
-  commandmate capture <id>                # Plain text
-  commandmate capture <id> --json         # JSON with status info
-  commandmate capture <id> --agent codex  # Specific agent
+  commandmate capture <id>                   # Plain text
+  commandmate capture <id> --json            # JSON with status info
+  commandmate capture <id> --instance codex  # Specific instance
 
 ### commandmate auto-yes <worktree-id>
   Control auto-yes (automatic prompt response).
@@ -167,6 +179,7 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   commandmate auto-yes <id> --enable --duration 3h      # With duration
   commandmate auto-yes <id> --enable --stop-pattern "error"
   commandmate auto-yes <id> --disable                   # Disable
+  commandmate auto-yes <id> --enable --instance codex-2 # Scoped to one instance
 
 ### commandmate instances <worktree-id> [action] [args]
   Discover and manage a worktree's agent-instance roster (1 agent, multiple sessions).
@@ -228,6 +241,17 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   --instance is accepted by send / wait / respond / capture / auto-yes.
   send --instance auto-starts the session if it is not already running.
 
+  --instance alone is the recommended way to name a target (Issue #1638). It is
+  the only flag all five commands share: --agent is rejected by 'wait'. A
+  rostered instance already carries its CLI tool (Issue #1629), and an instance
+  id that is itself a tool id resolves to that tool's primary instance even
+  without a roster entry, so '--instance codex' needs no --agent.
+
+  --agent remains accepted by send / respond / capture / auto-yes as the
+  supplement for ad-hoc instances the roster does not know -- notably
+  '--register', which cannot infer the tool from an id like codex-3. Passing an
+  --agent that contradicts the roster is an error (exit 2), not an override.
+
   The roster (visible in the browser UI's Agent panel) is the list of known
   instances with aliases and display order. Ad-hoc sessions started via
   'send --instance' do NOT appear in the roster unless registered:
@@ -240,9 +264,9 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   to that specific session, independent of other instances of the same agent.
 
   commandmate instances <id>                        # discover valid --instance values
-  commandmate send <id> "task" --agent codex --instance codex-2 --auto-yes
+  commandmate send <id> "task" --instance codex-2 --auto-yes
   commandmate wait <id> --instance codex-2 --timeout 600
-  commandmate capture <id> --agent codex --instance codex-2
+  commandmate capture <id> --instance codex-2
 
 ## All Exit Codes
 
@@ -318,12 +342,18 @@ Copy and adapt these patterns for your use case.
   WT2=$(commandmate ls --branch feature/102 --quiet)
 
   commandmate send "$WT1" "Implement #101" --auto-yes
-  commandmate send "$WT2" "Implement #102" --auto-yes --agent codex
+  commandmate send "$WT2" "Implement #102" --auto-yes --instance codex
 
-  commandmate wait "$WT1" "$WT2" --timeout 1800
+  # One --instance covers every worktree id in the call, so worktrees on
+  # different instances need one wait each. Both agents keep running while the
+  # first wait blocks, so this costs no wall clock over a combined wait.
+  # A bare 'wait "$WT2"' would watch WT2's DEFAULT agent, not the codex session:
+  # 'wait' has no --agent to correct that with.
+  commandmate wait "$WT1" --timeout 1800
+  commandmate wait "$WT2" --instance codex --timeout 1800
 
   commandmate capture "$WT1" --json
-  commandmate capture "$WT2" --json
+  commandmate capture "$WT2" --instance codex --json
 
 ## 5. Check status before sending
 
@@ -362,13 +392,16 @@ Copy and adapt these patterns for your use case.
   # Discover the roster before picking an --instance value
   commandmate instances "$WT"
 
-  # Register a second Codex instance, then send/wait/capture scoped to it
+  # Register a second Codex instance, then send/wait/capture scoped to it.
+  # Once it is in the roster, --instance alone carries the CLI tool.
   commandmate instances "$WT" add --agent codex --alias "Review"
-  commandmate send "$WT" "Review the diff" --agent codex --instance codex-2 --auto-yes
+  commandmate send "$WT" "Review the diff" --instance codex-2 --auto-yes
   commandmate wait "$WT" --instance codex-2 --timeout 600
-  commandmate capture "$WT" --agent codex --instance codex-2 --json
+  commandmate capture "$WT" --instance codex-2 --json
 
-  # Ad-hoc instance without pre-registering (still runs; register to show in UI)
+  # Ad-hoc instance without pre-registering (still runs; register to show in UI).
+  # --agent is required here: codex-3 is not in the roster yet, so nothing else
+  # says which CLI tool to start.
   commandmate send "$WT" "Quick check" --agent codex --instance codex-3 --register
 
   # Clean up when done

package/dist/cli/utils/api-client.d.ts

@@ -44,9 +44,12 @@ export interface ApiErrorResult {
  *
  * @param error - Error object or unknown
  * @param status - HTTP status code if available
+ * @param payload - Parsed error body, when the response carried one (Issue #1637).
+ *   Used for 5xx only: the 4xx messages below are already specific, and are
+ *   pinned by tests as the CLI's own wording.
  * @returns User-friendly error message and exit code
  */
-export declare function handleApiError(error: unknown, status?: number): ApiErrorResult;
+export declare function handleApiError(error: unknown, status?: number, payload?: ApiErrorPayload): ApiErrorResult;
 /**
  * API Client for CLI HTTP communication.
  * Uses Node.js built-in fetch. Handles auth headers and error mapping.

package/dist/cli/utils/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,4CAA4C;AAC5C,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAK3C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAaD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CASjF;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc,CAmE9E;AAeD;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAC,CAAS;gBAEX,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAa1D,OAAO,CAAC,UAAU;IAUlB;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAqBtC;;;OAGG;IACG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAyBvD;;;;OAIG;IACG,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;CAuBzD;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACxD,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AA0BD;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAGf,QAAQ,EAAE,MAAM;aAChB,UAAU,CAAC,EAAE,MAAM;IACnC,gEAAgE;aAChD,OAAO,CAAC,EAAE,eAAe;gBAJzC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,YAAA;IACnC,gEAAgE;IAChD,OAAO,CAAC,EAAE,eAAe,YAAA;IAM3C,uEAAuE;IACvE,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;CACF;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EACvC,OAAO,EAAE,MAAM,GACd,CAAC,CAiBH;AAOD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CASvF;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CASxE"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,4CAA4C;AAC5C,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAK3C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAaD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CASjF;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AA0BD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAyEhB;AAeD;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAC,CAAS;gBAEX,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAa1D,OAAO,CAAC,UAAU;IAUlB;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAuBtC;;;OAGG;IACG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IA2BvD;;;;OAIG;IACG,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;CAyBzD;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACxD,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AA0BD;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAGf,QAAQ,EAAE,MAAM;aAChB,UAAU,CAAC,EAAE,MAAM;IACnC,gEAAgE;aAChD,OAAO,CAAC,EAAE,eAAe;gBAJzC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,YAAA;IACnC,gEAAgE;IAChD,OAAO,CAAC,EAAE,eAAe,YAAA;IAM3C,uEAAuE;IACvE,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;CACF;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EACvC,OAAO,EAAE,MAAM,GACd,CAAC,CAiBH;AAOD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CASvF;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CASxE"}

package/dist/cli/utils/api-client.js

@@ -63,15 +63,41 @@ function resolveAuthToken(options) {
     }
     return process.env.CM_AUTH_TOKEN;
 }
+/**
+ * The server's own explanation for a failure, when it sent one worth showing.
+ *
+ * Issue #1637: every 5xx used to be flattened into `Server error. Check server
+ * logs for details.`, which is only useful to someone who has the server logs.
+ * A cold-start `send` failed with an initialization timeout and told the
+ * operator nothing but "go read the logs" — four orchestration runs in a row
+ * then misdiagnosed it as a session-creation race and worked around it by
+ * re-sending. Every route in this codebase already answers `{ error }`, so the
+ * cause was always in the response body; nothing read it.
+ *
+ * Trimmed and length-capped because it is printed to a terminal, and an
+ * unbounded server string is not something a CLI should paste verbatim.
+ */
+const MAX_SERVER_ERROR_DETAIL = 2000;
+function serverErrorDetail(payload) {
+    const detail = typeof payload?.error === 'string' ? payload.error.trim() : '';
+    if (detail === '')
+        return undefined;
+    return detail.length > MAX_SERVER_ERROR_DETAIL
+        ? `${detail.slice(0, MAX_SERVER_ERROR_DETAIL)}…`
+        : detail;
+}
 /**
  * Classify API errors into user-friendly messages and exit codes.
  * [IA3-09] Covers: ECONNREFUSED, 400, 401/403, 404, 429, 500, timeout
  *
  * @param error - Error object or unknown
  * @param status - HTTP status code if available
+ * @param payload - Parsed error body, when the response carried one (Issue #1637).
+ *   Used for 5xx only: the 4xx messages below are already specific, and are
+ *   pinned by tests as the CLI's own wording.
  * @returns User-friendly error message and exit code
  */
-function handleApiError(error, status) {
+function handleApiError(error, status, payload) {
     // HTTP status-based errors
     if (status !== undefined) {
         switch (status) {
@@ -99,8 +125,14 @@ function handleApiError(error, status) {
             case 500:
             default:
                 if (status >= 500) {
+                    // Issue #1637: pass the server's own reason through. The prefix is
+                    // kept so "this came from the server, not from the CLI" survives, and
+                    // so does the log pointer when the body said nothing.
+                    const detail = serverErrorDetail(payload);
                     return {
-                        message: 'Server error. Check server logs for details.',
+                        message: detail
+                            ? `Server error: ${detail}`
+                            : 'Server error. Check server logs for details.',
                         exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
                     };
                 }
@@ -186,8 +218,10 @@ class ApiClient {
                 headers: this.getHeaders(),
             });
             if (!response.ok) {
-                const errResult = handleApiError(null, response.status);
+                // Issue #1637: read the body first — handleApiError needs it to surface
+                // the server's reason for a 5xx instead of "check the logs".
                 const payload = await readErrorPayload(response);
+                const errResult = handleApiError(null, response.status, payload);
                 throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
             }
             return (await response.json());
@@ -211,8 +245,10 @@ class ApiClient {
                 body: body !== undefined ? JSON.stringify(body) : undefined,
             });
             if (!response.ok) {
-                const errResult = handleApiError(null, response.status);
+                // Issue #1637: read the body first — handleApiError needs it to surface
+                // the server's reason for a 5xx instead of "check the logs".
                 const payload = await readErrorPayload(response);
+                const errResult = handleApiError(null, response.status, payload);
                 throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
             }
             // Handle 204 No Content
@@ -241,8 +277,10 @@ class ApiClient {
                 body: body !== undefined ? JSON.stringify(body) : undefined,
             });
             if (!response.ok) {
-                const errResult = handleApiError(null, response.status);
+                // Issue #1637: read the body first — handleApiError needs it to surface
+                // the server's reason for a 5xx instead of "check the logs".
                 const payload = await readErrorPayload(response);
+                const errResult = handleApiError(null, response.status, payload);
                 throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
             }
             const text = await response.text();

package/dist/cli/utils/npm-runner.d.ts

@@ -16,6 +16,8 @@
  */
 /** Timeout for `npm view` (longer than preflight's 5s: this is a network round trip) */
 export declare const NPM_VIEW_TIMEOUT_MS = 10000;
+/** Timeout for `npm root -g` (a local path lookup, so preflight's 5s is plenty) */
+export declare const NPM_ROOT_TIMEOUT_MS = 5000;
 /**
  * Result of a registry version query
  */
@@ -55,4 +57,26 @@ export declare function viewLatestVersion(packageName: string): NpmViewResult;
  * @returns Success, or a classified failure (EACCES flagged separately)
  */
 export declare function installGlobalLatest(packageName: string): NpmInstallResult;
+/**
+ * A package present in the npm global root (`npm root -g`)
+ */
+export interface GlobalInstallation {
+    /** Absolute path of the installed package directory */
+    path: string;
+    /** Version read from its package.json; undefined when that cannot be read */
+    version?: string;
+}
+/**
+ * Locate a globally installed (`npm install -g`) package.
+ *
+ * Issue #1633: an npx self-update refreshes only the npx cache, so a global install left on the
+ * machine keeps shadowing `commandmate` on PATH at whatever version it was — a divergence that
+ * went unnoticed for months and surfaced as #1632. Callers only *warn* about what this reports,
+ * so every failure mode (npm missing, `npm root -g` failing on permissions, an unreadable
+ * package.json) degrades to "nothing to report" instead of propagating.
+ *
+ * @param packageName - Package name (e.g. `commandmate`)
+ * @returns The installation, or null when npm could not be asked or the package is not there
+ */
+export declare function findGlobalInstallation(packageName: string): GlobalInstallation | null;
 //# sourceMappingURL=npm-runner.d.ts.map

package/dist/cli/utils/npm-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"npm-runner.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/npm-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CA+BpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAwCzE"}
+{"version":3,"file":"npm-runner.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/npm-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CA+BpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAwCzE;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAsBrF"}

package/dist/cli/utils/npm-runner.js

@@ -16,12 +16,17 @@
  * @module npm-runner
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NPM_VIEW_TIMEOUT_MS = void 0;
+exports.NPM_ROOT_TIMEOUT_MS = exports.NPM_VIEW_TIMEOUT_MS = void 0;
 exports.viewLatestVersion = viewLatestVersion;
 exports.installGlobalLatest = installGlobalLatest;
+exports.findGlobalInstallation = findGlobalInstallation;
 const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
 /** Timeout for `npm view` (longer than preflight's 5s: this is a network round trip) */
 exports.NPM_VIEW_TIMEOUT_MS = 10_000;
+/** Timeout for `npm root -g` (a local path lookup, so preflight's 5s is plenty) */
+exports.NPM_ROOT_TIMEOUT_MS = 5_000;
 /**
  * Query the npm registry for the latest published version of a package.
  *
@@ -101,6 +106,51 @@ function installGlobalLatest(packageName) {
     }
     return { success: true, permissionDenied: false };
 }
+/**
+ * Locate a globally installed (`npm install -g`) package.
+ *
+ * Issue #1633: an npx self-update refreshes only the npx cache, so a global install left on the
+ * machine keeps shadowing `commandmate` on PATH at whatever version it was — a divergence that
+ * went unnoticed for months and surfaced as #1632. Callers only *warn* about what this reports,
+ * so every failure mode (npm missing, `npm root -g` failing on permissions, an unreadable
+ * package.json) degrades to "nothing to report" instead of propagating.
+ *
+ * @param packageName - Package name (e.g. `commandmate`)
+ * @returns The installation, or null when npm could not be asked or the package is not there
+ */
+function findGlobalInstallation(packageName) {
+    const result = (0, child_process_1.spawnSync)('npm', ['root', '-g'], {
+        encoding: 'utf-8',
+        timeout: exports.NPM_ROOT_TIMEOUT_MS,
+    });
+    // Covers ENOENT (no npm), a timeout, and a non-zero exit alike: nothing to report.
+    if (result.error || result.status !== 0) {
+        return null;
+    }
+    const root = readStream(result.stdout);
+    if (!root) {
+        return null;
+    }
+    const packagePath = (0, path_1.join)(root, packageName);
+    if (!(0, fs_1.existsSync)(packagePath)) {
+        return null;
+    }
+    return { path: packagePath, version: readInstalledVersion(packagePath) };
+}
+/**
+ * Best-effort version read from an installed package's package.json.
+ * The install itself is what matters, so an unreadable manifest still reports the install.
+ */
+function readInstalledVersion(packagePath) {
+    try {
+        const raw = (0, fs_1.readFileSync)((0, path_1.join)(packagePath, 'package.json'), 'utf-8');
+        const version = JSON.parse(raw).version;
+        return typeof version === 'string' && version.length > 0 ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Detect an npm global permission error.
  */

package/dist/cli/utils/pid-manager.d.ts

@@ -4,6 +4,8 @@
  * Issue #136: Phase 2 - Task 2.4 - Added factory functions for Issue number support
  * Issue #1354/#1355/#1358: the file now records the daemon's version, effective settings, and
  *   a process-identity signature, not just the PID. See DaemonState.
+ * Issue #1632: the file is written in a hybrid format (bare PID on line 1, JSON on line 2) so
+ *   that CLIs predating #1354 can still recover the PID from it. See formatState().
  * SF-1: SRP - Separated from daemon.ts for single responsibility
  * MF-SEC-2: TOCTOU protection with O_EXCL atomic writes
  */
@@ -51,8 +53,15 @@ export declare class PidManager {
     /**
      * Read the daemon state from file.
      *
-     * Tolerates the legacy format (a bare integer PID) by returning `{ pid }`, so a state file
-     * written by an older running daemon is still understood after a CLI upgrade (Issue #1354).
+     * Understands all three formats this file has ever had (Issue #1632):
+     * - hybrid (current): bare PID on line 1, JSON state on line 2
+     * - JSON only (#1354 .. #1632): the full state as one JSON object
+     * - bare integer (pre-#1354): just the PID, returned as `{ pid }`
+     *
+     * Reading the JSON of the hybrid format is not optional: falling back to the line-1 PID
+     * would silently drop `version`, disabling the CLI↔server version mismatch warning added
+     * by #1354, and drop `port`/`protocol`/`bind`, sending status back to re-deriving the URL
+     * from a possibly-diverged .env (#1355).
      *
      * @returns The daemon state, or null when the file is missing or invalid
      */
@@ -65,6 +74,7 @@ export declare class PidManager {
     /**
      * Write the daemon state to file atomically
      * MF-SEC-2: Uses O_EXCL to prevent TOCTOU race conditions
+     * Issue #1632: written in the hybrid format (see formatState)
      *
      * @returns true if successful, false if file already exists
      * @throws Error for other filesystem errors

package/dist/cli/utils/pid-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pid-manager.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/pid-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,OAAO,EAAuB,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAElF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,wEAAwE;IACxE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,UAAU;IAOnB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAPhC;;;;OAIG;gBAEgB,WAAW,EAAE,MAAM,EACnB,aAAa,GAAE,sBAA4C;IAG9E;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;;;;;;OAOG;IACH,SAAS,IAAI,WAAW,GAAG,IAAI;IA2B/B;;;OAGG;IACH,OAAO,IAAI,MAAM,GAAG,IAAI;IAIxB;;;;;;OAMG;IACH,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAwBvC;;;;;;OAMG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIxC;;OAEG;IACH,SAAS,IAAI,IAAI;IAUjB;;;;;;;;;;;OAWG;IACH,gBAAgB,IAAI,OAAO;CAoC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,CAI7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAEjE"}
+{"version":3,"file":"pid-manager.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/pid-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,OAAO,EAAuB,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAElF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,wEAAwE;IACxE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAuED;;GAEG;AACH,qBAAa,UAAU;IAOnB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAPhC;;;;OAIG;gBAEgB,WAAW,EAAE,MAAM,EACnB,aAAa,GAAE,sBAA4C;IAG9E;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;;;;;;;;;;;;;OAcG;IACH,SAAS,IAAI,WAAW,GAAG,IAAI;IAgB/B;;;OAGG;IACH,OAAO,IAAI,MAAM,GAAG,IAAI;IAIxB;;;;;;;OAOG;IACH,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAwBvC;;;;;;OAMG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIxC;;OAEG;IACH,SAAS,IAAI,IAAI;IAUjB;;;;;;;;;;;OAWG;IACH,gBAAgB,IAAI,OAAO;CAoC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,CAI7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAEjE"}

package/dist/cli/utils/pid-manager.js

@@ -5,6 +5,8 @@
  * Issue #136: Phase 2 - Task 2.4 - Added factory functions for Issue number support
  * Issue #1354/#1355/#1358: the file now records the daemon's version, effective settings, and
  *   a process-identity signature, not just the PID. See DaemonState.
+ * Issue #1632: the file is written in a hybrid format (bare PID on line 1, JSON on line 2) so
+ *   that CLIs predating #1354 can still recover the PID from it. See formatState().
  * SF-1: SRP - Separated from daemon.ts for single responsibility
  * MF-SEC-2: TOCTOU protection with O_EXCL atomic writes
  */
@@ -15,6 +17,68 @@ exports.createIssuePidManager = createIssuePidManager;
 const fs_1 = require("fs");
 const resource_resolvers_1 = require("./resource-resolvers");
 const process_inspector_1 = require("./process-inspector");
+/**
+ * Serialize the state in the hybrid format (Issue #1632).
+ *
+ * ```
+ * 84890
+ * {"pid":84890,"version":"0.18.0","port":3000,...}
+ * ```
+ *
+ * The path of this file has never changed, so a CLI predating #1354 that is still on PATH
+ * (a stale `npm install -g`) reads whatever the current daemon wrote. Those CLIs parse it as
+ * `parseInt(readFileSync(...).trim(), 10)`, which returned NaN for a leading `{` and made them
+ * report "Stopped (no PID file)" for a perfectly healthy server. `parseInt` stops at the first
+ * non-digit, so putting the bare PID on line 1 restores that forward compatibility.
+ *
+ * The JSON is always exactly one line: JSON.stringify escapes control characters inside
+ * strings, so it can never emit a raw newline of its own.
+ */
+function formatState(state) {
+    return `${state.pid}\n${JSON.stringify(state)}\n`;
+}
+/**
+ * Parse the (already trimmed, non-empty) contents of a state file in any format it has had.
+ *
+ * @returns The daemon state, or null when nothing usable could be parsed
+ */
+function parseState(content) {
+    const firstBreak = content.indexOf('\n');
+    // .trim() also drops the \r of a CRLF file, which /^\d+$/ would otherwise reject.
+    const head = (firstBreak === -1 ? content : content.slice(0, firstBreak)).trim();
+    if (/^\d+$/.test(head)) {
+        const pid = parseInt(head, 10);
+        if (pid <= 0) {
+            return null;
+        }
+        const body = firstBreak === -1 ? '' : content.slice(firstBreak + 1).trim();
+        if (body.length === 0) {
+            // Pre-#1354 format: the file held only the PID.
+            return { pid };
+        }
+        // Hybrid format (#1632): line 2 carries the full state. Line 1 is the fallback, so a
+        // truncated or corrupt JSON body still yields a usable PID instead of "no PID file".
+        return parseJsonState(body) ?? { pid };
+    }
+    // #1354..#1632 format: the whole file is the JSON state.
+    return parseJsonState(content);
+}
+/**
+ * Parse a JSON state object, rejecting anything without a usable PID.
+ */
+function parseJsonState(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed.pid !== 'number' || !Number.isInteger(parsed.pid) || parsed.pid <= 0) {
+        return null;
+    }
+    return parsed;
+}
 /**
  * PID file manager for daemon process tracking
  */
@@ -39,8 +103,15 @@ class PidManager {
     /**
      * Read the daemon state from file.
      *
-     * Tolerates the legacy format (a bare integer PID) by returning `{ pid }`, so a state file
-     * written by an older running daemon is still understood after a CLI upgrade (Issue #1354).
+     * Understands all three formats this file has ever had (Issue #1632):
+     * - hybrid (current): bare PID on line 1, JSON state on line 2
+     * - JSON only (#1354 .. #1632): the full state as one JSON object
+     * - bare integer (pre-#1354): just the PID, returned as `{ pid }`
+     *
+     * Reading the JSON of the hybrid format is not optional: falling back to the line-1 PID
+     * would silently drop `version`, disabling the CLI↔server version mismatch warning added
+     * by #1354, and drop `port`/`protocol`/`bind`, sending status back to re-deriving the URL
+     * from a possibly-diverged .env (#1355).
      *
      * @returns The daemon state, or null when the file is missing or invalid
      */
@@ -53,16 +124,7 @@ class PidManager {
             if (content.length === 0) {
                 return null;
             }
-            // Legacy format: the file held only the PID as a bare integer.
-            if (/^\d+$/.test(content)) {
-                const pid = parseInt(content, 10);
-                return pid > 0 ? { pid } : null;
-            }
-            const parsed = JSON.parse(content);
-            if (typeof parsed.pid !== 'number' || !Number.isInteger(parsed.pid) || parsed.pid <= 0) {
-                return null;
-            }
-            return parsed;
+            return parseState(content);
         }
         catch {
             return null;
@@ -78,6 +140,7 @@ class PidManager {
     /**
      * Write the daemon state to file atomically
      * MF-SEC-2: Uses O_EXCL to prevent TOCTOU race conditions
+     * Issue #1632: written in the hybrid format (see formatState)
      *
      * @returns true if successful, false if file already exists
      * @throws Error for other filesystem errors
@@ -87,7 +150,7 @@ class PidManager {
             // O_EXCL: Fail if file already exists (atomic check-and-create)
             const fd = (0, fs_1.openSync)(this.pidFilePath, fs_1.constants.O_WRONLY | fs_1.constants.O_CREAT | fs_1.constants.O_EXCL, 0o600);
             try {
-                (0, fs_1.writeSync)(fd, JSON.stringify(state));
+                (0, fs_1.writeSync)(fd, formatState(state));
                 return true;
             }
             finally {