premanmcp 1.1.18 → 1.1.20

package/README.md

@@ -1,4 +1,4 @@
-# `premanmcp` 1.0
+# PreMan CLI and MCP bridge
 
 `premanmcp` is the compatibility client for agents that can start only a local
 stdio MCP process. It forwards MCP initialization, discovery, notifications,
@@ -18,6 +18,284 @@ four-tool PreMan conversation protocol:
 
 PreMan can add private agent capabilities without publishing a new npm package.
 
+## Installed desktop and delegated QA
+
+This source tree adds durable delegated tasks to the modern CLI. The npm package
+version alone is not evidence that this feature has been published. Desktop
+packages record the exact CLI Git revision, dirty state and content hashes in
+`resources/cli/bundle-manifest.json`; `preman doctor --json` reports that provenance
+when present. Release builds require clean, pinned backend and dashboard sources.
+
+On a desktop build containing these resources, sign-in provisions a revocable
+machine API key and an executable at `~/.local/bin/preman` (Windows uses
+`preman.cmd`). The launcher uses the signed app's embedded Electron Node runtime,
+so a separate Node or npm installation is unnecessary. It retains the app's
+absolute path; moving the app requires opening it again to refresh the launcher.
+Add `~/.local/bin` to PATH if it is not already there. Detected Codex, Claude Code
+and Cursor installations get MCP configuration and marked instructions pointing
+to that exact executable. Existing unrelated configuration is preserved and
+conflicts are reported. Start a new harness session after registration.
+
+To register an agent explicitly, run the installed executable with
+`preman connect --agent codex --no-guide` (or `claude-code` / `cursor`).
+Connect writes the config and redeems the account pairing through its existing
+heartbeat. Interactive connection verification initializes the configured MCP
+bridge and discovers the four public tools; it does not invoke a tool, start a
+coding agent, or run QA. `--no-self-test` skips that transport check, and
+`--no-wait` writes the config and redeems pairing without waiting or self-testing.
+After restarting the coding agent, use `preman doctor --json` and
+`preman capabilities --json` to inspect readiness and available QA modes.
+
+Other coding harnesses can invoke the executable as a normal CLI, or configure
+standard MCP stdio with the absolute launcher path and `args: ["start"]`. The
+generic MCP descriptor is available from `preman local status` in
+`integrations.generic_mcp`. The machine credential is read from the shared,
+backend/account-bound private credential store; it is not copied into harness
+configuration. The bridge passes through server tools/resources and MCP Apps
+metadata rather than maintaining a separate QA tool catalogue. A harness with
+MCP Apps support can render the shared interactive task card; a CLI caller can
+attach the PNG preview described below.
+
+```bash
+preman capabilities --json
+preman doctor --json --workspace WORKSPACE_ID
+preman doctor --json --workspace WORKSPACE_ID --mode endpoint \
+  --target http://127.0.0.1:8000 --repo /absolute/repository --executor-kind local
+```
+
+`connection_ready` means authentication, backend and runtime are connected.
+`target_ready` is null until a target/source is supplied; it never implies a QA
+pass. Capabilities use the server's existing modes, resources and action policies.
+Selection retains workspace → collection → folder → request scope. Supply saved
+IDs in a `--context-json` file, for example:
+
+```json
+{
+  "mode": "endpoint",
+  "intent": "test",
+  "resources": {"collection_id": "COLLECTION_ID", "folder_id": "FOLDER_ID", "request_ids": ["REQUEST_ID"]},
+  "caller": {"name": "codex", "session_id": "CALLER_SESSION_ID"}
+}
+```
+
+The durable task interface defaults to one JSON object per response. `watch`
+emits JSONL snapshots, ordered events and a resume checkpoint. Errors are JSON on
+stdout, with a stable code and retryability; no machine command logs in, opens a
+browser or silently answers an approval. Human `chat -p` remains available.
+Nested commands such as `preman task start --help` and `preman patch apply --help` show scoped help without authentication, network calls, or execution.
+
+Prepare a complete source handoff before starting a task:
+
+```bash
+preman task prepare -p "Run the saved checks; repair the implementation if they fail." \
+  --workspace WORKSPACE_ID --context-json scope.json --repo /absolute/repository \
+  --target http://127.0.0.1:8000 --executor-kind local --repair patch \
+  --output /tmp/preman-prepared.json --json
+preman task start --prepared /tmp/preman-prepared.json --json
+```
+
+Preparation captures/uploads the requested source and validates its workspace and
+context without starting a task or calling a model. `status: "ready"` validates
+the handoff, not runtime qualification or a passing test. `needs_input` lists
+missing fields and corrective actions. For MCP, call `preman_chat` with the exact
+`mcp.arguments` from that JSON, including the snapshot, workspace, repair policy
+and idempotency key. Plain MCP chat remains conversational. CLI `--prepared`
+rejects context overrides; prepare again when the intended scope changes.
+`PREMAN_WORKSPACE_ID` supplies the workspace when `--workspace` is absent.
+On macOS, source operations fall back to the selected Xcode Git executable when
+the system launcher cannot write its cache inside an agent sandbox. An explicit
+`PREMAN_GIT_BIN` remains authoritative.
+Direct task starts also reject missing source context before creating any work;
+CLI errors preserve `error.issues` and `error.workspace_choices`. Correct the
+input and retry. Existing tasks retain immutable source context; use a linked
+retest for the applied tree.
+
+```bash
+preman task start -p "Check the saved requests against this source; report failures." \
+  --workspace WORKSPACE_ID --context-json scope.json --repo /absolute/repository \
+  --target http://127.0.0.1:8000 --executor-kind local --repair patch \
+  --idempotency-key caller-operation-001
+preman task get TASK_ID
+preman task wait TASK_ID --execute-local --timeout 600 --check
+preman task watch TASK_ID --execute-local --after 0 --timeout 600
+preman task reply TASK_ID --request REQUEST_ID --answers-json answers.json
+preman task message TASK_ID -p "Use the failure evidence to repair the implementation and return a patch."
+preman task cancel TASK_ID
+preman task result TASK_ID --check
+```
+
+Retain the task ID and event cursor. Retry a mutation with the same idempotency
+key and payload. Required input and exact action proposals return attention
+states; only use `preman action confirm PROPOSAL_ID` after the human explicitly
+approved that proposal's displayed impact. Cancellation is acknowledged only
+after the owned work stops. Ctrl-C stops the CLI's wait, stops its local active
+operation, and preserves the durable task; it does not silently cancel the task.
+An interrupted claimed local operation is reported as incomplete, not replayed.
+
+Exit codes: normal successful requests are 0. With `--check`, 0 requires a
+verified pass bound to the task's exact source snapshot or explicit target build;
+1 means failed QA; 2 means unverified, inconclusive or attention required; 3 means
+still running. Client/API errors are 4 and interrupted waits are 130. A completed
+chat turn, submitted job, successful patch application or missing source identity
+cannot produce a verified `--check` pass.
+
+### Missing QA capabilities
+
+Delegated tasks report genuine unsupported capabilities in `feature_requests`.
+Each persisted receipt has `capture_status: "saved"`, a stable request ID,
+summary, review status and exact web/native links. The Feature requests page in
+Workbench shows the workspace's reports. Developers use the separately
+authenticated review surface to triage them. Repeated reads do not create
+reports, and repeated reports of the same task/capability reuse the receipt.
+
+Setup, authentication, permission, budget and transient failures remain task
+blockers. They do not automatically become product feature requests. Saving
+feedback does not resolve missing coverage or establish a verified QA pass.
+An `unavailable` capture has no saved request ID or link; callers must report
+that failure rather than claim the feedback reached developers.
+
+The Preman agent can report a missing capability through its private
+`report_capability_gap` action. CLI and MCP callers continue the existing task
+with the missing capability if more context is needed; the four public MCP
+tool names remain unchanged. Display the returned receipt and link alongside
+the coverage gap. See [the feedback contract](../docs/DELEGATION_FEATURE_FEEDBACK.md)
+for storage, access and recovery behavior.
+
+### Local execution and repair
+
+`--repo` captures dirty and untracked eligible source into an immutable local
+snapshot and uploads the bounded snapshot to the owned workspace: at most 500
+files, 2 MiB each, 8 MiB total. Symlinks, generated paths, credential paths and
+detected private keys are excluded. The returned manifest names exclusions.
+Review it with `preman snapshot create --repo /absolute/repository` before upload
+when needed. Source is not placed in ordinary chat context.
+
+An explicitly selected local executor needs `task wait/watch --execute-local`.
+Without a source snapshot, localhost requests use bounded, same-origin HTTP on
+that device and cannot claim a source-specific pass. With a source snapshot,
+the CLI boots the immutable source in a distinct Docker container and replays
+the frozen saved checks against that container, not the caller's original server.
+The source manifest and execution-plan digest are bound to the run lease.
+
+Local repairs use the same native PreMan agent loop. Its bounded file operations
+edit a private candidate snapshot; the coding harness is not redispatched as a
+second repair agent. Original test/config files are frozen. Dependencies, suite
+commands and service replay run only in a local Docker engine with a preinstalled
+qualified image. Test/boot containers have no network, dropped capabilities,
+resource limits and no host credentials; dependency installation has network
+access inside its restricted container. No host-shell fallback or implicit image
+pull is used. Missing Docker, images, checks or target permissions remain explicit
+readiness/verification gaps. `--repair patch` permits returning a patch, never
+applying it to the caller's checkout.
+
+```bash
+preman artifacts get TASK_ID PATCH_ARTIFACT_ID --output /absolute/repair.json
+preman patch apply --file /absolute/repair.json --repo /absolute/repository --check-only
+preman patch apply --file /absolute/repair.json --repo /absolute/repository
+preman task retest TASK_ID --repo /absolute/repository --idempotency-key caller-retest-001
+preman task wait NEW_TASK_ID --execute-local --timeout 600 --check
+```
+
+Patch application validates the original snapshot, exact changed-file preimages
+and modes, paths, digest and postimages before editing. Unrelated caller edits
+are preserved; changed preimages are rejected. Binary patches are unsupported.
+Retest creates a new task/run against the newly captured source and the original
+saved checks. It does not inherit the old verdict or verify merely by applying.
+`artifact fetch` remains an alias for `artifacts get`.
+
+For local AppQA, select `mode: "app_qa"`, `executor: {"kind":"local"}` and an
+explicit supported target in context. Task creation checks target readiness and
+registers the existing desktop controller before the server creates its run.
+`wait/watch --execute-local` starts that assigned worker. Web targets without an
+explicit existing-browser selection use the bundled isolated browser. Native app,
+existing-browser and simulator targets require their platform qualification and
+OS permissions; no permissions are requested silently. Closing the app window preserves supported
+background execution; quitting the app stops it. A fully restarted app must prepare
+a new worker/task rather than reusing a revoked worker lease. `preman local status`
+and `preman local app-qa capabilities` distinguish those states.
+
+Local web UI Flows use the installed desktop's bundled Electron browser and the
+same Flow step engine as the backend worker. `task wait --execute-local` starts
+only the owned run assigned to this device; no source checkout, separate worker,
+browser download or Node installation is required. The browser uses a disposable
+profile, blocks requests outside the selected origin, and captures each step.
+The CLI also starts child Flow/AppQA runs created by repair verification.
+
+Web AppQA uses that isolated browser beneath the existing AppQA observation,
+action, lease and evidence controller. Native macOS apps, explicitly selected
+existing browser sessions and iOS simulators retain their permission and platform
+qualification gates. `doctor --mode flow --executor-kind local --target-kind web
+--target http://127.0.0.1:3000` reports installed runtime readiness.
+
+A source-bound repair can keep a private candidate service alive while the real
+saved Flow, AppQA, endpoint and agent checks replay. All source commands run in a
+bounded local container; the runtime verifies the immutable source, execution
+plan and actual image ID. Private headers protect its loopback proxy and never
+appear in public task evidence. Requests are bounded HTTP; WebSockets and streaming
+are not supported by this local candidate proxy. No replay is assigned the
+original caller's localhost service as candidate evidence.
+For ASSERT source callables, the native message/history contract runs only inside
+the selected source container. Provider-dependent code needs explicitly configured
+isolated prerequisites; no caller provider secret is copied into the container.
+Sandbox agent evaluations build the fixed root Dockerfile from the immutable
+snapshot, using cached base images and no build network, mounts, secrets or remote
+ADD. They require an existing paired evaluation runner connected on the same
+device and Docker daemon; that runner consumes the normal agent_eval_v1 case jobs.
+The CLI watch loop does not impersonate that evaluation runner. Missing Dockerfile,
+base image or paired runner is an explicit prerequisite.
+
+Closing the desktop window leaves its local executor available. A full process
+restart preserves task history, but an interrupted AppQA worker is not rebound to
+an uncertain browser session. `local_worker_session_lost` requires confirmed
+cleanup followed by `preman task retest <task-id>`; it never replays browser input
+from an expired worker lease.
+
+### Evidence, exact links and previews
+
+Every task includes `links.native_url` and `links.web_url` for its exact page.
+The native format is `preman://open?source=agent&route=<encoded-workbench-route>`;
+use the web URL when the desktop cannot open. Do not replace a task/run link with
+the app home page. Protected artifacts require the caller's normal authentication:
+
+```bash
+preman artifacts get TASK_ID ARTIFACT_ID --output /absolute/evidence.png
+preman task preview TASK_ID --output /absolute/task-card.png
+preman task result TASK_ID --preview --output /absolute/task-card.png
+```
+
+The installed desktop renders previews from the same bundled MCP task card using
+its sandboxed offscreen Chromium. It works with the main window closed while the
+desktop process remains alive. The returned absolute `local_path`, media type and
+SHA256 let a coding harness attach the preview inline. It requires no Chromium
+download. Explicit local execution or preview commands can wake the installed
+app in the background; readiness inspection never launches it or opens login.
+Remote artifacts retain their normal authentication requirements.
+
+### Upgrade and removal
+
+Upgrade the desktop normally, then open it once to refresh its launcher and
+managed harness registrations. A release bundles a pinned CLI plus the pinned
+dashboard task renderer, and packaging fails if those resources or hashes are
+missing. Release smoke tests execute the packaged Electron binary with Node
+removed from PATH, then initialize MCP and discover tools/resources. The Electron
+RunAsNode fuse must stay enabled for this launcher.
+
+`preman harness status` reports managed registrations. Run `preman harness install`
+after installing another coding harness; it preserves unrelated configuration and
+enables the PreMan server for Cursor CLI. Start a fresh harness session afterward.
+
+```bash
+preman harness remove --disconnect --remove-launcher
+```
+
+This stops local desktop executors, revokes the connected machine key, removes
+unchanged managed MCP entries and instruction blocks, and removes the marked
+launcher. User-modified entries remain intact and are reported. If backend
+revocation cannot be confirmed, removal stops with an actionable error. Then
+remove the PreMan app normally. Private snapshots/repair evidence under `~/.preman`
+remain available until explicitly removed. Desktop sign-out also stops local
+work, revokes its machine key and removes only that account's credential profile.
+
 ## Installing
 
 ```bash
@@ -32,6 +310,11 @@ stuck in. `--no-desktop` (or `PREMAN_NO_DESKTOP=1`) skips it, and it is skipped
 automatically off macOS, where there is no build. The git pre-push hook is the
 one thing still asked about, since it changes what happens on every push.
 
+Hook repair preserves an existing `--read-only` verification policy. Background
+repairs and command probes suppress further automatic repairs; help, version,
+and MCP startup do not schedule repairs. `PREMAN_NO_HOOK_REPAIR=1` disables
+background repair while leaving an explicit `preman hook repair` available.
+
 `preman install --cursor` writes Cursor's MCP config and nothing else, which is
 what plain `install` used to mean; `install --api-key …` and
 `install --project --backend …` are unchanged.
@@ -39,6 +322,44 @@ what plain `install` used to mean; `install --api-key …` and
 Nothing needs installing to try it: `npm exec -y premanmcp@latest -- <command>`
 runs any of these once, fetching the newest version each time.
 
+### Personal QA instructions
+
+`npm exec -y premanmcp@latest -- onboard` also installs persistent instructions
+telling detected coding agents to use the PreMan CLI agent for every QA task:
+agent evaluations, compatibility across agents, useful user simulations,
+full-stack API-to-frontend testing, backend testing, and frontend QA. The same
+step runs through `setup` and the onboarding form of `install`.
+
+| Coding agent | User instruction file |
+| --- | --- |
+| Codex | `~/.codex/AGENTS.md` (or under `CODEX_HOME`); also updates a nonempty `AGENTS.override.md` because it takes precedence |
+| Claude Code | `~/.claude/CLAUDE.md` (or under `CLAUDE_CONFIG_DIR`) |
+| Cursor | `~/.cursor/rules/preman-qa.mdc`, with `alwaysApply: true` |
+
+These are user-level files, not repository instructions. Codex uses the global
+`AGENTS.md` for its [personal instructions](https://learn.chatgpt.com/docs/personalize#add-custom-instructions).
+Claude Code loads [user memory](https://code.claude.com/docs/en/memory) across
+projects. Cursor's [local user rule files](https://prod.cursor.com/help/customization/rules#where-are-rules-stored)
+apply on this machine; they do not change its account-synced User Rules setting.
+
+Existing instructions are preserved outside a marked PreMan section. Rerunning
+onboarding updates that section without duplicates. An existing Cursor file
+that is not a PreMan-managed, always-on rule is preserved and reported as a
+conflict. Errors for one file do not prevent setup for the other agents.
+Onboarding prints each installed path and any manual follow-up needed. Start
+a new coding-agent session afterward to load the instructions.
+
+Use `--agent codex`, `--agent claude-code`, or `--agent cursor` to target just
+one agent, even before it is installed. Use `--no-agent-instructions` to skip
+this step. If no supported agents are detected, onboarding reports the skip.
+
+The installed guidance supplies
+`npm exec -y premanmcp@latest -- chat -p "<QA objective, target, and acceptance criteria>"`
+and tells the coding agent to follow the actual run to completion, report
+results and coverage gaps, explain unavailable targets, and respect the user's
+scope and approvals. Installing instructions does not itself run QA or prove
+that an agent followed them.
+
 ## The `preman` terminal session
 
 Installed globally, a bare `preman` opens an interactive session with the PreMan
@@ -83,12 +404,24 @@ account, backend, and workspace:
 /swarm stop <run-id>
 ```
 
