premanmcp 1.1.18 → 1.1.20

package/bin/connect/instructions.js

@@ -0,0 +1,254 @@
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import {
+  accessSync, chmodSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync,
+  renameSync, rmSync, statSync, writeFileSync,
+} from "node:fs";
+import { AGENTS, detectAgents, findAgent } from "./agents.js";
+import { onPath, cliInvocation } from "../shared.js";
+
+const START = "<!-- preman:qa-instructions:start -->";
+const END = "<!-- preman:qa-instructions:end -->";
+
+export function agentInstructions(invocation = cliInvocation()) { return `## QA with PreMan
+
+For every QA task, use the PreMan CLI agent. This includes agent evaluations,
+compatibility across multiple agents, user simulations when useful, full-stack
+API-to-frontend testing, backend testing, and frontend QA. Proactively involve
+PreMan when a task needs this validation; do not wait for the user to name it.
+
+Discover modes with \`${invocation} capabilities --json\` and readiness with
+\`${invocation} doctor --json\`. For working-tree testing, prepare the complete
+delegation before starting it. Read existing context supplied by the caller and
+preserve its saved resources, executor, target, permitted paths, and budgets.
+Bind the actual workspace ID explicitly; a prompt mentioning an environment
+variable does not pass its value to PreMan. Do not select a different workspace
+just because capabilities lists it first.
+
+CLI example (replace placeholders with known values and use a temporary path
+outside the source tree for prepared.json):
+\`\`\`sh
+${invocation} task prepare --workspace "<workspace-id>" --context-json "<context.json>" --repo "<repo-directory>" --repair none --idempotency-key "<stable-key>" -p "<QA objective and acceptance criteria>" --output "<prepared.json>" --json
+${invocation} task start --prepared "<prepared.json>" --json
+${invocation} task wait "<task-id>" --timeout 120 --json
+\`\`\`
+Preparation captures and uploads a bounded source snapshot but does not start
+tests. Continue only when status is ready. If status is needs_input, correct the
+listed issues or answer the workspace choice, then prepare again. When asking
+PreMan to produce an authorized repair, use --repair patch; this permits an
+isolated patch but does not apply or publish it. For PreMan testing followed by
+an isolated repair if needed, use --repair patch --intent test on the initial
+preparation. Preman first runs the
+selected checks and starts repair only if those checks fail.
+
+If an existing checks-only task has a verified failing QA result and PreMan is now
+asked to repair it, prepare a linked repair using its task ID and the same saved context.
+Finish the baseline first; awaiting_approval, queued, and unknown are not failures:
+\`\`\`sh
+${invocation} task prepare --workspace "<workspace-id>" --context-json "<context.json>" --repo "<repo-directory>" --retest-of "<failing-task-id>" --repair patch --intent repair --idempotency-key "<new-stable-repair-key>" -p "Repair the verified failures and verify against the same saved checks" --output "<repair-prepared.json>" --json
+${invocation} task start --prepared "<repair-prepared.json>" --json
+\`\`\`
+The --retest-of link binds repair to the original task's saved expectations and
+keeps failure-to-repair history intact. For MCP, submit that preparation's
+mcp.arguments unchanged; it carries the same link. task start --prepared reuses the validated workspace/context
+and snapshot without uploading it again. Read scoped command help before choosing
+flags; the older \`${invocation} test\` command is not working-tree delegation.
+
+MCP example: execute the same task prepare command in the calling agent's shell
+or terminal, then read the prepared JSON file. Call the tool named in
+prepared.mcp.tool (preman_chat) with prepared.mcp.arguments unchanged. Never paste
+a CLI command into preman_chat.message or rebuild the typed arguments by guessing.
+Those arguments contain workspace_id and delegation with operation=start, schema_version,
+context, and repair_policy. A plain preman_chat({message: ...}) starts legacy chat,
+not a delegated QA task. Poll the returned anchor_turn_id with:
+\`\`\`json
+{"turn_id":"<anchor_turn_id>","task_view":{},"wait_seconds":20}
+\`\`\`
+using preman_get_turn. Keep the task ID and anchor turn ID distinct. A missing
+context response is recoverable: complete the named fields and resubmit the
+prepared arguments. Hosted MCP cannot capture the caller's local files itself.
+
+Use task wait/watch/get and task reply for the returned task ID; use
+--execute-local only when this caller is the selected local executor. When a
+separate registered executor owns the work, ordinary wait/poll is sufficient.
+When awaiting_approval is returned, inspect every pending item in proposals.
+For each stored proposal whose exact scope the user has already approved, use
+\`${invocation} action confirm <proposal-id> --json\` or MCP preman_confirm_action.
+One confirmation does not approve the whole task: confirm each authorized proposal
+and continue polling until execution finishes or a new question needs an answer.
+There is no task --approve flag. Ask the user about proposals outside their approval.
+Check the typed QA verdict, verified flag, actual results, evidence, and coverage gaps.
+Fetch artifacts to local files and display their images; retain native and web links.
+Before repairing a failure, obtain the failing check and run IDs, tested source or
+build, reproduction inputs, expected versus actual behavior, and supporting
+evidence. Use task result and artifacts get to inspect the saved findings. If
+those details are incomplete, ask PreMan for the missing diagnostics through
+task message (or continue the MCP task); do not guess the cause from a verdict.
+The calling agent may repair the code itself using these findings, or request a
+PreMan patch when authorized. Accepting PreMan's proposed patch is optional unless
+the user explicitly requires that handoff. After either kind of fix, run task
+retest against the updated repository using the original task ID and saved
+expectations. Report the fix as verified only when that new-source retest passes.
+PreMan records genuine missing QA capabilities as feature requests. Include returned
+feature_requests receipts and their links when reporting unsupported coverage. If a
+gap has no receipt, continue the task with its missing capability and ask PreMan to
+record it; never claim feedback was saved without a recorded receipt. Setup, access,
+budget, and transient failures remain blockers rather than feature requests.
+Fetch the repair artifact with \`${invocation} artifacts get <task-id> <artifact-id> --output <artifact.json> --json\`.
+Apply that fetched file directly with \`${invocation} patch apply --file <artifact.json> --repo <repo-directory> --json\`
+only when patch application is authorized; patch apply accepts the repair artifact
+envelope and verifies its manifest. After application,
+\`${invocation} task retest <task-id> --repo <repo-directory> --json\` captures the
+resulting tree and reuses saved expectations. For MCP, prepare the updated source
+and use delegation.operation=retest with task_id and the prepared context.
+The original failure, verified candidate patch, and applied-tree retest are
+separate results; report each truthfully.
+When the requested handoff is a returned PreMan patch, a direct edit by the calling
+agent does not satisfy that handoff. Identify who made the fix and which source
+and checks were actually verified.
+For conversational help, use \`${invocation} chat -p "<question>"\`.
+A completed chat alone does not mean the tests passed. If PreMan
+is unavailable or cannot reach the target, explain the blocker and any fallback
+checks. Follow the user's scope, permissions, and approval requirements. Never
+confirm a stored risky-action proposal without the user's exact approval.`; }
+export const QA_INSTRUCTIONS = agentInstructions("npm exec -y premanmcp@latest --");
+
+function readOptional(file) {
+  try {
+    return readFileSync(file, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return "";
+  }
+}
+
+function mergeInstructions(existing, invocation) {
+  const eol = existing.includes("\r\n") ? "\r\n" : "\n";
+  const block = `${START}\n${agentInstructions(invocation)}\n${END}`.replaceAll("\n", eol);
+  const starts = existing.split(START).length - 1;
+  const ends = existing.split(END).length - 1;
+  if (!starts && !ends) {
+    const separator = !existing || existing.endsWith(eol + eol) ? "" : existing.endsWith(eol) ? eol : eol + eol;
+    return `${existing}${separator}${block}${eol}`;
+  }
+  const start = existing.indexOf(START);
+  const end = existing.indexOf(END);
+  if (starts !== 1 || ends !== 1 || end < start) {
+    throw new Error("The PreMan instruction markers are incomplete or duplicated; repair that section and rerun onboarding.");
+  }
+  return existing.slice(0, start) + block + existing.slice(end + END.length);
+}
+
+function writeInstructions(file, { cursor = false, optional = false, invocation } = {}) {
+  const existing = readOptional(file);
+  // An empty override is ignored by Codex. Creating one would hide the base file.
+  if (optional && !existing.trim()) return null;
+  let source = existing;
+  if (cursor) {
+    if (!existing) {
+      source = "---\ndescription: Use the PreMan CLI agent for QA tasks\nalwaysApply: true\n---\n";
+    } else {
+      const header = existing.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+      if (!existing.includes(START) || !/^alwaysApply:\s*true\s*$/m.test(header || "")) {
+        throw new Error("The existing Cursor rule is not an always-on PreMan-managed rule; rename the existing rule before rerunning onboarding.");
+      }
+    }
+  }
+  const next = mergeInstructions(source, invocation);
+  if (next === existing) return "already installed";
+
+  // Write beside the real destination, then replace it atomically. Dotfile
+  // symlinks stay intact, and an interrupted write cannot truncate user text.
+  let destination = file;
+  let mode = 0o600;
+  try {
+    lstatSync(file);
+    destination = realpathSync(file);
+    accessSync(destination, constants.W_OK);
+    mode = statSync(destination).mode & 0o777;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    // A dangling symlink is a configuration problem, not a file to replace.
+    try {
+      if (lstatSync(file).isSymbolicLink()) throw new Error(`Instruction file is a dangling symlink: ${file}`);
+    } catch (linkError) {
+      if (linkError.code !== "ENOENT") throw linkError;
+    }
+  }
+  mkdirSync(path.dirname(destination), { recursive: true });
+  const temporary = `${destination}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, next, { encoding: "utf8", mode, flag: "wx" });
+    chmodSync(temporary, mode);
+    renameSync(temporary, destination);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+  return "installed";
+}
+
+function instructionFiles(agent, home = os.homedir()) {
+  if (agent.id === "codex") {
+    const directory = process.env.CODEX_HOME || path.join(home, ".codex");
+    return [
+      { file: path.join(directory, "AGENTS.md") },
+      { file: path.join(directory, "AGENTS.override.md"), optional: true },
+    ];
+  }
+  if (agent.id === "claude_code") {
+    return [{ file: path.join(process.env.CLAUDE_CONFIG_DIR || path.join(home, ".claude"), "CLAUDE.md") }];
+  }
+  return [{ file: path.join(home, ".cursor", "rules", "preman-qa.mdc"), cursor: true }];
+}
+export function managedInstructionFiles(agentId, home = os.homedir()) {
+  const agent = findAgent(agentId);
+  return agent ? instructionFiles(agent, home).map((entry) => entry.file) : [];
+}
+
+export function validateInstructionAgent(args) {
+  const requested = args.value("--agent", "");
+  if (requested && !findAgent(requested)) {
+    throw new Error(`Unknown agent: ${requested}. Use cursor, claude-code, or codex.`);
+  }
+}
+
+export function installAgentInstructions(args, { quiet = false, invocation = cliInvocation(), homedir = os.homedir() } = {}) {
+  const write = (text) => { if (!quiet) process.stdout.write(text); };
+  if (args.has("--no-agent-instructions")) {
+    write("Skipped coding-agent QA instructions (--no-agent-instructions).\n");
+    return { state: "skipped", detail: "disabled with --no-agent-instructions" };
+  }
+  validateInstructionAgent(args);
+  const requested = findAgent(args.value("--agent", ""));
+  const detected = detectAgents();
+  detected.cursor ||= onPath("cursor-agent");
+  detected.claude_code ||= existsSync(process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude"));
+  const agents = requested ? [requested] : AGENTS.filter((agent) => detected[agent.id]);
+  if (!agents.length) {
+    write("No supported coding agents detected. Rerun onboard with --agent cursor, claude-code, or codex to install QA instructions.\n");
+    return { state: "skipped", detail: "no supported coding agents detected" };
+  }
+
+  let installed = 0;
+  let failed = 0;
+  for (const agent of agents) {
+    for (const { file, ...options } of instructionFiles(agent, homedir)) {
+      try {
+        const action = writeInstructions(file, { ...options, invocation });
+        if (!action) continue;
+        installed += 1;
+        write(`${agent.label} QA instructions ${action}: ${file}\n`);
+      } catch (error) {
+        failed += 1;
+        write(`Could not install ${agent.label} QA instructions in ${file}: ${error.message}\n`);
+      }
+    }
+  }
+  if (installed) write("Start a new coding-agent session to load the PreMan QA instructions.\n");
+  if (failed) {
+    write(`Add this guidance to the affected agent's personal instructions manually:\n\n${agentInstructions(invocation)}\n\n`);
+    return { state: "failed", detail: `${failed} instruction file(s) could not be updated; ${installed} installed` };
+  }
+  return { state: "done" };
+}

