premanmcp 0.9.0 → 0.10.1

package/README.md

@@ -42,19 +42,39 @@ Claude Code's MCP config, or `~/.codex/config.toml`):
 ```
 
 `connect` reads the config back after writing it, and prints a copy-paste snippet if it
-cannot confirm the entry landed. It then finishes the link itself by running your agent
-headlessly (`claude -p`, `cursor-agent -p`, `codex exec`) so it makes one PreMan call —
-that check-in is the only real proof the agent loaded the server. If the agent's CLI is
-not on PATH, `connect` asks you to restart it and waits instead. `--no-auto-checkin`
-turns the spawn off.
-
-Once the agent has checked in, `connect` walks you into your first test: it runs one
-against an endpoint you already have, or prints the discovery brief to hand your agent,
-followed by `preman endpoints setup` and `preman test`. Pass `--no-guide` to skip it.
+cannot confirm the entry landed. Then it finishes the link itself rather than asking you
+to go restart anything, in cheapest-first order:
+
+1. **Self-test.** It starts the MCP server exactly as your agent will and calls
+   `preman_status` over stdio. That both completes the link and proves the whole chain —
+   launcher, package, key, backend. `--no-self-test` turns it off.
+2. **Headless agent run** (`claude -p`, `cursor-agent -p`, `codex exec`), which also
+   proves your agent can load what was written. `--no-auto-checkin` turns it off.
+3. **Wait**, if neither is possible: restart your agent and it links on its first call.
+
+A self-test that answers from an unexpected backend is reported with the file that
+redirected it — a repo-local `preman-mcp.config.json` with `"PREMAN_CONFIG_OVERRIDE": true`
+wins over the MCP config env, and otherwise only fills in what the env leaves unset.
+
+Once linked, `connect` finishes onboarding without handing you homework:
+
+| Step | What happens |
+|------|--------------|
+| Endpoints | Runs your agent on the discovery brief, then reports `N endpoints · M runnable` |
+| First test | Generates and runs scenarios against the first runnable request |
+| Runner | Pairs this machine and starts `preman runner` in the background, so PreMan can apply fixes here instead of only describing them |
+| Desktop app | Offers the macOS app for watching runs and endpoints |
+| Integrations | Shows GitHub / AWS / Slack, opens what is missing, and picks the connection up when you finish in the browser or the desktop app |
+| Testing on push | Installs the git pre-push hook, so `git push` checks the endpoints you touched |
 
 Useful flags: `--agent cursor|claude-code|codex` skips the picker, `--project` writes
-project-local config, `--print` shows the config without writing it, `--no-guide` skips
-the guided first run.
+project-local config, `--print` shows the config without writing it, `--yes` takes every
+step's default without asking, `--no-guide` skips all of them, and `--no-runner` /
+`--no-desktop` / `--no-integrations` / `--no-hook` skip one each.
+
+`--yes` deliberately does *not* install the desktop app: that step's default is no, because
+it downloads a hundred-odd megabytes and writes to `/Applications`. Run `install-desktop`
+when you want it.
 
 In CI or any non-interactive shell, run `connect --agent <name> --api-key pm_live_…`.
 Without `--agent` there is nothing to prompt on, so `connect` prints ready-to-paste
@@ -190,6 +210,24 @@ npm exec -y premanmcp@latest -- login   # Create/login and generate a PreMan API
 npm exec -y premanmcp@latest -- install # Cursor-only installer (legacy)
 ```
 
+### Runner
+
+`connect` sets this up for you; these are for managing it afterwards.
+
+```bash
+preman runner status              # Paired? Running?
+preman runner start --background  # Hold the job stream, log to ~/.preman/runner.log
+preman runner stop                # Stop it and report offline
+preman runner register --agent claude-code   # Re-pair (e.g. a different project)
+```
+
+The runner holds one outbound connection to PreMan and runs the work PreMan queues for
+this machine — a failing endpoint becomes an agent run in your own repo instead of a
+prompt you have to paste. It is bound to the agent and directory it was registered with
+and refuses any job that names a different one. The agent may edit files; running commands
+needs `--full-access` (or `PREMAN_RUNNER_FULL_ACCESS=1`). Nothing runs until PreMan has
+something to fix, and `preman runner stop` ends it.
+
 Options:
 
 - `--api-key <key>`: PreMan API key.

package/bin/account.js

@@ -178,7 +178,7 @@ export async function watchCommand(commandArgs = []) {
   const integrationId = args.value("--integration", positional[1] || "");
   if (!runId || !integrationId) {
     throw new Error(
-      "usage: watch <run-id> <integration-id>  (both are shown by `preman status`)"
+      `usage: watch <run-id> <integration-id>  (both are shown by \`${cliInvocation()} status\`)`
     );
   }
 

package/bin/api_tools.js

@@ -45,7 +45,7 @@ export async function callTool(args, tool, toolArguments) {
   const token = resolveApiKey(args);
   if (!token) {
     throw new CliError(
-      "No PreMan API key. Run `preman login` or pass --api-key pm_live_...",
+      `No PreMan API key. Run \`${cliInvocation()} login\` or pass --api-key pm_live_...`,
       2,
     );
   }
@@ -110,7 +110,7 @@ export async function endpointsCommand(commandArgs) {
     if (args.has("--json-out")) return printJson(result);
     for (const line of result.instructions || []) process.stdout.write(`${line}\n`);
     process.stdout.write(
-      "\nHand this brief to your coding agent, then run `preman endpoints setup --file endpoints.json`.\n",
+      `\nHand this brief to your coding agent, then run \`${cliInvocation()} endpoints setup --file endpoints.json\`.\n`,
     );
     return undefined;
   }

package/bin/cli.js

@@ -34,6 +34,7 @@ import {
 import { HOSTED_HELP, linkCommand, runCommand, toolsCommand } from "./hosted.js";
 import { STATUS_HELP, statusCommand } from "./status.js";
 import { HOOK_HELP, hookCommand } from "./hook.js";
+import { RUNNER_HELP, runnerCommand } from "./runner.js";
 import { VERIFY_HELP, verifyCommand } from "./verify.js";
 import { DESKTOP_HELP, installDesktopCommand } from "./desktop.js";
 import { ACCOUNT_HELP, doctorCommand, loginBrowser, logoutCommand, watchCommand } from "./account.js";
@@ -80,6 +81,7 @@ function printHelp() {
     ["status", "Healthy / failing / recently fixed endpoints"],
     ["verify [options]", "Test endpoints against your local app"],
     ["hook install|uninstall|status", "Manage the git pre-push hook"],
+    ["runner start|status|stop", "Run PreMan's queued agent work on this machine"],
     ["doctor", "Diagnose credentials, backend, target, integrations"],
     ["install-desktop", "Download and install the PreMan desktop app"],
     ["onboard", "Sign in, then connect agent, GitHub, AWS, Slack"],
@@ -104,7 +106,7 @@ function printHelp() {
 
 Usage:
 ${usageLines}
-${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${VERIFY_HELP}${HOOK_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${ENDPOINTS_HELP}${TEST_HELP}
+${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${VERIFY_HELP}${HOOK_HELP}${RUNNER_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${ENDPOINTS_HELP}${TEST_HELP}
 Login options:
   --email <email>       Pre-fill the email prompt
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
@@ -221,6 +223,8 @@ async function main() {
     await verifyCommand(commandArgs);
   } else if (command === "hook") {
     await hookCommand(commandArgs);
+  } else if (command === "runner") {
+    await runnerCommand(commandArgs);
   } else if (command === "logout") {
     await logoutCommand();
   } else if (command === "doctor") {