commandmate 0.19.0 → 0.21.0

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 {

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

@@ -16,6 +16,15 @@ import { ApiClient } from './api-client';
 export declare const VERIFY_POLL_INTERVAL_MS = 5000;
 /** Built-in gate id; mirrors WORK_EVIDENCE_GATE_ID in lib/verification/gate-runner.ts. */
 export declare const WORK_EVIDENCE_GATE_ID = "work-evidence";
+/**
+ * Lines of a failing gate's log echoed to stderr before the rest becomes a
+ * count (#1683).
+ *
+ * log_tail is byte-capped only when stored (options.maxLogTailBytes, default
+ * 8KB but configurable up to 1MB), so echoing it whole lets one misconfigured
+ * gate flood the terminal and scroll the GATE verdict lines out of sight.
+ */
+export declare const MAX_PRINTED_LOG_TAIL_LINES = 40;
 export interface VerificationRequest {
     worktreeId: string;
     /** 'manual' for the verify command, 'wait' when chained after wait. */

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

@@ -1 +1 @@
-{"version":3,"file":"verify-runner.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/verify-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAEV,qBAAqB,EACrB,mBAAmB,EAGpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAAiC,MAAM,cAAc,CAAC;AAExE,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACnC,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,mBAAmB,CAAC;CAC3B;AAUD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAW1E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,CAOnF;AAqED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CAyD9B"}
+{"version":3,"file":"verify-runner.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/verify-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAEV,qBAAqB,EACrB,mBAAmB,EAGpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAAiC,MAAM,cAAc,CAAC;AAExE,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACnC,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,mBAAmB,CAAC;CAC3B;AAUD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAW1E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,CAOnF;AAsFD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CAyD9B"}

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

@@ -12,7 +12,7 @@
  * @module cli/utils/verify-runner
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WORK_EVIDENCE_GATE_ID = exports.VERIFY_POLL_INTERVAL_MS = void 0;
+exports.MAX_PRINTED_LOG_TAIL_LINES = exports.WORK_EVIDENCE_GATE_ID = exports.VERIFY_POLL_INTERVAL_MS = void 0;
 exports.exitCodeForRunStatus = exitCodeForRunStatus;
 exports.parseGateIds = parseGateIds;
 exports.runVerification = runVerification;
@@ -22,6 +22,15 @@ const api_client_1 = require("./api-client");
 exports.VERIFY_POLL_INTERVAL_MS = 5000;
 /** Built-in gate id; mirrors WORK_EVIDENCE_GATE_ID in lib/verification/gate-runner.ts. */
 exports.WORK_EVIDENCE_GATE_ID = 'work-evidence';
+/**
+ * Lines of a failing gate's log echoed to stderr before the rest becomes a
+ * count (#1683).
+ *
+ * log_tail is byte-capped only when stored (options.maxLogTailBytes, default
+ * 8KB but configurable up to 1MB), so echoing it whole lets one misconfigured
+ * gate flood the terminal and scroll the GATE verdict lines out of sight.
+ */
+exports.MAX_PRINTED_LOG_TAIL_LINES = 40;
 const GATE_LABELS = {
     passed: 'PASS',
     failed: 'FAIL',
@@ -86,6 +95,23 @@ function formatGateLine(gate) {
     const detail = formatDetail(gate);
     return detail ? `GATE ${gate.gateId} ${label} (${detail})` : `GATE ${gate.gateId} ${label}`;
 }
+/**
+ * Cap a failing gate's log for display, keeping the LAST lines: every producer
+ * puts its conclusion there — a failing suite ends with its summary, the scope
+ * gate ends with its violation list and guidance. The omission marker leads so
+ * the reader knows lines are missing before reading, and it names `verify show`
+ * because that is where the full stored log lives.
+ */
+function formatLogTailForDisplay(gate) {
+    const lines = (gate.logTail ?? '').replace(/\n+$/, '').split('\n');
+    if (lines.length <= exports.MAX_PRINTED_LOG_TAIL_LINES)
+        return lines.join('\n');
+    const omitted = lines.length - exports.MAX_PRINTED_LOG_TAIL_LINES;
+    return [
+        `... (+${omitted} more lines; run \`commandmate verify show ${gate.runId}\` for the full log)`,
+        ...lines.slice(-exports.MAX_PRINTED_LOG_TAIL_LINES),
+    ].join('\n');
+}
 /**
  * Print each gate exactly once, when it reaches a terminal status.
  * @param reported - Gate row ids already printed; mutated in place.
@@ -99,7 +125,7 @@ function reportGates(gates, reported) {
         // A failing gate without its log forces the caller back to the API to learn
         // anything actionable, which defeats the point of a CLI verdict.
         if (gate.status !== 'passed' && gate.logTail) {
-            console.error(gate.logTail.replace(/\n+$/, ''));
+            console.error(formatLogTailForDisplay(gate));
         }
     }
 }

package/dist/config/history-display-config.d.ts

@@ -0,0 +1,61 @@
+/**
+ * History Display Configuration (Issue #701)
+ *
+ * Single Source of Truth for the history display limit options used by:
+ * - GET /api/worktrees/:id/messages (upper-bound validation)
+ * - HistoryPane selector UI (selectable options)
+ * - WorktreeDetailRefactored state (persisted to localStorage)
+ *
+ * Design decisions:
+ * - MAX_MESSAGES_LIMIT is derived from HISTORY_DISPLAY_LIMIT_OPTIONS (no duplication).
+ * - DEFAULT_MESSAGES_LIMIT (50) matches the historical default before this issue.
+ * - Storage key uses the `commandmate:` namespace, matching other keys
+ *   (e.g. `commandmate:showArchived`).
+ */
+/**
+ * Selectable history display limit options (ascending).
+ * The first entry is the historical default; the last entry is the maximum.
+ *
+ * Issue #1123: the 250 ceiling was a performance mitigation for the previously
+ * flat-rendered HistoryPane. Now that the list is virtualized (render cost is
+ * O(visible rows), not O(total)), the ceiling is relaxed to 1000. The API still
+ * bounds the *fetch* by the maximum option (data volume); server-side paging is
+ * tracked separately.
+ */
+export declare const HISTORY_DISPLAY_LIMIT_OPTIONS: readonly [50, 100, 150, 200, 250, 500, 1000];
+/**
+ * Union type representing any selectable history display limit.
+ */
+export type HistoryDisplayLimit = (typeof HISTORY_DISPLAY_LIMIT_OPTIONS)[number];
+/**
+ * Upper bound enforced by the API, derived from the maximum option.
+ *
+ * Typed as `HistoryDisplayLimit` (not a brittle `as 250` literal) so that
+ * extending `HISTORY_DISPLAY_LIMIT_OPTIONS` does not require touching this line.
+ */
+export declare const MAX_MESSAGES_LIMIT: HistoryDisplayLimit;
+/**
+ * Default history display limit (used when no localStorage value is present).
+ */
+export declare const DEFAULT_MESSAGES_LIMIT: HistoryDisplayLimit;
+/**
+ * localStorage key used to persist the user-selected history display limit.
+ */
+export declare const HISTORY_DISPLAY_LIMIT_STORAGE_KEY = "commandmate:historyDisplayLimit";
+/**
+ * Type guard: returns true if `value` is one of the allowed limit options.
+ *
+ * Used when reading from localStorage (which may contain stale/corrupted data)
+ * to safely narrow `number` to `HistoryDisplayLimit`.
+ */
+export declare function isHistoryDisplayLimit(value: number): value is HistoryDisplayLimit;
+/**
+ * localStorage key used to persist the HistoryPane "User only" filter toggle
+ * (Issue #725).
+ *
+ * Value representation: `'true'` / `'false'` (string), matching the existing
+ * `commandmate:showArchived` convention. Any other value (including legacy
+ * `'1'`/`'0'` or missing) is treated as `false` (safe-off fallback).
+ */
+export declare const HISTORY_USER_ONLY_STORAGE_KEY = "commandmate:historyUserOnly";
+//# sourceMappingURL=history-display-config.d.ts.map

package/dist/config/history-display-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-display-config.d.ts","sourceRoot":"","sources":["../../src/config/history-display-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,8CAA+C,CAAC;AAE1F;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,mBAET,CAAC;AAEzB;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,mBAAwB,CAAC;AAE9D;;GAEG;AACH,eAAO,MAAM,iCAAiC,oCAAoC,CAAC;AAEnF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,mBAAmB,CAEjF;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,gCAAgC,CAAC"}

package/dist/config/history-display-config.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * History Display Configuration (Issue #701)
+ *
+ * Single Source of Truth for the history display limit options used by:
+ * - GET /api/worktrees/:id/messages (upper-bound validation)
+ * - HistoryPane selector UI (selectable options)
+ * - WorktreeDetailRefactored state (persisted to localStorage)
+ *
+ * Design decisions:
+ * - MAX_MESSAGES_LIMIT is derived from HISTORY_DISPLAY_LIMIT_OPTIONS (no duplication).
+ * - DEFAULT_MESSAGES_LIMIT (50) matches the historical default before this issue.
+ * - Storage key uses the `commandmate:` namespace, matching other keys
+ *   (e.g. `commandmate:showArchived`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HISTORY_USER_ONLY_STORAGE_KEY = exports.HISTORY_DISPLAY_LIMIT_STORAGE_KEY = exports.DEFAULT_MESSAGES_LIMIT = exports.MAX_MESSAGES_LIMIT = exports.HISTORY_DISPLAY_LIMIT_OPTIONS = void 0;
+exports.isHistoryDisplayLimit = isHistoryDisplayLimit;
+/**
+ * Selectable history display limit options (ascending).
+ * The first entry is the historical default; the last entry is the maximum.
+ *
+ * Issue #1123: the 250 ceiling was a performance mitigation for the previously
+ * flat-rendered HistoryPane. Now that the list is virtualized (render cost is
+ * O(visible rows), not O(total)), the ceiling is relaxed to 1000. The API still
+ * bounds the *fetch* by the maximum option (data volume); server-side paging is
+ * tracked separately.
+ */
+exports.HISTORY_DISPLAY_LIMIT_OPTIONS = [50, 100, 150, 200, 250, 500, 1000];
+/**
+ * Upper bound enforced by the API, derived from the maximum option.
+ *
+ * Typed as `HistoryDisplayLimit` (not a brittle `as 250` literal) so that
+ * extending `HISTORY_DISPLAY_LIMIT_OPTIONS` does not require touching this line.
+ */
+exports.MAX_MESSAGES_LIMIT = Math.max(...exports.HISTORY_DISPLAY_LIMIT_OPTIONS);
+/**
+ * Default history display limit (used when no localStorage value is present).
+ */
+exports.DEFAULT_MESSAGES_LIMIT = 50;
+/**
+ * localStorage key used to persist the user-selected history display limit.
+ */
+exports.HISTORY_DISPLAY_LIMIT_STORAGE_KEY = 'commandmate:historyDisplayLimit';
+/**
+ * Type guard: returns true if `value` is one of the allowed limit options.
+ *
+ * Used when reading from localStorage (which may contain stale/corrupted data)
+ * to safely narrow `number` to `HistoryDisplayLimit`.
+ */
+function isHistoryDisplayLimit(value) {
+    return exports.HISTORY_DISPLAY_LIMIT_OPTIONS.includes(value);
+}
+/**
+ * localStorage key used to persist the HistoryPane "User only" filter toggle
+ * (Issue #725).
+ *
+ * Value representation: `'true'` / `'false'` (string), matching the existing
+ * `commandmate:showArchived` convention. Any other value (including legacy
+ * `'1'`/`'0'` or missing) is treated as `false` (safe-off fallback).
+ */
+exports.HISTORY_USER_ONLY_STORAGE_KEY = 'commandmate:historyUserOnly';