commandmate 0.43.0 → 0.44.0

package/dist/cli/commands/respond.js

@@ -120,6 +120,240 @@ async function answerSolePendingDecision(client, worktreeId, body) {
         throw error;
     }
 }
+/** Reason `/prompt-response` gives when no dialog is on screen any more. */
+const PROMPT_NO_LONGER_ACTIVE = 'prompt_no_longer_active';
+/**
+ * Issue #3125: what `--plan-review` takes. Restated rather than imported from
+ * `src/lib` (the CLI build does not reach it); the server validates the same set.
+ */
+const PLAN_REVIEW_ACTIONS = ['comment', 'submit', 'approve', 'cancel'];
+/** Reasons the server gives for a plan review answer it refused before any key. */
+function isPlanReviewRefusal(reason) {
+    return reason.startsWith('plan_review_');
+}
+/** ` --instance <id>` as the caller spelled it, or nothing. */
+function instanceFlag(instance) {
+    return instance ? ` --instance ${instance}` : '';
+}
+/**
+ * `textFollowUp` from a `/prompt-response` success (Issue #3093), read
+ * defensively: an older server omits it, and the route's mirror type is not
+ * this command's to widen.
+ */
+function readTextFollowUp(result) {
+    const value = result?.textFollowUp;
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const { optionNumber, optionLabel } = value;
+    if (typeof optionNumber !== 'number' || typeof optionLabel !== 'string')
+        return null;
+    return { optionNumber, optionLabel };
+}
+/** Argument checks; returns whether --default was chosen. A mocked `process.exit` returns, so nothing here stops early. */
+function validateRespondArgs(worktreeId, answer, options) {
+    // [SEC4-04] Validate worktree ID
+    if (!(0, api_client_1.isValidWorktreeId)(worktreeId)) {
+        console.error('Error: Invalid worktree ID format.');
+        process.exit(types_1.ExitCode.CONFIG_ERROR);
+    }
+    // Validate agent if provided
+    if (options.agent && !(0, cli_tool_ids_1.isCliToolId)(options.agent)) {
+        console.error('Error: Invalid agent.');
+        process.exit(types_1.ExitCode.CONFIG_ERROR);
+    }
+    // Issue #868 / #2376: an instance id or a roster alias.
+    if (options.instance && !(0, instances_1.isInstanceSelector)(options.instance)) {
+        console.error(instances_1.INSTANCE_SELECTOR_ERROR);
+        process.exit(types_1.ExitCode.CONFIG_ERROR);
+    }
+    // Issue #1681: exactly one of <answer> / --default
+    const useDefault = options.default === true;
+    // Issue #3125: Command Code's plan review. `approve` / `cancel` take no text,
+    // `comment` needs it, and `submit` takes an optional comment to send first.
+    const planReview = options.planReview;
+    if (planReview !== undefined) {
+        if (!PLAN_REVIEW_ACTIONS.includes(planReview)) {
+            console.error(`Error: --plan-review must be one of: ${PLAN_REVIEW_ACTIONS.join(', ')}.`);
+            process.exit(types_1.ExitCode.CONFIG_ERROR);
+        }
+        if (useDefault) {
+            console.error('Error: --plan-review and --default are mutually exclusive.');
+            process.exit(types_1.ExitCode.CONFIG_ERROR);
+        }
+        if ((planReview === 'approve' || planReview === 'cancel') && answer !== undefined) {
+            console.error(`Error: --plan-review ${planReview} takes no <answer>.`);
+            process.exit(types_1.ExitCode.CONFIG_ERROR);
+        }
+        if (planReview === 'comment' && (answer === undefined || !answer.trim())) {
+            console.error('Error: --plan-review comment needs the comment text as <answer>.');
+            process.exit(types_1.ExitCode.CONFIG_ERROR);
+        }
+        return false;
+    }
+    if (useDefault && answer !== undefined) {
+        console.error('Error: <answer> and --default are mutually exclusive.');
+        process.exit(types_1.ExitCode.CONFIG_ERROR);
+    }
+    if (!useDefault && (answer === undefined || !answer.trim())) {
+        console.error('Error: Answer cannot be empty. Provide an answer or --default.');
+        process.exit(types_1.ExitCode.CONFIG_ERROR);
+    }
+    return useDefault;
+}
+/** The `/prompt-response` request body. */
+function buildPromptResponseBody(useDefault, answer, agent, instanceId, planReview) {
+    // [DR2-06] Use prompt-response API with cliTool (not cliToolId)
+    const body = useDefault ? { useDefault: true } : { answer };
+    // Issue #3125: Command Code's plan review action.
+    if (planReview !== undefined) {
+        body.planReviewAction = planReview;
+    }
+    if (agent) {
+        body.cliTool = agent;
+    }
+    // Issue #868: target a specific agent instance
+    if (instanceId) {
+        body.instanceId = instanceId;
+    }
+    return body;
+}
+/** Reports a `success: false` result and sets the exit code. */
+function reportFailedResponse(result, worktreeId, answer, useDefault, options) {
+    // [DR2-06] Check reason for failure
+    const reason = result.reason || 'unknown';
+    // Issue #1681 / #1726: these mean the server refused BEFORE sending,
+    // so the terminal is untouched — worth saying plainly, because the
+    // other reasons leave the answer's fate unknown. Issue #2486 adds
+    // `unsupported_dialog_layout`: a picker IS on screen but its layout
+    // could not be verified, and the server's message says what to do.
+    // Issue #3125 adds the `plan_review_*` refusals: the plan review overlay was
+    // read and the request did not fit its current focus, so nothing was typed.
+    const refusedBeforeSending = reason === 'unresolvable_answer' ||
+        reason === 'answer_out_of_range' ||
+        reason === 'unsupported_dialog_layout' ||
+        isPlanReviewRefusal(reason);
+    // Issue #1898: the verdict was addressed to the agent's own API and
+    // the POST did not land. Distinct from the two above — the answer was
+    // resolved and an attempt was made — and distinct from a keystroke,
+    // whose fate is never knowable.
+    if (reason === 'decision_not_delivered') {
+        console.error(`Error: The approval could not be delivered to the agent (reason: ${reason}). ` +
+            'The dialog is still open; answer it in the terminal.');
+        process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
+    }
+    if (refusedBeforeSending) {
+        console.error(`Error: Answer was not sent. Reason: ${reason}${result.message ? ` (${result.message})` : ''}`);
+        // Issue #2583: the operator who lands here typed WORDS at a dialog
+        // that only takes a choice — a claude / agy Bash approval refused as
+        // free text, or #2573's "No, tell … what to do differently" row. The
+        // server's sentence ends with "answer with the option number", and
+        // this is that command with the ids already filled in, so the next
+        // step is a paste rather than a trip to the docs while a dialog sits
+        // open. Printed only for the reason that means "this answer could not
+        // be mapped onto a choice", and only when the answer was not already
+        // a number (where the number itself is what was wrong).
+        if (reason === 'unresolvable_answer' && answer !== undefined && !/^\d+$/.test(answer.trim())) {
+            const target = options.instance ? ` --instance ${options.instance}` : '';
+            console.error(`Hint: answer with the option number — \`commandmate respond ${worktreeId} <number>${target}\` ` +
+                `(\`commandmate capture ${worktreeId}${target}\` prints the dialog and its numbers).`);
+        }
+    }
+    else {
+        console.error(`Warning: Response may not have been applied. Reason: ${reason}`);
+        // Issue #3093: the usual way here is the second half of a "No, tell
+        // … what to do differently" answer — the row closed the dialog and
+        // the agent is waiting for the reason in its input box, which
+        // `respond` (dialogs only) cannot reach and `send` can.
+        if (reason === PROMPT_NO_LONGER_ACTIVE && !useDefault && answer !== undefined && !/^\d+$/.test(answer.trim())) {
+            console.error('Hint: no dialog is open, so this text was not delivered. If you just chose an option that asks ' +
+                'for text (e.g. "No, tell … what to do differently"), the agent is waiting for it in its input box — ' +
+                `send it with \`commandmate send ${worktreeId} "<text>"${instanceFlag(options.instance)}\`.`);
+        }
+    }
+    // Issue #1726: an option number the agent's own payload does not offer
+    // is a bad argument, so it exits with the input-error code the rest of
+    // this command already uses for a malformed worktree id or agent.
+    process.exit(reason === 'answer_out_of_range' ? types_1.ExitCode.CONFIG_ERROR : types_1.ExitCode.UNEXPECTED_ERROR);
+}
+/**
+ * What was done on Command Code's plan review (Issue #3125), and the next step:
+ * a pinned comment is not delivered to the agent until the review is submitted.
+ */
+function printPlanReviewOutcome(result, worktreeId, options) {
+    const planReview = result.planReview;
+    if (!planReview)
+        return;
+    const target = instanceFlag(options.instance);
+    switch (planReview.action) {
+        case 'comment':
+            console.log(`Plan review: pinned comment "${planReview.comment ?? ''}".`);
+            console.error(`Next: send the review with \`commandmate respond ${worktreeId} --plan-review submit${target}\` ` +
+                `(ctrl+r), or approve with \`--plan-review approve\` (comments go along as notes).`);
+            break;
+        case 'submit':
+            console.log(planReview.comment
+                ? `Plan review: pinned comment "${planReview.comment}" and submitted the review (ctrl+r).`
+                : 'Plan review: submitted the review (ctrl+r).');
+            break;
+        case 'approve':
+            if (planReview.phase === 'approve-choice') {
+                console.log(`Plan review: confirmed the approval (${planReview.approveChoice === 'discard-comments' ? 'discarding' : 'with'} the pending comments).`);
+            }
+            else {
+                console.log('Plan review: approved the plan (ctrl+a).');
+                if (planReview.pendingCommentsBefore > 0) {
+                    console.error('Note: with pending comments Command Code may ask how to approve — confirm with ' +
+                        `\`commandmate respond ${worktreeId} --plan-review approve${target}\` again, or go back with \`--plan-review cancel\`.`);
+                }
+            }
+            break;
+        case 'cancel':
+            console.log(planReview.phase === 'approve-choice'
+                ? 'Plan review: went back from the approval choice (esc).'
+                : 'Plan review: cancelled the plan (esc).');
+            if (planReview.phase !== 'approve-choice' && planReview.pendingCommentsBefore > 0) {
+                console.error(`Note: ${planReview.pendingCommentsBefore} pending comment(s) were discarded with it.`);
+            }
+            break;
+    }
+}
+/** Audit trail of which option was actually selected. */
+function printResolvedAudit(result, answer) {
+    // Issue #1681: audit trail — print which option was actually selected.
+    const resolved = result?.resolved;
+    if (resolved) {
+        if (resolved.via === 'structured-decision') {
+            // Issue #1898: no key was sent. The verdict went to the agent's own
+            // API by decision id, which is the only way an opencode approval can
+            // be answered at all — worth saying, because "Response sent." on
+            // this path would read as "a 1 was typed into the pane".
+            console.log(`Answered approval ${resolved.decisionId ?? '(unknown id)'} with ` +
+                `option ${resolved.optionNumber}: ${resolved.optionLabel}`);
+        }
+        else if (resolved.via === 'structured-question') {
+            // Issue #2040: a question, answered over `POST /question/:id/reply`.
+            // What is printed is what reached the AGENT — the labels — rather
+            // than the number that was typed: `respond <id> 2` at a question is
+            // a position in the agent's own list, and an operator reconciling
+            // what they meant against what was sent needs the other end of that
+            // mapping. `freeText` prints the text for the same reason.
+            const chosen = resolved.optionLabels ?? [];
+            console.log(`Answered question ${resolved.decisionId ?? '(unknown id)'} with ` +
+                (chosen.length > 0
+                    ? chosen.map((label, index) => `${resolved.optionNumbers?.[index] ?? '?'}: ${label}`).join(', ')
+                    : `free text: ${(resolved.answers?.[0] ?? []).join(', ')}`));
+        }
+        else if (resolved.via === 'semantic') {
+            console.log(`Resolved "${answer}" to option ${resolved.optionNumber}: ${resolved.optionLabel}`);
+        }
+        else if (resolved.optionNumber !== undefined) {
+            console.log(`Selected default option ${resolved.optionNumber}: ${resolved.optionLabel}`);
+        }
+        else {
+            console.log(`Selected default answer: ${resolved.optionLabel}`);
+        }
+    }
+}
 function createRespondCommand() {
     const cmd = new commander_1.Command('respond');
     cmd
@@ -127,36 +361,14 @@ function createRespondCommand() {
         .argument('<worktree-id>', 'Worktree ID')
         .argument('[answer]', 'Response answer (yes, no, number, or free text)')
         .option('--default', "Select the prompt's default option (mutually exclusive with <answer>)")
+        .option('--plan-review <action>', 'Command Code plan review: comment | submit | approve | cancel ' +
+        '(text alone is a comment; submit takes an optional comment; approve/cancel take no <answer>)')
         .option('--instance <id>', `${agent_target_options_1.INSTANCE_OPTION_DESCRIPTION} ${instances_1.INSTANCE_ALIAS_HELP_SUFFIX}`)
         .option('--agent <agent>', agent_target_options_1.AGENT_OPTION_DESCRIPTION)
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)
         .action(async (worktreeId, answer, options) => {
         try {
-            // [SEC4-04] Validate worktree ID
-            if (!(0, api_client_1.isValidWorktreeId)(worktreeId)) {
-                console.error('Error: Invalid worktree ID format.');
-                process.exit(types_1.ExitCode.CONFIG_ERROR);
-            }
-            // Validate agent if provided
-            if (options.agent && !(0, cli_tool_ids_1.isCliToolId)(options.agent)) {
-                console.error('Error: Invalid agent.');
-                process.exit(types_1.ExitCode.CONFIG_ERROR);
-            }
-            // Issue #868 / #2376: an instance id or a roster alias.
-            if (options.instance && !(0, instances_1.isInstanceSelector)(options.instance)) {
-                console.error(instances_1.INSTANCE_SELECTOR_ERROR);
-                process.exit(types_1.ExitCode.CONFIG_ERROR);
-            }
-            // Issue #1681: exactly one of <answer> / --default
-            const useDefault = options.default === true;
-            if (useDefault && answer !== undefined) {
-                console.error('Error: <answer> and --default are mutually exclusive.');
-                process.exit(types_1.ExitCode.CONFIG_ERROR);
-            }
-            if (!useDefault && (answer === undefined || !answer.trim())) {
-                console.error('Error: Answer cannot be empty. Provide an answer or --default.');
-                process.exit(types_1.ExitCode.CONFIG_ERROR);
-            }
+            const useDefault = validateRespondArgs(worktreeId, answer, options);
             const client = new api_client_1.ApiClient({ token: options.token });
             // Issue #1629: /prompt-response derives the session name from cliTool
             // and falls back to the worktree default, so `--instance codex` alone
@@ -168,15 +380,7 @@ function createRespondCommand() {
             const agent = target ? target.cliToolId : options.agent;
             // Issue #2376: the resolved id. /prompt-response reads instance ids.
             const instanceId = target?.instanceId;
-            // [DR2-06] Use prompt-response API with cliTool (not cliToolId)
-            const body = useDefault ? { useDefault: true } : { answer };
-            if (agent) {
-                body.cliTool = agent;
-            }
-            // Issue #868: target a specific agent instance
-            if (instanceId) {
-                body.instanceId = instanceId;
-            }
+            const body = buildPromptResponseBody(useDefault, answer, agent, instanceId, options.planReview);
             // Issue #2040: for an agent that publishes per-decision ids (opencode
             // today, and only opencode), a bare `respond <worktree> 3` names the ONE
             // decision that agent is holding, and the number is resolved against
@@ -189,7 +393,11 @@ function createRespondCommand() {
             // the structured path refuses it (`answerStructuredDecision` says so in
             // as many words) — while Enter at a `keys` dialog is a real answer that
             // this command has always been able to give.
-            const structured = !useDefault && (await addressesDecisionsById(client, worktreeId, agent, instanceId));
+            //
+            // Issue #3125: a plan review action names no decision, so it skips this.
+            const structured = !useDefault &&
+                options.planReview === undefined &&
+                (await addressesDecisionsById(client, worktreeId, agent, instanceId));
             let result = null;
             if (structured) {
                 const outcome = await answerSolePendingDecision(client, worktreeId, body);
@@ -205,85 +413,20 @@ function createRespondCommand() {
                 result = await client.post(`/api/worktrees/${worktreeId}/prompt-response`, body);
             }
             if (result && !result.success) {
-                // [DR2-06] Check reason for failure
-                const reason = result.reason || 'unknown';
-                // Issue #1681 / #1726: these mean the server refused BEFORE sending,
-                // so the terminal is untouched — worth saying plainly, because the
-                // other reasons leave the answer's fate unknown. Issue #2486 adds
-                // `unsupported_dialog_layout`: a picker IS on screen but its layout
-                // could not be verified, and the server's message says what to do.
-                const refusedBeforeSending = reason === 'unresolvable_answer' ||
-                    reason === 'answer_out_of_range' ||
-                    reason === 'unsupported_dialog_layout';
-                // Issue #1898: the verdict was addressed to the agent's own API and
-                // the POST did not land. Distinct from the two above — the answer was
-                // resolved and an attempt was made — and distinct from a keystroke,
-                // whose fate is never knowable.
-                if (reason === 'decision_not_delivered') {
-                    console.error(`Error: The approval could not be delivered to the agent (reason: ${reason}). ` +
-                        'The dialog is still open; answer it in the terminal.');
-                    process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
-                }
-                if (refusedBeforeSending) {
-                    console.error(`Error: Answer was not sent. Reason: ${reason}${result.message ? ` (${result.message})` : ''}`);
-                    // Issue #2583: the operator who lands here typed WORDS at a dialog
-                    // that only takes a choice — a claude / agy Bash approval refused as
-                    // free text, or #2573's "No, tell … what to do differently" row. The
-                    // server's sentence ends with "answer with the option number", and
-                    // this is that command with the ids already filled in, so the next
-                    // step is a paste rather than a trip to the docs while a dialog sits
-                    // open. Printed only for the reason that means "this answer could not
-                    // be mapped onto a choice", and only when the answer was not already
-                    // a number (where the number itself is what was wrong).
-                    if (reason === 'unresolvable_answer' && answer !== undefined && !/^\d+$/.test(answer.trim())) {
-                        const target = options.instance ? ` --instance ${options.instance}` : '';
-                        console.error(`Hint: answer with the option number — \`commandmate respond ${worktreeId} <number>${target}\` ` +
-                            `(\`commandmate capture ${worktreeId}${target}\` prints the dialog and its numbers).`);
-                    }
-                }
-                else {
-                    console.error(`Warning: Response may not have been applied. Reason: ${reason}`);
-                }
-                // Issue #1726: an option number the agent's own payload does not offer
-                // is a bad argument, so it exits with the input-error code the rest of
-                // this command already uses for a malformed worktree id or agent.
-                process.exit(reason === 'answer_out_of_range' ? types_1.ExitCode.CONFIG_ERROR : types_1.ExitCode.UNEXPECTED_ERROR);
-            }
-            // Issue #1681: audit trail — print which option was actually selected.
-            const resolved = result?.resolved;
-            if (resolved) {
-                if (resolved.via === 'structured-decision') {
-                    // Issue #1898: no key was sent. The verdict went to the agent's own
-                    // API by decision id, which is the only way an opencode approval can
-                    // be answered at all — worth saying, because "Response sent." on
-                    // this path would read as "a 1 was typed into the pane".
-                    console.log(`Answered approval ${resolved.decisionId ?? '(unknown id)'} with ` +
-                        `option ${resolved.optionNumber}: ${resolved.optionLabel}`);
-                }
-                else if (resolved.via === 'structured-question') {
-                    // Issue #2040: a question, answered over `POST /question/:id/reply`.
-                    // What is printed is what reached the AGENT — the labels — rather
-                    // than the number that was typed: `respond <id> 2` at a question is
-                    // a position in the agent's own list, and an operator reconciling
-                    // what they meant against what was sent needs the other end of that
-                    // mapping. `freeText` prints the text for the same reason.
-                    const chosen = resolved.optionLabels ?? [];
-                    console.log(`Answered question ${resolved.decisionId ?? '(unknown id)'} with ` +
-                        (chosen.length > 0
-                            ? chosen.map((label, index) => `${resolved.optionNumbers?.[index] ?? '?'}: ${label}`).join(', ')
-                            : `free text: ${(resolved.answers?.[0] ?? []).join(', ')}`));
-                }
-                else if (resolved.via === 'semantic') {
-                    console.log(`Resolved "${answer}" to option ${resolved.optionNumber}: ${resolved.optionLabel}`);
-                }
-                else if (resolved.optionNumber !== undefined) {
-                    console.log(`Selected default option ${resolved.optionNumber}: ${resolved.optionLabel}`);
-                }
-                else {
-                    console.log(`Selected default answer: ${resolved.optionLabel}`);
-                }
+                reportFailedResponse(result, worktreeId, answer, useDefault, options);
             }
+            printResolvedAudit(result, answer);
+            if (result && 'planReview' in result)
+                printPlanReviewOutcome(result, worktreeId, options);
             console.error('Response sent.');
+            // Issue #3093: the option just chosen continues as typed text, which the
+            // dialog no longer takes — name the command that does deliver it.
+            const followUp = readTextFollowUp(result);
+            if (followUp) {
+                console.error(`Next: option ${followUp.optionNumber} ("${followUp.optionLabel}") asks for your text, and the dialog ` +
+                    'is closed now, so `respond` cannot deliver it — send it with ' +
+                    `\`commandmate send ${worktreeId} "<text>"${instanceFlag(options.instance)}\`.`);
+            }
         }
         catch (error) {
             (0, command_helpers_1.handleCommandError)(error);

package/dist/cli/commands/stop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stop.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/stop.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAA6B,MAAM,UAAU,CAAC;AASlE;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAyFrE"}
+{"version":3,"file":"stop.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/stop.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAA6B,MAAM,UAAU,CAAC;AA8ClE;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA6GrE"}

package/dist/cli/commands/stop.js

@@ -14,7 +14,39 @@ const daemon_1 = require("../utils/daemon");
 const security_logger_1 = require("../utils/security-logger");
 const env_setup_1 = require("../utils/env-setup");
 const input_validators_1 = require("../utils/input-validators");
+const server_ready_1 = require("../utils/server-ready");
+const server_url_1 = require("../utils/server-url");
+const process_inspect_1 = require("../utils/process-inspect");
 const logger = new logger_1.CLILogger();
+/**
+ * Issue #3087: with nothing recorded to stop, make sure nothing answers on the configured port
+ * either. A server whose PID file is gone (an orphan from an earlier start, or a file removed by
+ * a failed run) still serves there, and "Status: Stopped" would be false. Such a process cannot
+ * be proven to be ours, so it is reported, never killed.
+ *
+ * Only the main server's .env port is known here; a worktree server's port is not re-derived.
+ *
+ * @returns true when the configured port is free
+ */
+async function ensureConfiguredPortFree(daemonManager, serverLabel) {
+    const endpoint = (0, server_url_1.resolveServerEndpoint)(daemonManager.getEffectiveEnv());
+    const host = endpoint.bind === '0.0.0.0' ? '127.0.0.1' : endpoint.bind;
+    if (!(await (0, server_ready_1.isPortInUse)(host, endpoint.port))) {
+        return true;
+    }
+    const listeners = (0, process_inspect_1.describeListeners)(endpoint.port);
+    logger.error(`${serverLabel} has no running process on record, but something is answering on ${host}:${endpoint.port}` +
+        `${listeners ? `: ${listeners}` : ''}.`);
+    logger.info('It was not started through this PID file, so it was not stopped. ' +
+        'If it is an earlier CommandMate server, stop it yourself (e.g. kill <PID>).');
+    (0, security_logger_1.logSecurityEvent)({
+        timestamp: new Date().toISOString(),
+        command: 'stop',
+        action: 'failure',
+        details: `Unrecorded listener on port ${endpoint.port}${listeners ? ` (${listeners})` : ''}`,
+    });
+    return false;
+}
 /**
  * Execute stop command
  * Issue #125: Use getPidFilePath for correct path resolution
@@ -44,10 +76,30 @@ async function stopCommand(options) {
             const status = await daemonManager.getStatus();
             if (status === null) {
                 logger.info(`${serverLabel} is not running (no PID file found)`);
-                logger.info('Status: Stopped');
             }
             else {
                 logger.info(`${serverLabel} is not running (stale PID file)`);
+                // Issue #3087: the recorded npm process can be gone while the server it launched still
+                // listens as an orphan. stop() finds that process group and stops it, and only reports
+                // failure when something is left behind.
+                if (!(await daemonManager.stop(options.force))) {
+                    logger.error(`Failed to stop ${serverLabel}: its processes or port are still in use`);
+                    (0, security_logger_1.logSecurityEvent)({
+                        timestamp: new Date().toISOString(),
+                        command: 'stop',
+                        action: 'failure',
+                        details: `Failed to stop orphaned server of PID ${status.pid ?? 'unknown'}${options.issue !== undefined ? ` (Issue #${options.issue})` : ''}`,
+                    });
+                    process.exit(types_1.ExitCode.STOP_FAILED);
+                    return;
+                }
+            }
+            if (options.issue === undefined && !(await ensureConfiguredPortFree(daemonManager, serverLabel))) {
+                process.exit(types_1.ExitCode.STOP_FAILED);
+                return;
+            }
+            if (status === null) {
+                logger.info('Status: Stopped');
             }
             process.exit(types_1.ExitCode.SUCCESS);
             return;

package/dist/cli/commands/sync.js

@@ -39,9 +39,9 @@ function createSyncCommand() {
             }
         }
         catch (error) {
-            // The route's only 400 is "No repositories configured..." — the server's
-            // wording names the fix (WORKTREE_REPOS / CM_ROOT_DIR), so pass it
-            // through instead of the generic "Bad request" mapping.
+            // The route's only 400 is "No repositories are registered yet..." — the
+            // server's wording names the fix (Web UI Add Repository / WORKTREE_REPOS),
+            // so pass it through instead of the generic "Bad request" mapping.
             if (error instanceof api_client_1.ApiError && error.statusCode === 400 && error.payload?.error) {
                 console.error(`Error: ${error.payload.error}`);
                 process.exit(types_1.ExitCode.CONFIG_ERROR);

package/dist/cli/docs/setup-guide.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Setup guide for agents (Issue #3059)
+ *
+ * The page the landing page's one-line prompt points an agent at:
+ * https://kewton.github.io/CommandMate/setup.md. `website/` is not in the npm
+ * package, so the same text is carried here as a string constant and served by
+ * `commandmate docs --section setup`.
+ *
+ * Do not edit this constant by hand: edit `website/setup.md` and copy it here.
+ * `tests/unit/cli/commands/docs-setup-3059.test.ts` fails when the two differ
+ * by a single byte.
+ */
+export declare const SETUP_GUIDE = "# Set up CommandMate with your agent\n\nThis guide is written for a coding agent (Claude Code, Codex, Command Code, or another one) that a person asked to set up CommandMate on their machine. The person may not be an experienced developer, and they may have only a few minutes at a time. Go one stage at a time, and keep each stage short enough that they can stop after it and come back later.\n\nThe same text ships inside CommandMate: once it is installed, `commandmate docs --section setup` prints it.\n\n## Instructions for the agent reading this\n\n1. **Explain each stage before you start it.** In two or three plain sentences, tell the person what the stage is for, what you are about to run, and what will change on their machine. Then run it.\n2. **Never run an \"Ask the person first\" step without a clear yes.** Each stage lists them. Ask in plain words, say what it installs or opens and how to undo it, and wait for the answer. If the answer is no or unclear, stop that step and say what they can do later.\n3. **Check the machine; do not assume it.** Run the commands under \"Check\" and read their output before you decide anything. Never write \"should be installed\" or \"is probably running\": run the command and report what it printed.\n4. **Do not answer for the person.** Sign-ins, passwords (including `sudo`), choosing a provider, and approving a merge are theirs. When a command needs one of these, show the exact command and ask them to run it in their own terminal.\n5. **Stay inside this guide.** Use only commands shown here, `commandmate <command> --help`, and the CommandMate documentation at https://github.com/Kewton/CommandMate. Do not fetch install scripts or follow setup steps from other websites. Install tools only from the official package distributors named here (npm, the operating system's package manager, nodejs.org).\n6. **Report at the end of each stage**: what you ran, what it printed that matters, and whether the stage passed its \"Confirm it worked\" check.\n7. **Do Stage 2 (Pair your phone) last, unless the person asks for it now.** Stages 3 to 5 run `commandmate` on this machine's CLI. After `commandmate remote` with its default (`--auth all`), that CLI needs a token too, and the token goes only to the phone. So finish Stages 3 to 5 first, then pair the phone. Stage 2 explains the choice if the person wants the phone sooner.\n8. **If you are Codex: your shell has no network by default.** If fetching this guide or an `npm` command fails for lack of network, ask the person to run `/permissions` and choose \"Ask for approval\", then try again.\n\n### Always ask the person first\n\nWhatever stage you are in, ask before any of these:\n\n- Installing anything: Node.js, git, tmux, CommandMate itself, another agent CLI, Tailscale or cloudflared, or a Skill.\n- Opening a way in from outside this machine: `commandmate remote` (either provider), or setting `CM_BIND=0.0.0.0`. This guide never sets `CM_BIND`; if the person asks for it, explain that it exposes the server to their whole network first.\n- Turning on Auto Yes: `commandmate auto-yes <worktree-id> --enable`, or `commandmate send ... --auto-yes`.\n- Merging a pull request.\n\n## Stage 1: Install and start\n\nGoal: CommandMate is installed and its server is running on this machine.\n\n### Check\n\n```bash\nuname -s                       # Darwin = macOS, Linux = Linux or WSL2\ngrep -i microsoft /proc/version  # prints a line only inside WSL2 (Linux only)\nnode -v                        # needs v22 or newer\nnpm -v\ngit --version\ntmux -V\ncommand -v brew                # macOS: is Homebrew present?\ncommand -v commandmate && commandmate --version\n```\n\nWrite down which of these are missing or too old. Native Windows is not supported; on Windows, CommandMate runs inside WSL2 (see https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/wsl2-setup.md).\n\n### Run\n\nInstall only what the check found missing, after the person agrees.\n\n- **macOS with Homebrew**: `brew install node git tmux` (leave out what is already there).\n- **macOS without Homebrew**: tmux needs a package manager. Tell the person that, and let them decide whether to install Homebrew from its own official instructions. Do not install it for them. git alone can come from Apple's tools: `xcode-select --install`.\n- **Linux / WSL2 (Debian or Ubuntu)**: `sudo apt update && sudo apt install -y git tmux`. The `sudo` password is the person's to type. If `node -v` is missing or older than v22, the distribution's package is usually too old: tell the person and use the official Node.js download (https://nodejs.org/en/download) in the way they choose.\n\nThen install and start CommandMate:\n\n```bash\nnpm install -g commandmate     # the global install: for daily use\ncommandmate --version\ncommandmate init --defaults    # writes ~/.commandmate/.env; repositories go under ~/repos\ncommandmate start --daemon\n```\n\n**`npx commandmate@latest` versus the global install.** `npx commandmate@latest` is the one-line way for a person to try CommandMate in their own terminal: it asks its setup questions and opens the browser. It needs an interactive terminal, so when you run it from your tool it only prints help. Use the global install above when you are the one running the commands, and for anything the person will keep using.\n\n### Ask the person first\n\n- Each tool you are about to install (Node.js, git, tmux), and the exact command.\n- `npm install -g commandmate`.\n- If `~/.commandmate/.env` already exists, `commandmate init --defaults` stops with \".env file already exists\": CommandMate is already configured, so skip `init`. Do not add `--force` without asking: it replaces their settings.\n\n### Confirm it worked\n\n```bash\ncommandmate status             # reports the server as running, with its URL\n```\n\nTell the person to open the URL it prints (by default http://localhost:3000) in their browser.\n\n### If it fails\n\n- `commandmate: command not found` after `npm install -g`: npm's global bin directory is not on `PATH`. Run `npm prefix -g` and show the person; the fix is in https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/cli-setup-guide.md#command-not-found-error.\n- `EACCES` during `npm install -g`: do not retry with `sudo`. Show the person the \"Permission Error (EACCES)\" section of the same setup guide.\n- The port is already in use: `commandmate start --daemon --port 3001`, then `commandmate status`.\n- The server does not start: `commandmate status`, then `commandmate stop --force` and `commandmate start --daemon` again. Read what it prints rather than retrying blindly.\n\n## Stage 2: Pair your phone\n\nGoal: the person scans a QR code with their phone and sees CommandMate there.\n\n`commandmate remote` makes this server reachable from outside the machine through a provider, and prints a QR code that pairs one phone. There are two providers, and **the person chooses which one**:\n\n| | Tailscale (`--provider tailscale`) | Cloudflare (`--provider cloudflare`) |\n|---|---|---|\n| Who can reach it | Only devices signed in to the person's own Tailscale network (tailnet) | Anyone with the URL: it is a public address on the internet |\n| What protects it | The tailnet, plus CommandMate's token login | A one-time pairing code (single use, expires in 10 minutes by default), plus CommandMate's token login |\n| Needs | The Tailscale app on this machine and on the phone, both signed in to the same account, with HTTPS (Serve) available | `cloudflared` installed on this machine; no account |\n| Approval | No public-tunnel approval | A public tunnel: `--yes` only after the person agrees |\n\nExplain both in plain words and ask which one they want. If they cannot decide, Tailscale keeps the server off the public internet; Cloudflare needs fewer accounts.\n\n**When to do this stage.** By default (`--auth all`), once `commandmate remote` runs, the `commandmate` CLI on this machine also needs a token, and the token goes only to the phone. Stages 3 to 5 run on that CLI, so they stop working. Ask the person which they want:\n\n- **Pair the phone last (recommended).** Skip to Stage 3 now, and come back to this stage after Stage 5.\n- **Pair the phone now, and keep the CLI on this machine.** Add `--auth remote-only` to the `commandmate remote` command below. Only the phone's route then needs the token: every process on this machine, agents included, can operate CommandMate without logging in. Say that plainly before they choose it.\n\n### Check\n\n```bash\ncommandmate status             # is the server running, and with authentication?\ncommandmate remote status      # is a remote session already recorded?\ntailscale status               # Tailscale: installed and signed in?\ncloudflared --version          # Cloudflare: installed?\n```\n\n### Run\n\n1. Install the chosen provider if the check found it missing, after the person agrees:\n   - **Cloudflare**: on macOS `brew install cloudflared`; on Linux, from Cloudflare's official package repository for their distribution.\n   - **Tailscale**: the person installs the Tailscale app from Tailscale's official distribution on this machine and on their phone, and signs in themselves. Signing in is theirs to do.\n2. If `commandmate status` showed the server running, stop it first, so `remote` can start it again with authentication: `commandmate stop`.\n3. Publish and pair:\n\n```bash\ncommandmate remote --provider tailscale\n# or, only after the person agreed to a public URL:\ncommandmate remote --provider cloudflare --yes\n```\n\n`remote` starts the server itself, publishes it, and prints the QR code. Show the person the QR code and tell them to scan it with the phone's camera. If the output is too narrow for a QR code, it prints a URL instead: that URL contains the pairing code, so give it only to the person and do not save it to a file or a log.\n\nIf the QR code cannot be read, or scanning it does not get the person in, have them copy the pairing URL and paste it into the address bar of the phone's browser. Pasting the link into the address bar is the way that worked in the hands-on check; do not save the link to a file.\n\nTo get the link as text again without reopening the tunnel, run `commandmate remote pair` (or `commandmate remote pair --json` and read `pairingUrl`). The URL stays the same, and it works only while the code is unused.\n\n### Ask the person first\n\n- Which provider: Tailscale or Cloudflare.\n- Installing that provider.\n- Running `commandmate remote` at all: it opens a way in from outside this machine.\n- Pairing now or after Stage 5, and, if now, whether to add `--auth remote-only`.\n- `--yes`: only after they agreed to the public Cloudflare URL. Never add `--yes` to get past a question they have not answered.\n\n### Confirm it worked\n\n- The person says the phone opened CommandMate.\n- `commandmate remote status` shows `Pairing: consumed`.\n\nTo close the way in later: `commandmate remote stop`. The server keeps running.\n\n### If it fails\n\n- Exit 1, \"no provider is usable\": read the reason it prints. For Tailscale it is usually \"not connected\" (the person has not signed in) or \"no MagicDNS name\". Do not switch to Cloudflare without asking: that changes who can reach the machine.\n- Exit 2 without a terminal: Cloudflare needs `--yes`, or a server is running that `remote` has to restart. Ask the person, then run `commandmate stop` and try again.\n- Exit 2, \"a server with authentication is already running\": `commandmate stop`, then `commandmate remote` again.\n- The QR code is cut off in the agent's chat pane, or the person lost it, and it has not been used yet: run `commandmate remote pair`. The public URL stays the same and the earlier link stops working. The new code keeps the original expiry time.\n- The code expired or was already used: run `commandmate remote stop`, then `commandmate remote` again for a new QR code (`remote pair` prints nothing for a used or expired code). `--pairing-expires 30m` gives a slower person more time.\n- After pairing, the browser on this machine asks for a login and the CLI stops answering: that is the default `--auth all`. Do not look for a way to give the token to the CLI. Ask the person to choose: run `commandmate remote stop` and finish Stages 3 to 5 on this machine first, or pair again with `--auth remote-only` (every process on this machine can then operate CommandMate without logging in).\n\n## Stage 3: Add a second agent\n\nGoal: a second agent CLI, for example Command Code or Codex, can work in one of the person's repositories through CommandMate.\n\nBefore Stages 3 to 5: CommandMate needs at least one of the person's repositories registered. The CLI cannot register one; the person does it in the browser, under **Repositories \u2192 Add Repository**.\n\n### Check\n\n```bash\nclaude --version\ncodex --version\ncommandcode --version          # Command Code\ncommandmate ls                 # the worktrees CommandMate knows about\n```\n\nIf `commandmate ls` lists nothing, the person has not registered a repository yet. CommandMate only manages repositories under `~/repos` (the `CM_ROOT_DIR` that `init` set). Ask the person to open **Repositories \u2192 Add Repository** in the browser and add one, or to tell you where their repository is so you can check whether it is under that directory. Then run `commandmate sync` and `commandmate ls` again.\n\n### Run\n\nInstall the CLI the person picked, after they agree:\n\n```bash\nnpm install -g command-code    # Command Code; CommandMate runs it as `commandcode`\nnpm install -g @openai/codex   # Codex\n```\n\nSigning in to the CLI is the person's: ask them to run `commandcode` (or `codex`) once in their own terminal and finish its sign-in. Then add it to a worktree and give it a first, small message:\n\n```bash\ncommandmate instances <worktree-id> add --agent command-code\ncommandmate instances <worktree-id>\ncommandmate send <worktree-id> \"Read the README and summarize this repository in three lines.\" --instance command-code\ncommandmate wait <worktree-id> --instance command-code --timeout 600\ncommandmate reply <worktree-id> --instance command-code\n```\n\nFor Codex, use `--agent codex` and `--instance codex`.\n\nThe first time Codex starts in a worktree it shows two confirmation screens. Show them to the person with `commandmate capture <worktree-id> --instance codex`; do not answer them yourself.\n\n- `Trust this folder?`: whether Codex may work in this folder.\n- `Hooks need review (5 hooks are new or changed)`: these hooks are not from the repository. CommandMate wrote them into `~/.codex/hooks.json` itself, marked with `# commandmate:agent-hooks`, and they only send Codex's events to CommandMate on localhost. Check this with `grep -n 'commandmate:agent-hooks' ~/.codex/hooks.json` before you say where they came from. If the person does not trust them, Codex still works, but CommandMate cannot receive Codex's state as events, so `wait` and the status shown in the browser are less accurate.\n\n### Ask the person first\n\n- Which CLI to add, and installing it.\n- The sign-in, which they do themselves.\n- Do not turn on Auto Yes (`--auto-yes`, `commandmate auto-yes --enable`) to get past the CLI's own confirmations. If it stops on a question, show the person with `commandmate capture <worktree-id> --instance command-code` and let them answer.\n\n### Confirm it worked\n\n- `commandmate instances <worktree-id>` lists the new instance.\n- `commandmate reply <worktree-id> --instance command-code` prints its answer.\n\n### If it fails\n\n- \"is not installed or not in PATH\": the message names the install command. Run `commandcode --version` to check, and ask before installing.\n- `wait` exits 10: the agent is waiting on a question (often its own sign-in or a permission). Show the person `commandmate capture <worktree-id> --instance command-code`.\n- `wait` exits 124: it timed out. Check `commandmate capture` before waiting again.\n- \"Worktree ID not found\": run `commandmate sync`, then `commandmate ls`, and copy the ID exactly.\n\n## Stage 4: Give your team a PM\n\nGoal: one session plans the work and hands tasks to the others. That session is the lead (the \"PM\"). Skills from CommandMate's official Catalog teach it the method.\n\n### Check\n\n```bash\ncommandmate skill list                                         # what the Catalog offers\ncommandmate skill info cmate-orchestrate                       # versions, risk, compatibility\ncommandmate skill status cmate-orchestrate --worktree <worktree-id>\n```\n\n### Run\n\nPick the exact version from `skill info`, show the person the plan, and install after they agree:\n\n```bash\ncommandmate skill install cmate-orchestrate --worktree <worktree-id> --version <version> --dry-run\ncommandmate skill install cmate-orchestrate --worktree <worktree-id> --version <version> --yes --ack-risk cmate-orchestrate@<version>\n```\n\n`cmate-orchestrate` is a high-risk Skill: it needs `--ack-risk <skill-id>@<version>` in addition to `--yes`. A Skill that is not high-risk needs only `--yes`. The Skill lands in `.agents/skills/` and `.claude/skills/` of that worktree.\n\nAn agent reads its Skills when its session starts, so the lead session has to start again. Ask the person whether to restart it from the worktree screen; if they prefer the CLI, `commandmate instances <worktree-id> kill <instance-id>` stops it and the next `commandmate send` starts it again.\n\nThen ask the lead in plain words. For example, sent to the lead session (in Claude Code the Skill is also available as `/cmate-orchestrate`):\n\n```bash\ncommandmate send <worktree-id> \"Use the cmate-orchestrate skill to plan issues #12 and #13. Show me the plan; do not run anything that changes the repository yet.\" --instance claude\n```\n\nThe plan step changes nothing. Steps that change something run only when the person approves them.\n\nCommand Code's plan mode (Command Code only; this workaround can be removed once #3125 is fixed): if the lead enters plan mode, it stops on a REVIEW screen and CommandMate cannot send a comment to it from the CLI. When you only want a plan, ask in plain words as above and do not have the lead enter plan mode.\n\n### Ask the person first\n\n- Installing each Skill, after showing the `--dry-run` plan. Say plainly that `cmate-orchestrate` is marked high-risk and what `--ack-risk` acknowledges.\n- Restarting the lead session.\n- Every approval the lead asks for, and every merge. You never approve or merge on the person's behalf.\n\n### Confirm it worked\n\n- `commandmate skill status cmate-orchestrate --worktree <worktree-id>` reports it as installed.\n- The lead's reply (`commandmate reply <worktree-id> --instance claude`) shows a plan.\n\n### If it fails\n\n- `skill install` exits 2: `--version` is missing or does not exist. Copy it from `skill info`.\n- Exit 12: the install was not confirmed: no `--yes`, or a high-risk Skill without `--ack-risk`. Ask again rather than adding flags on your own.\n- Exit 11: the worktree has local changes in the way. Show the person `git status` in that worktree.\n- Exit 1: the server or the Catalog could not be reached. Check `commandmate status`.\n- The agent does not know the Skill: its session started before the install. Restart it.\n\n## Stage 5: Let checks decide what's done\n\nGoal: \"done\" means the repository's own checks passed, not that an agent said so.\n\n### Check\n\n```bash\nls .commandmate/verify.yaml                    # in the repository: are gates declared?\ncommandmate skill status cmate-verify --worktree <worktree-id>\n```\n\n### Run\n\n1. Declare the gates. Either install the `cmate-verify` Skill (as in Stage 4, after the person agrees) and ask the lead to write `.commandmate/verify.yaml` with it, or draft it from the repository's CI definitions:\n\n```bash\ncommandmate verify init --cwd <repository-path> --dry-run   # print the draft, write nothing\ncommandmate verify init --cwd <repository-path>             # write it (never overwrites)\n```\n\nShow the person the gates (lint, type check, tests and so on) and change them only with their agreement.\n\nBefore handing over a task that commits, check that git knows who is committing: `git config user.name` and `git config user.email` in the repository (a worker's commit fails when they are empty). If they are empty, ask the person for their name and email, and set them only with their answer. Do not let a worker invent a bot name. The person may also choose to have the worker leave the changes uncommitted.\n\n2. Run the gates once on the worktree as it is:\n\n```bash\ncommandmate verify <worktree-id>\n```\n\n3. Hand a task over under a contract, and let the gates judge it. A contract is a YAML file in the repository, `.commandmate/tasks/<name>.yaml`, that states the goal, the files the agent may change, and the checks that decide when it is done:\n\n```yaml\nversion: 1\ntitle: \"Issue #12: <one-line summary>\"\ngoal: |\n  Implement issue #12. Commit when the work is done.\nscope:\n  allow:\n    - \"src/**\"\n    - \"tests/**\"\nverify:\n  gates: [lint, unit]        # gate ids from .commandmate/verify.yaml\nsuccess:\n  requireWorkEvidence: true\n  requireScopeClean: true\n```\n\n```bash\ncommandmate send <worktree-id> --contract .commandmate/tasks/issue-12.yaml --instance command-code\ncommandmate wait <worktree-id> --instance command-code --verify\n```\n\n`wait --verify` exits **0** when every gate passed, **20** when a gate failed, and **21** when there is no work to judge (no commits and no changes).\n\n### Ask the person first\n\n- Installing `cmate-verify`, and writing `.commandmate/verify.yaml` into their repository.\n- Which gates to declare, and any later change to them.\n- Merging the result. A passed gate means the checks passed; whether to merge is still the person's decision.\n\n### Confirm it worked\n\n- `commandmate verify <worktree-id>` ends with exit 0, or with a gate failure the person recognizes as real.\n- `commandmate verify history` lists the run.\n\n### If it fails\n\n- `verify` exits 21 right away: the worktree has no work yet. That is expected before a task.\n- Exit 20: a gate failed. `commandmate verify show <run-id>` shows which one and the end of its log. Report it; do not weaken the gate to make it pass.\n- The contract is rejected (exit 2): it prints every problem, for example a gate id that is not in `verify.yaml`. Fix the contract, not the gates.\n\n## Where to read more\n\n- CommandMate on GitHub: https://github.com/Kewton/CommandMate\n- CLI operations guide, every flag and exit code: https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/cli-operations-guide.md\n- The project site: https://kewton.github.io/CommandMate/\n";
+//# sourceMappingURL=setup-guide.d.ts.map

package/dist/cli/docs/setup-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-guide.d.ts","sourceRoot":"","sources":["../../../src/cli/docs/setup-guide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,WAAW,wzsBA8VvB,CAAC"}