-`/swarm help` lists every option. Add `--dry-run` to preview a launch without
-starting attempts. Ctrl+C while watching returns to the conversation and leaves
+Launch follows automatically, showing queue and running counts, live tool
+actions, and the final result. `/swarm help` lists every option. Add `--dry-run`
+to preview a launch without starting attempts, or `--no-watch` to return
+immediately. `--json` returns one JSON response. Ctrl+C while watching returns to the conversation and leaves
 the swarm running; `/swarm stop <run-id>` cancels it explicitly. The same commands
 work outside a session as `preman swarm list|launch|watch|stop|bank`. These run
 real agents against hosted MCPs; the app's sample swarms remain a separate demo.
 
+Headless callers can choose the existing matrix settings with `--visibility
+resident` (or `deferred`, or both comma-separated), repeat `--model <name>` to
+compare explicit models, and set `--budget <USD>`. The matrix budget stops new
+cells when priced spend plus in-flight reservations reaches the limit; it cannot
+cap provider usage whose cost is unknown. Use a provider-enforced allowance for
+a strict spending ceiling. `launch --json --no-watch`, `watch <id> --json`, and
+`list --json` return result links. Watch JSON also includes the individual cells
+and their evidence; process completion and tool-selection scores do not establish
+a verified QA pass.
+
 A session takes a screen of its own, the way `vim` does: nothing above it is
 scrollable, and leaving hands your shell back exactly as it was with one line
 saying how to resume. Ctrl+C stops the current turn (PreMan keeps working on it)