package/bin/connect/pairing.js

@@ -73,8 +73,13 @@ export async function redeemPairCode(args, agent, apiKey, pairCode) {
   });
   if (!result.ok) {
     process.stdout.write(`Note: could not close the link (${result.status_code}).\n`);
+    return false;
   }
-  return Boolean(result.ok);
+  const connected = result.connected === true && result.status === "connected";
+  if (!connected) {
+    process.stdout.write("Note: the pairing heartbeat has not confirmed a connection yet.\n");
+  }
+  return connected;
 }
 
 /** Whichever of the two ways to learn the backend still accepts this key. */

package/bin/connect.js

@@ -37,7 +37,6 @@ import { MARK } from "./integrations.js";
 import { describeCheckout, resolveCheckout } from "./repo.js";
 import { ConnectError, EXIT_USAGE } from "./connect/errors.js";
 import {
-  agentBlocker,
   detectAgents,
   findAgent,
   promptAgentChoice,
@@ -51,8 +50,6 @@ import {
 } from "./connect/configs.js";
 import { checkKeyAndPair, redeemPairCode, refreshStaleCredentials } from "./connect/pairing.js";
 import {
-  autoCheckIn,
-  lastLine,
   mcpSelfTest,
   pollTicker,
   selfTestBudgetMs,
@@ -87,7 +84,7 @@ export async function preflight(args) {
     );
   }
 
-  if (!onPath("npx")) {
+  if (!(process.env.PREMAN_CLI_EXECUTABLE && existsSync(process.env.PREMAN_CLI_EXECUTABLE)) && !onPath("npx")) {
     notes.push(
       "npx was not found on PATH; the written config launches PreMan via npx, so make sure your agent's environment has it."
     );
@@ -137,9 +134,9 @@ Connect options:
   --skip-dispatch-credential  Do not ask for a cloud-dispatch credential
   --skip-login                Write config without interactive terminal auth
   --no-pair                   Do not mint a pair code
-  --no-self-test              Do not start the MCP server to finish the link
-  --no-auto-checkin           Do not run the agent to finish the link
-  --no-wait                   Do not wait for the agent to check in
+  --no-self-test              Skip MCP initialization and tool-discovery verification
+  --no-auto-checkin           Compatibility option; connection checks never run an agent
+  --no-wait                   Write config and redeem pairing without waiting or self-testing
   --guide                     Also run discovery, the runner, the desktop app
                               and the integration prompts after connecting
   --no-guide                  Connect only: no push hook, no closing summary
@@ -172,7 +169,7 @@ export async function connectCommand(commandArgs) {
   if (!agent && !interactive) {
     process.stdout.write(
       `preman connect needs a terminal to pick an agent. Copy-paste setup instead:\n\n${renderAllAgentSnippets(args, serverName, { projectInstall })}\n` +
-        'Then restart your agent and ask it: "run preman_status".\n' +
+        `Then restart your agent and ask it to run "${cliInvocation()} doctor --json" and "${cliInvocation()} capabilities --json".\n` +
         "Or rerun: preman connect --agent <cursor|claude-code|codex> --api-key pm_live_…\n"
     );
     throw new ConnectError(
@@ -326,24 +323,6 @@ export async function connectCommand(commandArgs) {
   return connected;
 }
 
-/**
- * A repo config that sends every agent started here to a backend the key we just
- * wrote was not issued for, or null.
- *
- * Only an override can do this: without the flag the MCP config's env wins, and
- * a self-test that disagrees with it is a transient, not a redirect. It matters
- * because it is the one failure waiting cannot fix — the agent starts in the
- * same directory, reads the same file, and checks in somewhere else forever.
- */
-function backendRedirect(repo, status, serverConfig) {
-  if (!repo?.override || !(repo.applied || []).includes("PREMAN_BACKEND")) return null;
-  const trim = (url) => String(url || "").replace(/\/+$/, "");
-  const actual = trim(status.backend_url);
-  const wanted = trim(serverConfig?.env?.PREMAN_BACKEND);
-  if (!actual || !wanted || actual === wanted) return null;
-  return { path: repo.path, actual, wanted };
-}
-
 /**
  * Somewhere to start the agent when this directory would redirect its backend.
  *
@@ -369,203 +348,42 @@ export function neutralCwd(candidates = [os.homedir(), os.tmpdir()]) {
 }
 
 /**
- * Finish the link here, by whatever means work, in cheapest-first order.
- *
- * 1. Run the MCP server ourselves and call one tool. No agent, no tokens, a few
- *    seconds, and it proves the launcher/key/backend chain the agent will use.
- * 2. Failing that, start the agent — in its own window when there is a desktop
- *    to open one on, headlessly otherwise — which also proves the agent can load
- *    the config we wrote.
- * 3. Failing that, ask them to restart it and wait, which is all this ever did.
- *
- * A directory whose repo config redirects the backend moves steps 1 and 2 out of
- * that directory rather than giving up in it: the config on disk is right, and
- * where the server and the agent stand is the only thing that has to change. Not
- * step 2 under `--project`, though — that config exists in that directory alone,
- * so an agent sent anywhere else would have no server to call.
- *
- * Every diagnosis is printed the moment it is known rather than saved for the
- * end: the steps below are measured in minutes, and a note that explains what is
- * happening is worth nothing after it has stopped happening.
- *
- * Returns whether the check-in landed and, when this directory redirects it, why
- * nothing started here can use PreMan — the caller has its own agent to run once
- * this is done. Prints the troubleshooting block itself when the link did not
- * land.
+ * Verify the configured MCP transport and the account pairing independently.
+ * Discovery never invokes a tool or starts a coding agent. The terminal's
+ * heartbeat, or an existing matching pairing receipt, establishes the link.
  */
 async function establishCheckIn(
   args,
   agent,
   apiKey,
-  { serverName, written, serverConfig, projectInstall = false, pairingId = "", preLinked = false }
+  { written, serverConfig, pairingId = "", preLinked = false }
 ) {
   const notes = [];
-  // Both set only when this directory redirects the agent: where it can be
-  // started instead, and why an agent left standing here cannot use PreMan at all.
-  let elsewhere = null;
-  let blockedHere = "";
-  const done = (linked) => ({ linked, blockedHere });
-  // Already linked by the terminal that wrote the config: nothing to self-test
-  // into, no window to open, and no check-in to wait for.
-  if (preLinked) return done(true);
+  const done = (linked) => ({ linked, blockedHere: "" });
+  let transportFailed = false;
   const ticker = pollTicker();
   const say = (text) => {
     ticker.end();
     process.stdout.write(text);
   };
-  const note = (text) => {
-    notes.push(text);
-    say(`Note: ${text}\n`);
-  };
 
+  // A successful heartbeat does not prove the installed MCP launcher works.
+  // Keep the explicit self-test opt-out, but otherwise verify both surfaces.
   if (!args.has("--no-self-test") && serverConfig && selfTestBudgetMs() > 0) {
     process.stdout.write("\nChecking the connection…\n");
     const test = await mcpSelfTest(serverConfig);
-    const status = test.status || {};
-    const repo = status.config?.repo_config;
-    if (repo?.override && repo.applied?.length) {
-      // The one failure that reads as a bad key: a working server talking to a
-      // backend nobody chose. Name the file before it costs anyone an hour.
-      note(
-        `${repo.path} overrides ${repo.applied.join(", ")} for anything started in this directory, ` +
-          `so your agent will use ${status.backend_url}.`
-      );
-    }
-    if (
-      test.ok &&
-      status.authenticated &&
-      (await waitForConnection(args, apiKey, {
-        timeoutMs: 15000,
-        expectedAgent: agent.id,
-        pairingId,
-      }))
-    ) {
-      return done(true);
-    }
-    note(
-      test.ok
-        ? `the MCP server answered from ${status.backend_url || "an unknown backend"} but was not authenticated`
-        : `the MCP server could not be started (${test.reason || "unknown"}${test.stderr ? `: ${test.stderr}` : ""})`
-    );
-
-    const redirect = backendRedirect(repo, status, serverConfig);
-    if (redirect) {
-      const flag = `--agent ${agent.id.replace("_", "-")}`;
-      const notLinked = (why) =>
-        say(
-          `\nNot linked: ${redirect.path} forces PREMAN_BACKEND=${redirect.actual} for anything\n` +
-            `started in this directory, so ${agent.label} cannot check in against ${redirect.wanted}.\n` +
-            `  - ${why}\n` +
-            `  - Or connect to that backend: ${cliInvocation()} connect ${flag} --backend ${redirect.actual}\n` +
-            `    (needs a key issued by it, and that API running).\n` +
-            `  - Config written to: ${written.path}\n`
-        );
-      notes.push(
-        `start ${agent.label} from another project, or connect to the backend this ` +
-          `directory forces: ${cliInvocation()} connect ${flag} --backend ${redirect.actual} ` +
-          `(needs a key issued by it, and that API running).`
-      );
-      // Linking is not the only thing this directory breaks: whatever runs here
-      // next gets the same redirected, unauthenticated server, and the callers
-      // that would start an agent in it need to hear so.
-      blockedHere =
-        `${redirect.path} sends ${agent.label} to ${redirect.actual} in this directory, ` +
-        `where this key is not valid.`;
-
-      // The config we wrote is correct; the directory around it is not. Since the
-      // server only reads the file it is standing in, everything this does next
-      // happens somewhere the override cannot reach.
-      const outside = neutralCwd();
-      if (!outside) {
-        notLinked(`Run '${cliInvocation()} connect' from your own project instead of this directory.`);
-        return done(false);
-      }
-
-      say(
-        (projectInstall
-          ? `\nThe key and backend written are right: ${redirect.path}\n` +
-            `only redirects what starts in this directory. `
-          : `\nThe config is written and works anywhere else: ${redirect.path}\n` +
-            `only redirects agents started in this directory. `) +
-          `Trying again from\n${outside}, which is out of that file's reach.\n`
-      );
-      // Nothing was wrong with the self-test but where it stood, and a self-test
-      // is what completes the link — so re-run it before spending an agent window
-      // on the same question. This works under --project too: it runs the config
-      // in memory rather than loading it from disk.
-      const retry = await mcpSelfTest(serverConfig, { cwd: outside });
-      if (
-        retry.ok &&
-        retry.status?.authenticated &&
-        (await waitForConnection(args, apiKey, {
-          timeoutMs: 15000,
-          expectedAgent: agent.id,
-          pairingId,
-        }))
-      ) {
-        return done(true);
-      }
-
-      if (projectInstall) {
-        // --project put the server in this directory and nowhere else, so there
-        // is no config to load anywhere the override cannot reach, and no agent
-        // worth starting to look for one.
-        notLinked(
-          `This --project config exists only here; started anywhere else, ` +
-            `${agent.label} has no ${serverName} server to call.`
-        );
-        return done(false);
-      }
-      elsewhere = outside;
+    transportFailed = !test.ok;
+    if (transportFailed) {
+      const detail = `the MCP connection could not be verified (${test.reason || "unknown"}${test.stderr ? `: ${test.stderr}` : ""})`;
+      notes.push(detail);
+      say(`Note: ${detail}\n`);
     }
   }
 
-  const blocker = agentBlocker(agent.id);
-  let launch = {};
-  if (!args.has("--no-auto-checkin") && !blocker) {
-    launch = await autoCheckIn(args, agent, apiKey, {
-      serverName,
-      cwd: elsewhere || process.cwd(),
-      pairingId,
-      onPoll: ticker.tick,
-      onLaunch: ({ mode, terminal }) =>
-        say(
-          mode === "interactive"
-            ? `\nOpened a new ${terminal} window running ${agent.label}.\n`
-            : `\nStarting ${agent.label} to finish the link…\n`
-        ),
-    });
-    if (launch.connected) {
-      ticker.end();
-      return done(true);
-    }
-    if (launch.ran && !launch.interactive) {
-      const why = lastLine(launch.output);
-      say(`${agent.label} ran but did not check in${why ? `: ${why}` : "."}\n`);
-    } else if (!launch.ran && launch.reason) {
-      say(`Could not run ${agent.label}: ${launch.reason}\n`);
-    }
-  } else if (blocker) {
-    // Starting an agent that cannot authenticate spends two minutes to learn
-    // what one status probe already knows.
-    say(`${MARK.skip()} ${blocker}\n`);
-    notes.push(blocker);
-  }
-
-  say(
-    launch.interactive
-      ? `\nAnswer it in the ${agent.label} window — it links on its first PreMan call.\n` +
-          "Waiting for your agent to check in… (Ctrl+C to stop waiting)\n"
-      : // Restarting it here would read the same redirecting file again, so the
-        // one instruction that works is to start it somewhere else.
-        (elsewhere
-          ? `\nStart ${agent.label} in another project and ask it: "run preman_status"\n`
-          : `\nRestart ${agent.label} and ask it: "run preman_status"\n`) +
-          "Waiting for your agent to check in… (Ctrl+C to stop waiting)\n"
-  );
+  if (preLinked && !transportFailed) return done(true);
 
   if (
-    await waitForConnection(args, apiKey, {
+    !transportFailed && await waitForConnection(args, apiKey, {
       expectedAgent: agent.id,
       pairingId,
       onPoll: ticker.tick,
@@ -576,11 +394,11 @@ async function establishCheckIn(
   }
 
   say(
-    "No check-in yet. Troubleshooting:\n" +
+    "Connection verification is incomplete.\n" +
       notes.map((entry) => `  - ${entry}\n`).join("") +
       `  - ${agent.restartHint}\n` +
       `  - Config written to: ${written.path}\n` +
-      `  - Then ask ${agent.label} to "run preman_status" — it links on its first PreMan call.\n` +
+      `  - Ask ${agent.label} to run "${cliInvocation()} doctor --json" and "${cliInvocation()} capabilities --json" for readiness details.\n` +
       `  - Then: ${cliInvocation()} connect --agent ${agent.id.replace("_", "-")}\n`
   );
   return done(false);

package/bin/credentials.d.ts

@@ -0,0 +1,2 @@
+export type MachineCredential = { api_key: string; backend_url: string; user_id?: string | number; key_id?: string; scopes?: string[]; frontend_url?: string };
+export function readCredentials(options?: { homedir?: string; backend?: string; accountId?: string | number }): MachineCredential | null;