staysfixed 0.7.2 → 0.9.0

package/src/v2/doctor.js

@@ -36,9 +36,12 @@ import { findConfigFile, rootForConfig } from '../core/paths.js';
 import { platformTag } from '../drive/find.js';
 import { isRepo } from '../core/git.js';
 import { surveyBrowsers, INSTALL_COMMAND, PORT_NEVER_USE } from './browsers.js';
-import { POWERSHELL_PATHS } from './remote.js';
+import { POWERSHELL_PATHS, describeRemote } from './remote.js';
+import { deviceToMake } from './adapters/android.js';
+import { describeWindows } from './adapters/windows.js';
 import { messageOf, EXIT } from '../core/errors.js';
 import { say, ok, warn, fail, blank, heading, paint, mark, shortPath, setLogLevel } from '../core/log.js';
+import { loadPlaywright } from './adapters/web-driver.js';
 
 const exec = promisify(execFile);
 
@@ -90,6 +93,19 @@ export const CHANNELS = [
  * @property {string} [powershell]  The absolute path to powershell.exe that answered, when one did.
  *                                  Kept because it is the evidence: "there is Windows behind this
  *                                  host" is a claim, and this is the file that proves it.
+ * @property {import('./remote.js').RemoteDescription} [detail]
+ *   Everything the remote runner could learn about that machine once it was known to answer:
+ *   what is installed on it, whether anybody is signed in, whether the desktop is locked, and
+ *   a `missing[]` carrying the exact command for each thing that is not there.
+ *
+ *   WHY THE FOUR FIELDS ABOVE ARE NOT READ OUT OF IT. They come from the cheap probe, which
+ *   is a plain `echo` down an ssh connection and needs nothing on the far machine at all.
+ *   `detail` comes from the runner, which needs Node there. Letting the deeper answer
+ *   overwrite the shallower one would report a perfectly reachable machine as unreachable the
+ *   day somebody's Node is a version too old, and offer them the ssh config as the fix.
+ *
+ *   Absent when the host never answered, and when `doctor --offline` skipped dialling
+ *   altogether. Absent is "nobody asked", never "there is nothing there".
  */
 
 /**
@@ -180,7 +196,7 @@ export const CHANNELS = [
  * should be able to read it once and know what to call, what it will get back,
  * and what it must not bother asking for here.
  *
- * @param {{cwd?: string, configFile?: string, offline?: boolean}} [opts]
+ * @param {{cwd?: string, configFile?: string, offline?: boolean, machines?: boolean}} [opts]
  * @returns {Promise<Capabilities>}
  */
 export async function capabilities(opts = {}) {
@@ -202,7 +218,12 @@ export async function capabilities(opts = {}) {
 
   const [tools, hosts, repo, reference, drivers, phones, asked] = await Promise.all([
     findTools(cwd, browsers),
-    offline ? Promise.resolve(/** @type {HostReport[]} */ ([])) : reachableHosts(),
+    // Only a product that could actually run somewhere else is a reason to go looking for
+    // somewhere else. A website or a command-line tool never needs a Windows desktop, and
+    // the hosts list feeds exactly one surface: that one.
+    offline
+      ? Promise.resolve(/** @type {HostReport[]} */ ([]))
+      : reachableHosts({ dial: opts.machines === true || desktopApp !== null }),
     isRepo(root).catch(() => false),
     findReference(root),
     whatThisCopyCanDrive(),
@@ -233,7 +254,7 @@ export async function capabilities(opts = {}) {
     },
     surfaces,
     drivers,
-    covers: whatThisRunActuallyCovers(surfaces),
+    covers: whatThisRunActuallyCovers(surfaces, configFile !== null),
     browsers: {
       willOpen: browsers.chosen,
       borrowingYourOwn: browsers.borrowingHis,
@@ -256,7 +277,15 @@ export async function capabilities(opts = {}) {
     hosts,
     nextSteps: nextSteps(surfaces, reference, repo),
     limits: PERMANENT_LIMITS,
-    wiring: WIRING,
+    // The wiring block, with the real folder in it.
+    //
+    // `WIRING` carries a placeholder, because it is written once as a constant and a constant
+    // cannot know where it is being asked from. Handing that placeholder straight back is
+    // how `doctor --json` came to answer an agent's "how do I wire this up" with the literal
+    // words `/absolute/path/to/your/project` — a value that fails silently if pasted, and
+    // one the tool knew the real answer to all along. `init` had always filled it in; this
+    // is the same courtesy from the command an agent is told to call first.
+    wiring: { ...WIRING, mcp: mcpWiringFor(root) },
   };
 
   return caps;
@@ -328,6 +357,20 @@ const WIRING = {
   },
 };
 
+/**
+ * The wiring block for one project, with its folder filled in.
+ *
+ * @param {string} root
+ * @returns {Record<string, unknown>}
+ */
+function mcpWiringFor(root) {
+  return {
+    mcpServers: {
+      staysfixed: { command: 'npx', args: ['-y', 'staysfixed', 'mcp'], cwd: root },
+    },
+  };
+}
+
 /**
  * The version out of package.json, read without importing the CLI — doctor has
  * to work when everything else in the project is broken.
@@ -470,22 +513,27 @@ async function findTools(cwd, browsers) {
     })(),
 
     (async () => {
-      const installed = hasModule(cwd, 'playwright') || hasModule(cwd, 'playwright-core');
-      // The browsers Playwright downloads live outside any project and survive
-      // every reinstall, so finding them means half the work is already done and
-      // telling somebody to download them again would be wrong.
+      // Ask the thing that actually opens the page, not the folder it might live in.
+      //
+      // This used to look for a `playwright` folder under the project being checked. That is
+      // the wrong question in two directions at once. The driver now ships WITH this tool, so
+      // it is present even when the project has never heard of it; and a project that keeps
+      // its packages somewhere unusual has one when the folder walk says it does not.
+      //
+      // Getting this wrong is how 0.7.2 came to tell every agent that asked that web apps and
+      // sites could be checked "here and now", and then answered every single website check
+      // with "no web page can be opened". `loadPlaywright` is the one piece of code whose
+      // answer is the truth, because it is the code the walk itself runs.
+      const state = await loadPlaywright({ projectRoot: cwd });
       const downloaded = playwrightBrowsersDir();
       add({
         id: 'playwright',
-        name: 'Playwright',
-        found: installed,
-        where: downloaded ?? undefined,
-        why: 'Reads a page’s meaning tree properly, and brings a browser of its own so yours is left alone.',
-        fix: installed
-          ? undefined
-          : downloaded
-            ? `Its browsers are already downloaded in ${downloaded}, so only the package is missing: npm install --save-dev playwright`
-            : INSTALL_COMMAND,
+        name: 'a browser to read pages with',
+        found: state.ok,
+        where: state.executable ?? downloaded ?? undefined,
+        version: state.version,
+        why: 'Reads a page’s meaning tree properly, and opens a browser that is not the one you use, so yours is left alone.',
+        fix: state.ok ? undefined : `${state.howToGet ?? INSTALL_COMMAND}  — nothing to sign up for and nobody to ask.`,
         automatic: true,
       });
     })(),
@@ -498,7 +546,15 @@ async function findTools(cwd, browsers) {
         found: app !== null,
         where: app?.where,
         why: 'A desktop app is driven straight over its own debugging port, so no browser is needed for it — only the app itself.',
-        fix: app ? undefined : 'Only needed if the product you are watching is a desktop app. If it is, name the built app in your settings under app.binary.',
+        // `electron.binary`, not `app.binary`.
+        //
+        // Both keys exist and they belong to different halves of the tool: `app.binary` is
+        // what version 1's picture engine reads, and `electron.binary` is what the difference
+        // engine reads. `doctor` describes the difference engine, so telling somebody to set
+        // `app.binary` sent them to write a setting the adapter they are about to run never
+        // looks at — and the next run says there is no desktop app, for a reason they have
+        // just ruled out.
+        fix: app ? undefined : 'Only needed if the product you are watching is a desktop app. If it is, name the built app in your settings under electron.binary.',
         automatic: false,
       });
     })(),
@@ -540,7 +596,17 @@ async function findTools(cwd, browsers) {
         where: where ?? undefined,
         version: names[0],
         why: 'The emulator is the program; a virtual device is the phone it runs. Without one there is nothing to install the app onto.',
-        fix: names.length > 0 ? undefined : 'sdkmanager "system-images;android-35;google_apis;arm64-v8a" && avdmanager create avd -n staysfixed -k "system-images;android-35;google_apis;arm64-v8a"',
+        // Asked of the Android adapter, never written out again here.
+        //
+        // There were two copies of this command, one in each file, and they had drifted in
+        // two ways at once. They named different Android versions, so doctor and the adapter
+        // disagreed about which device to make. And both hardcoded `arm64-v8a`, so anybody on
+        // an Intel Mac or an x86 Linux box was handed a command naming an image that does not
+        // exist for their machine — and the failure talks about the image, which sends them
+        // looking for the wrong thing entirely. `deviceToMake` reads this machine's processor
+        // and carries the Play-Store warning in the same string, so neither half can be
+        // separated from the other again.
+        fix: names.length > 0 ? undefined : deviceToMake().both,
         automatic: true,
       });
     })(),
@@ -745,7 +811,7 @@ function findDesktopApp(cwd) {
       // in a folder that contains one script.
       const text = withoutComments(readFileSync(configFile, 'utf8'));
       const named = /["']?binary["']?\s*:\s*["'`]([^"'`]+)["'`]/.exec(text);
-      if (named) return { where: named[1], how: 'your settings name it under app.binary' };
+      if (named) return { where: named[1], how: 'your settings name it under electron.binary' };
       if (/["']?kind["']?\s*:\s*["'`]electron["'`]/.test(text)) {
         return { where: configFile, how: 'your settings say this project is a desktop app' };
       }
@@ -910,6 +976,54 @@ function blocks(need) {
   return need.why.startsWith('Nothing on this platform');
 }
 
+/**
+ * One adapter's — or one machine's — `Missing` in the shape the rest of this file reads.
+ *
+ * The two shapes exist for good reasons and neither is going away: an adapter says what it
+ * needs and what that unlocks, and doctor has to say additionally whether a person is
+ * required. The translation between them is the only place that decision is made, so both
+ * callers make it the same way and `blocks` above keeps reading the sentence it expects.
+ *
+ * @param {import('./adapters/contract.js').Missing} m
+ * @returns {Need}
+ */
+function needFromMissing(m) {
+  return {
+    what: String(m.what),
+    why: m.blocking === true ? 'Nothing on this platform can be checked at all without it.' : 'It widens what can be watched here.',
+    fix: String(m.howToGet ?? ''),
+    // Whether a person is needed is read out of the words, because the adapter
+    // contract has no field for it. A licence, an account, a pair of hands or a
+    // device is a person; everything else is a command the agent just runs. Being
+    // wrong in this direction only ever means telling somebody about a step they
+    // did not have to take, which is far cheaper than the other way round.
+    automatic: !/licen[cs]e|apple id|app store|plug|pair of hands|somebody has to|a person|sign in|log in|only a person/i.test(String(m.howToGet ?? '')),
+    unlocks: String(m.unlocks ?? ''),
+  };
+}
+
+/**
+ * What one platform reports when the adapter that answers for it did not answer.
+ *
+ * Written as blocking on purpose. It is not a claim that the platform cannot be checked — it
+ * is the honest opposite, that nobody here knows — and between the two ways of being wrong,
+ * saying less is covered than really is costs somebody a second look, while saying more is
+ * covered than really is costs them a green run that means nothing.
+ *
+ * @param {string} name
+ * @param {string} why
+ * @returns {Need}
+ */
+function couldNotAsk(name, why) {
+  return {
+    what: `an answer from the ${name} adapter about what it needs`,
+    why: 'Nothing on this platform can be checked at all without it.',
+    fix: `The ${name} adapter was asked what it needs here and ${why}, so nothing on this page says whether it would work. Run \`staysfixed doctor\` again; if it keeps happening, run a check aimed at ${name} and read what that says.`,
+    automatic: true,
+    unlocks: `an honest answer about whether your ${name} product can be checked on this machine — right now there is none, in either direction`,
+  };
+}
+
 /**
  * The platforms that arrive as an adapter of their own, and know their own requirements.
  * The built-in five are described by hand above, because they are older than this
@@ -960,29 +1074,26 @@ async function askTheAdapters(root) {
       const adapter = engine.adapters.find((a) => a.name === name);
       if (!adapter) return;
       try {
-        /** @type {{missing?: {what?: string, unlocks?: string, howToGet?: string, blocking?: boolean}[]}} */
+        /** @type {{missing?: {what?: string, unlocks?: string, howToGet?: string, blocking?: boolean}[]}|null} */
         const detection = await Promise.race([
           adapter.detect({ root, config: config[name] ?? {} }),
-          new Promise((resolve) => setTimeout(() => resolve({ missing: [] }), REACH_MS * 2)),
+          // Null, not an empty answer. "The adapter says it needs nothing" and "the adapter
+          // never answered" reached this line as the same empty list, and an empty list is
+          // what makes a surface READY: an Android adapter that hung for sixteen seconds
+          // produced "Covered against the stored record" on a machine where nothing had been
+          // asked at all. A silence that turns into an all-clear is the exact failure this
+          // whole tool exists to prevent, so silence now has a value of its own.
+          new Promise((resolve) => setTimeout(() => resolve(null), REACH_MS * 2)),
         ]);
-        const needs = (detection?.missing ?? [])
+        out.set(name, detection === null ? [couldNotAsk(name, `it did not answer within ${Math.round((REACH_MS * 2) / 1000)} seconds`)] : (detection.missing ?? [])
           .filter((m) => typeof m.what === 'string' && m.what !== '')
-          .map((m) => /** @type {Need} */ ({
-            what: String(m.what),
-            why: m.blocking === true ? 'Nothing on this platform can be checked at all without it.' : 'It widens what can be watched here.',
-            fix: String(m.howToGet ?? ''),
-            // Whether a person is needed is read out of the words, because the adapter
-            // contract has no field for it. A licence, an account, a pair of hands or a
-            // device is a person; everything else is a command the agent just runs. Being
-            // wrong in this direction only ever means telling somebody about a step they
-            // did not have to take, which is far cheaper than the other way round.
-            automatic: !/licen[cs]e|apple id|app store|plug|pair of hands|somebody has to|a person|sign in|log in/i.test(String(m.howToGet ?? '')),
-            unlocks: String(m.unlocks ?? ''),
-          }))
-          .filter((need) => need.fix !== '');
-        out.set(name, needs);
-      } catch {
-        // An adapter that cannot answer contributes nothing, and the machine survey stands.
+          .map((m) => needFromMissing(/** @type {import('./adapters/contract.js').Missing} */ (m)))
+          .filter((need) => need.fix !== ''));
+      } catch (e) {
+        // Same again for an adapter that fell over. It contributes a hole, never a silence:
+        // the machine survey stands, and this platform says plainly that nothing here knows
+        // whether it would work.
+        out.set(name, [couldNotAsk(name, messageOf(e))]);
       }
     }),
   );
@@ -1069,13 +1180,40 @@ function androidSdkTool(folder, name) {
  * answers is a runner the tool already has, and it must never appear in the
  * result as something to go and set up.
  *
+ * @param {{dial?: boolean}} [opts]
  * @returns {Promise<HostReport[]>}
  */
-export async function reachableHosts() {
+export async function reachableHosts(opts = {}) {
   if (!onPath('ssh')) return [];
   const names = await sshConfigHosts();
   if (names.length === 0) return [];
 
+  // READING the ssh config is free and tells nobody anything. DIALLING is neither, and it
+  // is not something this tool may do to somebody who has just installed it.
+  //
+  // The first command a stranger runs is `doctor`. On a brand-new scratch project with no
+  // settings file and nothing that could possibly need a second machine, this opened ssh
+  // connections to every host in their `~/.ssh/config` and ran a command on each — measured
+  // on 2026-08-30: ten hosts configured, connections out within seconds of the first run,
+  // nothing said before or after. Those are production servers in a lot of people's configs,
+  // and in a lot of workplaces that alone is a policy breach. `--offline` existed, but a way
+  // out you only learn about afterwards is not consent.
+  //
+  // So it is asked for now rather than assumed, and the machines are still NAMED either way,
+  // because a machine quietly left out of the answer is the same bug as a folder quietly
+  // skipped while reading source: the list looks complete and the runner somebody needed is
+  // simply not in it.
+  if (opts.dial !== true) {
+    return names.map(
+      (name) =>
+        /** @type {HostReport} */ ({
+          name,
+          reachable: false,
+          how: 'named in your ssh config and deliberately NOT dialled. Nothing here needs a second machine, and this tool does not connect to yours unasked. `staysfixed doctor --machines` checks them.',
+        })
+    );
+  }
+
   const dialled = await Promise.all(names.slice(0, MAX_HOSTS).map((name) => describeHost(name)));
   // Anything past the cap is NAMED rather than dropped. A machine quietly left out of
   // this list is the same shape of bug as a folder quietly skipped while reading source:
@@ -1126,6 +1264,9 @@ async function describeHost(name) {
   const ssh = ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=5'];
   const alive = await ask('ssh', [...ssh, name, `echo ${ALIVE}`], REACH_MS);
   if (!answered(alive)) return readHostProbe(name, alive, null);
+  // Nothing more is asked of a machine that will not even echo. Everything below costs a
+  // second connection, and spending it on a host that did not answer the first one is how
+  // doctor stops being the quick command somebody runs when they are already stuck.
 
   // A shell that can SEE powershell.exe on the filesystem has a real Windows desktop
   // behind it — the cheapest Windows runner there is, and one nobody has to provision.
@@ -1135,7 +1276,64 @@ async function describeHost(name) {
   // it. The one list of places to look lives in remote.js, which is the file that later
   // has to actually run one.
   const look = await ask('ssh', [...ssh, name, `ls -d ${POWERSHELL_PATHS.map((p) => `'${p}'`).join(' ')}`], REACH_MS);
-  return readHostProbe(name, alive, look);
+  const report = readHostProbe(name, alive, look);
+
+  // And then the half that was written and never called.
+  //
+  // "Reachable" on its own is not an answer anybody can act on. The requirement this whole
+  // file exists to meet is that a stranger's AI can read what the tool needs and tell the
+  // person, with the exact commands — and a remote machine that comes back as one boolean
+  // and a sentence fails that completely. `describeRemote` answers the rest: what is
+  // installed there, whether anybody is signed in on the Windows desktop, whether it is
+  // locked, and a list of what is missing with the command for each.
+  //
+  // It never throws, but it does open a connection, so it is still wrapped: doctor answering
+  // less is a bad day, and doctor not answering is the command somebody runs when they are
+  // already stuck failing on them.
+  try {
+    const detail = await describeRemote(name, {
+      // What the cheap probe already proved, handed over rather than asked again. Without
+      // this, a machine with no Node on it comes back "could not be reached" and the fix
+      // offered is the ssh config that just worked.
+      answered: true,
+      powershell: report.powershell ?? null,
+      timeoutMs: REACH_MS * 2,
+      windowsTimeoutMs: REACH_MS * 4,
+    });
+    return withRemoteDetail(report, detail);
+  } catch (e) {
+    return { ...report, how: `${report.how}, but nothing more could be learned about it (${messageOf(e)})` };
+  }
+}
+
+/**
+ * Fold what the runner learned into what the cheap probe proved.
+ *
+ * Split out and exported so the merge can be tested without a network: the rule that the
+ * shallow answer wins on reachability is the whole point of it, and a rule that only exists
+ * inside a function nothing can call without an ssh key is a rule nobody will notice
+ * breaking.
+ *
+ * @param {HostReport} report   What the plain `echo` and `ls` probes established.
+ * @param {import('./remote.js').RemoteDescription} detail
+ * @returns {HostReport}
+ */
+export function withRemoteDetail(report, detail) {
+  /** @type {HostReport} */
+  const out = { ...report, detail };
+  // Windows, only ever added. The cheap probe asks the filesystem for powershell.exe and is
+  // right whether or not anything else on that machine works; the deep one cannot ask at all
+  // unless the runner started. So a `false` from the deep probe is "could not tell", and
+  // letting it clear a `true` would lose the Windows runner somebody already has.
+  if (detail.windows === true && out.windows !== true) {
+    out.windows = true;
+    if (detail.powershell) out.powershell = detail.powershell;
+  }
+  // `detail.how` already opens with the fact that a shell answers, so it replaces the
+  // shallower sentence rather than being appended to it. Two sentences saying the same thing
+  // in different words is how a reader starts wondering which of them is the real answer.
+  if (!detail.runnerStarted) out.how = detail.how;
+  return out;
 }
 
 /**
@@ -1409,7 +1607,7 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
             {
               what: 'settings naming the built app',
               why: 'Two builds of one desktop app fight over its single-instance lock and its data folder, so the tool has to know exactly which file to open and give each run its own folder.',
-              fix: `Run \`staysfixed init\`, or set app.binary to ${desktopApp.where}.`,
+              fix: `Run \`staysfixed init\`, or set electron.binary to ${desktopApp.where}.`,
               automatic: true,
               unlocks: 'Your desktop app gets checked end to end, including every IPC channel the code registers — the doors no screenshot has ever seen.',
             },
@@ -1417,7 +1615,7 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
   });
   if (desktopApp === null) {
     notInThisProject.add('electron');
-    impossible.set('electron', 'This project has no desktop app in it. If yours is built somewhere else, name the built app in your settings under app.binary and this becomes available — nothing else is needed, and no browser is needed for it at all.');
+    impossible.set('electron', 'This project has no desktop app in it. If yours is built somewhere else, name the built app in your settings under electron.binary and this becomes available — nothing else is needed, and no browser is needed for it at all.');
   }
 
   // Three separate questions, and folding any two of them together is how a surface gets
@@ -1536,25 +1734,51 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
   // is "detect rather than ask" at its sharpest: a runner that already answers must never
   // be presented as something to go and set up.
   const windowsDriver = canDrive('windows');
+  // A Windows desktop nobody has signed into is not a runner. There is nothing on it to read
+  // — no windows, no controls — so calling it "partly covered" would be the exact over-claim
+  // this file exists to prevent. The question can only be asked when the runner started
+  // there, so `undefined` means nobody could tell and the older, more generous answer stands.
+  const windowsSignedOut = windowsHost?.detail?.desktopLoggedIn === false;
+  const windowsUsable = windowsHost !== undefined && windowsDriver && !windowsSignedOut;
   surfaces.push({
     id: 'windows',
     name: 'native Windows apps',
-    status: windowsHost && windowsDriver ? 'partial' : 'unavailable',
+    status: windowsUsable ? 'partial' : 'unavailable',
     summary: !windowsHost
       ? 'No Windows desktop is reachable from here. This is usually fine: an Electron product on Windows is watched over the debug port instead, from any machine.'
       : !windowsDriver
         ? `A real Windows desktop is reachable through ${windowsHost.name}, and this copy of Stays Fixed cannot drive one. ${noDriver('windows')}`
-        : `A real Windows desktop is already reachable through ${windowsHost.name}, and nothing has to be installed on it — the program that reads the screen is sent down the ssh connection each run and disappears when it closes. Two builds still cannot run at once, because Windows shows one desktop, so runs are one after the other and the comparison is weaker here than anywhere else.`,
-    canCheck: windowsHost && windowsDriver ? withoutADriver : [],
-    cannotCheck: windowsHost && windowsDriver ? ['meaning', 'pixels'] : CHANNELS.map((c) => c.id),
+        // The adapter's own paragraph, not a second one written here. It knows whether
+        // anybody is signed in and whether the screen is locked, and those two change the
+        // answer completely; a summary kept in this file could only ever guess at them, and
+        // two descriptions of one machine will eventually disagree.
+        : windowsHost.detail
+          ? `${describeWindows(windowsHost.detail)} Nothing has to be installed on it either — the program that reads the screen is sent down the ssh connection each run and disappears when it closes.`
+          : `A real Windows desktop is already reachable through ${windowsHost.name}, and nothing has to be installed on it — the program that reads the screen is sent down the ssh connection each run and disappears when it closes. Two builds still cannot run at once, because Windows shows one desktop, so runs are one after the other and the comparison is weaker here than anywhere else.`,
+    canCheck: windowsUsable ? withoutADriver : [],
+    cannotCheck: windowsUsable ? ['meaning', 'pixels'] : CHANNELS.map((c) => c.id),
     // Asked of the Windows adapter, which knows what it needs — the name of a machine and
     // the built program — rather than kept as a second opinion here. The one thing added
     // is the host name, because doctor found it by dialling and the adapter cannot.
+    //
+    // Plus whatever the machine itself is missing, which only the dial could find out: a
+    // desktop nobody has signed into, a screen that is locked. Those come with the sentence
+    // saying what each one unlocks, so an agent can relay one clear line to a person instead
+    // of inventing instructions.
     needs:
       windowsHost && windowsDriver
-        ? (asked.get('windows') ?? []).map((need) => ({ ...need, fix: need.fix.replace(/"the-ssh-host-name"/g, `"${windowsHost.name}"`) }))
+        ? [
+            ...(windowsHost.detail?.missing ?? []).map(needFromMissing),
+            ...(asked.get('windows') ?? []).map((need) => ({ ...need, fix: need.fix.replace(/"the-ssh-host-name"/g, `"${windowsHost.name}"`) })),
+          ]
         : [],
   });
+  if (windowsSignedOut && windowsHost) {
+    impossible.set(
+      'windows',
+      `${windowsHost.name} is a Windows machine and this copy can drive one, but nobody is signed in on that desktop. Nothing can be read off a desktop nobody has signed into. Sign in on it once and leave the session running — locking the screen afterwards is fine — and this becomes available.`,
+    );
+  }
   if (windowsHost && !windowsDriver) {
     impossible.set('windows', `${noDriver('windows')} Nothing you install on that machine changes it. Update Stays Fixed to a copy that has it.`);
   }
@@ -1584,6 +1808,9 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
  * @property {{name: string, why: string}[]} partly   Looked at, but not completely, and why.
  * @property {{name: string, why: string, whoFixes: SurfaceState}[]} notCovered
  * @property {boolean} everything    True only when nothing at all is left out.
+  * @property {boolean} [canRunHere]
+ *   False when nothing is set up in this folder, so a check cannot run here at all
+ *   whatever this machine could otherwise drive.
  */
 
 /**
@@ -1595,9 +1822,10 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
  * covers your website; your iPhone app is not being checked, and here is why.
  *
  * @param {SurfaceReport[]} surfaces
+ * @param {boolean} setUpHere   Whether a check can actually run in this folder at all.
  * @returns {Covers}
  */
-function whatThisRunActuallyCovers(surfaces) {
+function whatThisRunActuallyCovers(surfaces, setUpHere = true) {
   // Three buckets, not two. Folding "partly" into "covered" is exactly the
   // over-claim this function exists to stop: an iPhone app whose screens cannot
   // be read is not a covered iPhone app.
@@ -1621,7 +1849,23 @@ function whatThisRunActuallyCovers(surfaces) {
 
   /** @type {string[]} */
   const parts = [];
-  parts.push(full.length > 0 ? `A check here covers ${plainList(out.covered)} in full.` : 'A check here covers nothing in full.');
+  // What this MACHINE can drive and what a check in THIS FOLDER would cover are two
+  // different questions, and only one of them was being answered. In an empty folder — no
+  // settings, no code — this said "A check here covers command-line tools and libraries and
+  // web apps and sites in full" and doctor exited 0, while `check` in that same folder
+  // refused to run at all: "No Stays Fixed config found here, so there is nothing to check."
+  // Measured 2026-08-30. `doctor --json` is the first call an agent is told to make, which
+  // is the worst place there is for a sentence with "here" in it to mean somewhere else.
+  //
+  // Everything below still says what it said — a reader needs the whole picture either way —
+  // it is just no longer written as though a check could run.
+  if (!setUpHere) {
+    out.canRunHere = false;
+    parts.push('Nothing is set up in this folder, so a check cannot run here at all and would cover nothing. Run `staysfixed init` first.');
+    parts.push(full.length > 0 ? `Once it is set up, this machine could cover ${plainList(out.covered)} in full.` : 'Even set up, this machine could cover nothing in full.');
+  } else {
+    parts.push(full.length > 0 ? `A check here covers ${plainList(out.covered)} in full.` : 'A check here covers nothing in full.');
+  }
   if (some.length > 0) parts.push(`It covers ${plainList(some.map((s) => s.name))} only partly — read the summary for each before treating a clean result as proof.`);
   if (missing.length > 0) {
     parts.push(`It does NOT check ${plainList(missing.map((s) => s.name))} at all, so a clean result says nothing whatever about ${missing.length === 1 ? 'that' : 'those'}.`);
@@ -1696,8 +1940,15 @@ function nextSteps(surfaces, reference, repo) {
     steps.push({
       what: 'record a reference',
       why: 'Until one build has been recorded there is nothing to compare a new one against, and a clean result would mean nothing.',
-      fix: 'staysfixed check --paired',
-      automatic: true,
+      // Both halves of this were wrong, and they were wrong in the direction that matters.
+      // `check --paired` cannot record a reference — run it twice on a fresh project and
+      // both runs answer that there is no build on record, with the reference id still
+      // empty — so anybody following this went round in a circle. And `automatic: true` told
+      // the agent this was its to do, when the one rule underneath this whole product is
+      // that only shipping cuts a reference and no agent may bless its own work. Saying an
+      // agent can do the single thing it must never do is worse than saying nothing.
+      fix: 'staysfixed ship    (only shipping records what "working" means — no agent may cut that reference)',
+      automatic: false,
       unlocks: 'Every check after this one has something to compare against, so "nothing changed" starts meaning something.',
     });
   }
@@ -1726,6 +1977,49 @@ function nextSteps(surfaces, reference, repo) {
 
 // ── words ───────────────────────────────────────────────────────────────────
 
+/**
+ * What one reachable machine actually is, in the plainest words there are.
+ *
+ * Every one of these facts was already being collected and thrown away: `describeRemote`
+ * returns what is installed there, whether anybody is signed in, whether the desktop is
+ * locked and what each missing thing would unlock, and doctor was printing a host name.
+ *
+ * Nothing is invented when the answer is unknown. A machine whose runner would not start has
+ * an empty tools list because nothing could ask, not because nothing is installed, and the
+ * note that says so comes from the same place the facts do.
+ *
+ * @param {HostReport} host
+ * @returns {string[]}
+ */
+function hostLines(host) {
+  /** @type {string[]} */
+  const lines = [];
+  const detail = host.detail;
+  if (!detail) {
+    lines.push(`${host.name}: ${host.how}. Nothing further was asked of it.`);
+    return lines;
+  }
+  const has = Object.entries(detail.tools).filter(([, where]) => typeof where === 'string' && where !== '').map(([name]) => name);
+  const head = [detail.os, has.length > 0 ? `has ${plainList(has)}` : null].filter(Boolean).join(', ');
+  lines.push(`${host.name}: ${head || detail.how}.`);
+  if (detail.windows) {
+    lines.push(
+      `  Windows behind it${detail.windowsVersion ? ` (${detail.windowsVersion})` : ''}, ` +
+        `${detail.desktopLoggedIn === false ? 'with nobody signed in on the desktop' : detail.desktopLoggedIn === true ? 'signed in' : 'and whether anybody is signed in could not be read'}` +
+        `${detail.desktopLocked === true ? ', screen locked — controls still read correctly, only whole-screen pictures come back black' : ''}.`,
+    );
+  }
+  // Each one with the exact command, because "you need Node there" and "run this" are not the
+  // same message, and only one of them can be relayed to somebody who is not a programmer.
+  for (const missing of detail.missing) {
+    lines.push(`  ${missing.blocking === true ? 'needs' : 'would help'}: ${missing.what} — ${missing.howToGet}`);
+  }
+  if (!detail.runnerStarted) {
+    lines.push('  What is installed on it is unknown rather than absent: the program this tool sends down the connection did not start, so nothing could be asked.');
+  }
+  return lines;
+}
+
 /**
  * The same object, said out loud. Used by the CLI, and quoted verbatim into the
  * MCP answer so an agent and a person are never told different things.
@@ -1799,6 +2093,10 @@ export function describeCapabilities(caps) {
   const runners = caps.hosts.filter((h) => h.reachable);
   if (runners.length > 0) {
     lines.push(`Other machines it can already reach: ${runners.map((h) => h.name + (h.windows ? ' (has a real Windows desktop behind it)' : '')).join(', ')}.`);
+    // And then what each of them actually is. A name and the word "reachable" is not
+    // something anybody can act on — the requirement is that an agent reading this can tell
+    // a person what a machine needs, with the command, and a one-word answer fails that.
+    for (const host of runners) for (const line of hostLines(host)) lines.push(`  ${line}`);
     lines.push('');
   }
   // Said out loud, because a machine left undialled is a runner somebody may be
@@ -1833,7 +2131,7 @@ export function describeCapabilities(caps) {
  * @returns {Promise<number>}
  */
 export async function run(ctx) {
-  const caps = await capabilities({ cwd: ctx.cwd, configFile: ctx.configFile, offline: ctx.bool('offline') });
+  const caps = await capabilities({ cwd: ctx.cwd, configFile: ctx.configFile, offline: ctx.bool('offline'), machines: ctx.bool('machines') });
 
   if (ctx.bool('json')) {
     // Nothing but the object may reach standard output. Doctor is the first call
@@ -1881,6 +2179,7 @@ export async function run(ctx) {
   const runners = caps.hosts.filter((h) => h.reachable);
   if (runners.length > 0) {
     say(paint.grey(`  machines it can already reach: ${runners.map((h) => h.name).join(', ')}`));
+    for (const host of runners) for (const line of hostLines(host)) say(paint.grey(`    ${line}`));
   }
   const undialled = caps.hosts.filter((h) => h.how.startsWith('not dialled'));
   if (undialled.length > 0) {

package/src/v2/escalate.js

@@ -517,7 +517,11 @@ function buildEscalations(product, record, verdict) {
       kind: 'no-reference',
       what: `There is no build of ${product} on record as working yet, so this run had nothing to compare against.`,
       why: 'Only you can say what "working" means, and you say it by shipping — no agent may cut that reference.',
-      todo: 'Ship once with the hook in place. From the next change onwards it is automatic and you will not see this again.',
+      // The order is said out loud because leaving it out sent people round a circle: `ship`
+      // on a build nothing has watched answers "run a check before the next release", and
+      // this line answered "you say it by shipping". Both are true and neither says which
+      // comes first. A check watches the build; shipping then blesses what was watched.
+      todo: 'Run `staysfixed check` once so there is a build to bless, then `staysfixed ship`. From the next change onwards it is automatic and you will not see this again.',
     });
   }