package/bin/agent.js

@@ -2086,7 +2086,7 @@ export async function runSwarm(rest, { args, token, workspaceId, say, paint, reg
     }
     await swarmCommand(argv, {
       sessionArgs: args, token, workspaceId, signal: controller.signal,
-      write: say, clearWatch: false,
+      write: say,
     });
     say("\n");
   } catch (error) {

package/bin/cli.js

@@ -51,6 +51,9 @@ import {
 } from "./desktop.js";
 import { ACCOUNT_HELP, doctorCommand, loginBrowser, logoutCommand, watchCommand } from "./account.js";
 import { AGENT_HELP, agentCommand } from "./agent.js";
+import { TASK_HELP, taskHelpRequested, taskCommand, artifactCommand, capabilitiesCommand, machineDoctorCommand, snapshotCommand, patchCommand, actionCommand, localCommand } from "./tasks.js";
+import { publicError } from "./task_client.js";
+import { HARNESS_HELP, harnessCommand } from "./harness.js";
 import {
   CREDENTIALS_FILE,
   cliInvocation,
@@ -105,6 +108,8 @@ const leadingFlag = Boolean(args[0]) && args[0].startsWith("-");
 // Only the first two positions, because `run` and `dispatch` forward arguments
 // to a tool and one of those may legitimately be asking that tool for help.
 const wantsHelp = args.slice(0, 2).some((arg) => arg === "--help" || arg === "-h");
+const wantsTaskHelp = ["task", "artifact", "artifacts", "snapshot", "patch", "action", "local", "capabilities", "doctor"].includes(args[0])
+  && taskHelpRequested(args.slice(1));
 // Leading position only, unlike help: `update --version 1.1.9` is how somebody
 // pins a version to install, so reading `--version` anywhere would answer that
 // with a number and never run the update. Asking a CLI its version is also the
@@ -142,6 +147,10 @@ function printHelp() {
   const usage = [
     ["", "Chat with the PreMan agent in this terminal"],
     ["chat [message] [--continue]", "The same session, named explicitly"],
+    ["task prepare|start|get|wait|watch|reply|cancel|retest|result", "Delegate durable QA with JSON results"],
+    ["capabilities --json | doctor --json", "Discover modes and machine readiness"],
+    ["artifacts get | snapshot create | patch apply", "Fetch evidence and exchange source/patches"],
+    ["harness status|install|remove", "Manage installed coding-agent integrations"],
     ["status", "Healthy / failing / recently fixed endpoints"],
     ["swarm list|launch|watch|stop|bank", "Send real coding agents to see if they pick your MCP tools"],
     ["verify [options]", "Test endpoints against your local app"],
@@ -180,7 +189,7 @@ function printHelp() {
 
 Usage:
 ${usageLines}
-${AGENT_HELP}${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${SWARM_HELP}${VERIFY_HELP}${PROBE_HELP}${HOOK_HELP}${RUNNER_HELP}${EVAL_HELP}${TARGET_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${PREDICT_HELP}${ENDPOINTS_HELP}${TEST_HELP}${TESTS_HELP}
+${TASK_HELP}${HARNESS_HELP}${AGENT_HELP}${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${SWARM_HELP}${VERIFY_HELP}${PROBE_HELP}${HOOK_HELP}${RUNNER_HELP}${EVAL_HELP}${TARGET_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${PREDICT_HELP}${ENDPOINTS_HELP}${TEST_HELP}${TESTS_HELP}
 Login options:
   --email <email>       Pre-fill the email prompt
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
@@ -362,13 +371,36 @@ function startServer() {
 }
 
 async function main() {
+  // Scoped help must precede hook repair, credentials, source capture and any
+  // executor or network activity, including help on nested operations.
+  if (wantsTaskHelp) {
+    process.stdout.write(TASK_HELP);
+    return;
+  }
   // Running at all is the signal. `hook` and `verify` own the hook themselves,
   // and connect reinstalls it in the foreground, so a background rewrite there
-  // would only race with the one the user is watching.
-  if (!["hook", "verify", "connect"].includes(command)) scheduleHookRepair();
+  // would only race with the one the user is watching. Informational commands
+  // and MCP startup must remain free of background hook changes.
+  if (!["help", "version", "start", "hook", "verify", "connect", "task", "artifact", "artifacts", "snapshot", "patch", "action", "local", "capabilities", "harness"].includes(command) && !(command === "doctor" && commandArgs.includes("--json"))) scheduleHookRepair();
 
   if (command === "version") {
     process.stdout.write(`${packageVersion() || "unknown"}\n`);
+  } else if (command === "task") {
+    process.exitCode = await taskCommand(commandArgs);
+  } else if (command === "harness") {
+    process.exitCode = await harnessCommand(commandArgs);
+  } else if (["artifact", "artifacts"].includes(command)) {
+    process.exitCode = await artifactCommand(commandArgs);
+  } else if (command === "snapshot") {
+    process.exitCode = await snapshotCommand(commandArgs);
+  } else if (command === "patch") {
+    process.exitCode = await patchCommand(commandArgs);
+  } else if (command === "action") {
+    process.exitCode = await actionCommand(commandArgs);
+  } else if (command === "local") {
+    process.exitCode = await localCommand(commandArgs);
+  } else if (command === "capabilities") {
+    process.exitCode = await capabilitiesCommand(commandArgs);
   } else if (command === "agent" || command === "chat") {
     await agentCommand(commandArgs);
   } else if (command === "target") {
@@ -414,7 +446,8 @@ async function main() {
   } else if (command === "logout") {
     await logoutCommand();
   } else if (command === "doctor") {
-    await doctorCommand(commandArgs);
+    if (commandArgs.includes("--json")) process.exitCode = await machineDoctorCommand(commandArgs);
+    else await doctorCommand(commandArgs);
   } else if (command === "watch") {
     await watchCommand(commandArgs);
   } else if (command === "install-desktop") {
@@ -530,6 +563,11 @@ async function main() {
 }
 
 main().catch((error) => {
+  if (["task", "artifact", "artifacts", "snapshot", "patch", "action", "local", "capabilities", "harness"].includes(command) || (command === "doctor" && commandArgs.includes("--json"))) {
+    process.stdout.write(`${JSON.stringify(publicError(error))}\n`);
+    process.exitCode = error?.exitCode || 4;
+    return;
+  }
   const message = error instanceof Error ? error.message : String(error);
   process.stderr.write(`[preman] ${message}\n`);
   process.exit(error?.exitCode || 1);

package/bin/connect/checkin.js

@@ -9,13 +9,14 @@
 
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { callBackendJson, onPath } from "../shared.js";
+import { callBackendJson, cliInvocation, onPath } from "../shared.js";
 
 import { findAgent } from "./agents.js";
 import { shellQuote } from "./configs.js";
 
 const MCP_CONNECT_SOURCES = new Set([
   "mcp",
+  // Historical pairing receipts remain valid; this is never invoked as a tool.
   "preman_status",
   "premanmcp",
   "agent",
@@ -102,10 +103,9 @@ export function pollTicker() {
 /**
  * How to ask each agent to make one PreMan call without opening its UI.
  *
- * The link is established by the agent's first call, so anything that reaches
- * `preman_status` finishes the connect. Claude Code needs the server on its
- * allow-list because print mode refuses un-allowed MCP tools rather than
- * prompting.
+ * Retained for callers that explicitly open an agent session. Connection
+ * verification itself uses MCP discovery and the terminal's pairing heartbeat,
+ * without starting an agent or a QA conversation.
  */
 export function headlessCheckIn(agent, serverName) {
   const prompt = checkInPrompt(serverName);
@@ -123,7 +123,8 @@ export function headlessCheckIn(agent, serverName) {
 }
 
 function checkInPrompt(serverName) {
-  return `Call the ${serverName} MCP tool preman_status and report the result.`;
+  const cli = cliInvocation();
+  return `Run ${cli} doctor --json and ${cli} capabilities --json, then report PreMan readiness and any blockers. The configured MCP server is ${serverName}. Do not start QA or a chat merely to verify the connection.`;
 }
 
 /**
@@ -365,7 +366,7 @@ export function selfTestBudgetMs() {
 }
 
 /**
- * Run the config we just wrote, exactly as the agent will, and call one tool.
+ * Run the config we just wrote, exactly as the agent will, and discover tools.
  *
  * This is both the fastest way to finish the link and the only check that proves
  * the whole chain — launcher, package, key, backend — rather than proving the
@@ -374,7 +375,9 @@ export function selfTestBudgetMs() {
  * redirect the server to a backend the key was never issued for, and every
  * symptom of that points at the key.
  *
- * Speaks the two JSON-RPC calls an MCP client makes on startup. Never throws.
+ * Speaks the two JSON-RPC requests an MCP client makes on startup. No tool is
+ * called: discovery verifies the authenticated transport without model usage.
+ * Pairing is separately established by the terminal heartbeat. Never throws.
  */
 export async function mcpSelfTest(
   serverConfig,
@@ -468,24 +471,41 @@ export async function mcpSelfTest(
           continue;
         }
         if (message.id === 1) {
+          if (message.error || !message.result?.protocolVersion) {
+            finish({ ok: false, reason: message.error?.message || "the MCP server returned an invalid initialization response" });
+            continue;
+          }
           send({ jsonrpc: "2.0", method: "notifications/initialized" });
           send({
             jsonrpc: "2.0",
             id: 2,
-            method: "tools/call",
-            params: { name: "preman_status", arguments: {} },
+            method: "tools/list",
+            params: {},
           });
           continue;
         }
         if (message.id !== 2) continue;
-        const text = message.result?.content?.[0]?.text;
-        let status = {};
-        try {
-          status = text ? JSON.parse(text) : {};
-        } catch {
-          status = { raw: text };
+        if (message.error) {
+          finish({ ok: false, reason: message.error.message || "MCP tool discovery failed" });
+          continue;
         }
-        finish({ ok: !message.error, status, reason: message.error?.message || "" });
+        const expected = ["preman_chat", "preman_confirm_action", "preman_get_turn", "preman_cancel_turn"].sort();
+        const names = Array.isArray(message.result?.tools)
+          ? message.result.tools.map((tool) => tool?.name).sort()
+          : [];
+        if (JSON.stringify(names) !== JSON.stringify(expected) || message.result?.nextCursor) {
+          finish({ ok: false, reason: "the MCP server did not expose the four supported PreMan tools; update PreMan and check the configured backend" });
+          continue;
+        }
+        finish({
+          ok: true,
+          status: {
+            authenticated: true,
+            backend_url: serverConfig.env?.PREMAN_BACKEND || "",
+            tools: names,
+          },
+          reason: "",
+        });
       }
     });
 
@@ -494,7 +514,7 @@ export async function mcpSelfTest(
       id: 1,
       method: "initialize",
       params: {
-        protocolVersion: "2024-11-05",
+        protocolVersion: "2025-06-18",
         capabilities: {},
         clientInfo: { name: "preman-connect-selftest", version: "1" },
       },

package/bin/connect/guide.js

@@ -40,9 +40,10 @@ function manualSteps() {
 }
 
 export function nextStepsBlock(agent) {
+  const cli = cliInvocation();
   return (
     "\nNext steps:\n" +
-    `  1. Restart ${agent.label}, then ask it: "run preman_status" to finish linking.\n` +
+    `  1. Restart ${agent.label}, then ask it to run "${cli} doctor --json" and "${cli} capabilities --json" to check readiness.\n` +
     `  2. ${cliInvocation()} runner start --background   # let PreMan run work here\n` +
     `  3. ${cliInvocation()} endpoints discover          # map this repo's endpoints\n` +
     `  4. ${cliInvocation()} hook install                # test affected endpoints on git push\n`