staysfixed 0.10.0 → 0.11.1

package/src/v2/doctor.js

@@ -196,7 +196,8 @@ 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, machines?: boolean}} [opts]
+ * @param {{cwd?: string, configFile?: string, offline?: boolean, machines?: boolean,
+ *   settingsText?: string}} [opts]
  * @returns {Promise<Capabilities>}
  */
 export async function capabilities(opts = {}) {
@@ -210,6 +211,28 @@ export async function capabilities(opts = {}) {
   // sitting two folders up, and told the agent to go and build one that was already there.
   const root = configFile ? rootForConfig(configFile) : cwd;
 
+  // The settings, as text, from whichever of the two places they live in.
+  //
+  // `init` is the second place. It works out what it is about to write and only then asks
+  // this function what the machine can do — so on a fresh project every question below was
+  // answered against NO settings at all, and the answers went straight into the readiness
+  // it printed. A plain Node command-line tool was told, by the same run that had just
+  // wired `node cli.js --help` into its settings, that it still needed "a command to run".
+  // Being sent to set up something the tool has already set up is how somebody decides this
+  // page is not worth reading. Measured 2026-08-31.
+  const settingsText = opts.settingsText ?? readTextOrNull(configFile);
+  // A machine NAMED in the settings is a machine the project has asked for. Doctor does not
+  // dial anybody's ssh config unasked — that rule stands and is right — but "you have not
+  // asked me to look" and "your own settings name this machine" are different situations,
+  // and treating them the same produced a flat untruth: with `windows: { host: "imza-pc" }`
+  // sitting in the settings, doctor answered "No Windows desktop is reachable from here"
+  // having never dialled anything. Measured 2026-08-31 against a Windows 11 machine that was
+  // reachable, signed in and unlocked the whole time. Only the named machines are dialled;
+  // the rest of the ssh config is still left alone.
+  const askedFor = hostsNamedInSettings(settingsText);
+  const settingsAreJson = opts.settingsText ? false : configFile !== null && configFile.endsWith('.json');
+  const hasSettings = settingsText !== null;
+
   // The browser survey comes first because three different answers below depend
   // on it, and asking this machine the same question three times would be both
   // slow and a way for the three answers to disagree.
@@ -223,15 +246,16 @@ export async function capabilities(opts = {}) {
     // the hosts list feeds exactly one surface: that one.
     offline
       ? Promise.resolve(/** @type {HostReport[]} */ ([]))
-      : reachableHosts({ dial: opts.machines === true || desktopApp !== null }),
+      : reachableHosts({ dial: opts.machines === true || desktopApp !== null, only: askedFor }),
     isRepo(root).catch(() => false),
     findReference(root),
     whatThisCopyCanDrive(),
-    phoneApps(root, configFile),
-    askTheAdapters(root),
+    phoneApps(root, settingsText),
+    askTheAdapters(root, settingsText, settingsAreJson),
   ]);
 
-  const surfaces = describeSurfaces(tools, hosts, configFile !== null, browsers, desktopApp, drivers, phones, asked);
+  const wires = settingsText ? whatTheProcessBlockWires(settingsText) : { commands: 0, imports: 0 };
+  const surfaces = describeSurfaces(tools, hosts, hasSettings, browsers, desktopApp, drivers, phones, asked, wires);
 
   /** @type {Capabilities} */
   const caps = {
@@ -254,7 +278,7 @@ export async function capabilities(opts = {}) {
     },
     surfaces,
     drivers,
-    covers: whatThisRunActuallyCovers(surfaces, configFile !== null),
+    covers: whatThisRunActuallyCovers(surfaces, hasSettings),
     browsers: {
       willOpen: browsers.chosen,
       borrowingYourOwn: browsers.borrowingHis,
@@ -874,22 +898,20 @@ function findDesktopApp(cwd) {
  * install thirty gigabytes of Xcode is asking for work that changes nothing, and the whole
  * design turns on never doing that.
  *
+ * Windows is answered here too, for the same reason and by the same rule: a repository with
+ * no Windows program in it does not need a Windows machine, and saying "no Windows desktop
+ * can be reached from here" about one sends somebody looking for a machine they will never
+ * use. Only the settings can answer it — a native Windows build is not something this file
+ * can go and find in a folder.
+ *
  * @param {string} root
- * @param {string|null} configFile
- * @returns {Promise<{android: FoundApp|null, ios: FoundApp|null}>}
+ * @param {string|null} settingsText
+ * @returns {Promise<{android: FoundApp|null, ios: FoundApp|null, windows: FoundApp|null}>}
  */
-async function phoneApps(root, configFile) {
-  /** @type {string} */
-  let settings = '';
-  if (configFile) {
-    try {
-      // Comments taken away first, for the same reason `findDesktopApp` does it: a
-      // commented-out `apk:` line is an example, not an Android app.
-      settings = withoutComments(readFileSync(configFile, 'utf8'));
-    } catch {
-      settings = '';
-    }
-  }
+async function phoneApps(root, settingsText) {
+  // Comments taken away first, for the same reason `findDesktopApp` does it: a
+  // commented-out `apk:` line is an example, not an Android app.
+  const settings = settingsText ? withoutComments(settingsText) : '';
 
   /**
    * @param {string} key
@@ -961,7 +983,9 @@ async function phoneApps(root, configFile) {
         ? { where: root, how: 'there is an Xcode project here, but nothing says where the built app is' }
         : null);
 
-  return { android, ios };
+  const windows = named('remoteExe') ?? namedPath('exe', (v) => /\.exe$/i.test(v));
+
+  return { android, ios, windows };
 }
 
 /**
@@ -1065,9 +1089,12 @@ const ADAPTERS_THAT_ANSWER_FOR_THEMSELVES = ['android', 'ios', 'windows'];
  * take the rest of the answer with it.
  *
  * @param {string} root
+ * @param {string|null} [settingsText]   The settings as text — from disk, or from what
+ *                                       `init` is about to write.
+ * @param {boolean} [settingsAreJson]
  * @returns {Promise<Map<string, Need[]>>}
  */
-async function askTheAdapters(root) {
+async function askTheAdapters(root, settingsText = null, settingsAreJson = false) {
   /** @type {Map<string, Need[]>} */
   const out = new Map();
   /** @type {{adapters: {name: string, detect: (p: any) => Promise<any>}[]}} */
@@ -1081,10 +1108,9 @@ async function askTheAdapters(root) {
   /** @type {Record<string, any>} */
   let config = {};
   try {
-    const file = findConfigFile(root);
     // Read as text and parsed only when it is JSON. Doctor never runs a person's code to
     // answer a question about their machine, and a settings file may be JavaScript.
-    if (file && file.endsWith('.json')) config = JSON.parse(readFileSync(file, 'utf8'));
+    if (settingsText && settingsAreJson) config = JSON.parse(settingsText);
     // But "not JSON" was being treated as "says nothing", and `init` writes JavaScript — so
     // for almost every project every adapter was asked what it needs while being handed an
     // EMPTY config. It then asked for the very thing the settings already named: a project
@@ -1094,7 +1120,7 @@ async function askTheAdapters(root) {
     // The few values the adapters need to answer honestly are read out of the TEXT instead,
     // scoped to their own block so one block's `app` can never be read as another's. Still no
     // code is run, which was the whole point of the rule.
-    else if (file) config = { ...config, ...settingsFromText(readFileSync(file, 'utf8')) };
+    else if (settingsText) config = { ...config, ...settingsFromText(settingsText) };
   } catch {
     config = {};
   }
@@ -1210,7 +1236,7 @@ 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]
+ * @param {{dial?: boolean, only?: string[]}} [opts]
  * @returns {Promise<HostReport[]>}
  */
 export async function reachableHosts(opts = {}) {
@@ -1233,6 +1259,24 @@ export async function reachableHosts(opts = {}) {
   // 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.
+  // The settings named these, so they are dialled even when nothing else is. Everything
+  // else in the ssh config stays untouched and is still listed by name.
+  const named = (opts.only ?? []).filter((name) => names.includes(name));
+  if (opts.dial !== true && named.length > 0) {
+    const dialledByName = await Promise.all(named.slice(0, MAX_HOSTS).map((name) => describeHost(name)));
+    const rest = names
+      .filter((name) => !named.includes(name))
+      .map(
+        (name) =>
+          /** @type {HostReport} */ ({
+            name,
+            reachable: false,
+            how: 'named in your ssh config and deliberately NOT dialled. Your settings do not mention it and nothing here needs it. `staysfixed doctor --machines` checks them all.',
+          })
+      );
+    return [...dialledByName, ...rest];
+  }
+
   if (opts.dial !== true) {
     return names.map(
       (name) =>
@@ -1414,6 +1458,73 @@ export function readHostProbe(name, alive, look) {
   return report;
 }
 
+/**
+ * Every machine the settings name by ssh host. These are the ones doctor may dial without
+ * being asked twice, because naming a machine in your own settings IS the ask.
+ *
+ * @param {string|null} text
+ * @returns {string[]}
+ */
+export function hostsNamedInSettings(text) {
+  if (!text) return [];
+  const clean = withoutComments(text);
+  const out = new Set();
+  for (const hit of clean.matchAll(/["']?host["']?\s*:\s*["'`]([^"'`]+)["'`]/g)) out.add(hit[1]);
+  return [...out];
+}
+
+/**
+ * The settings as text, or null when there are none to read yet.
+ *
+ * Null and empty are different answers here. "There is no settings file" is what makes a
+ * surface unready; "the settings say nothing about this surface" is a different sentence.
+ *
+ * @param {string|null} file
+ * @returns {string|null}
+ */
+function readTextOrNull(file) {
+  if (!file) return null;
+  try {
+    return readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * How much of this project is actually wired for the command-line surface.
+ *
+ * The `cli` surface was hard-coded READY with "Fully covered here" — it never looked at the
+ * project at all. So on a settings file whose `process` block wires no commands and nothing
+ * to import, doctor said command-line tools were fully covered, and a check then answered
+ * "Nothing that worked has changed" having run not one command. Measured 2026-08-31.
+ *
+ * Counted out of the text, like everything else here, because the settings may be JavaScript
+ * and doctor never runs a person's code to answer a question about their machine.
+ *
+ * @param {string} text
+ * @returns {{commands: number, imports: number}}
+ */
+function whatTheProcessBlockWires(text) {
+  const clean = withoutComments(text);
+  const at = /["']?process["']?\s*:\s*\{/.exec(clean);
+  if (!at) return { commands: 0, imports: 0 };
+  let depth = 0;
+  let end = at.index + at[0].length;
+  for (; end < clean.length; end += 1) {
+    if (clean[end] === '{') depth += 1;
+    else if (clean[end] === '}') {
+      if (depth === 0) break;
+      depth -= 1;
+    }
+  }
+  const inside = clean.slice(at.index + at[0].length, end);
+  return {
+    commands: (inside.match(/["']?run["']?\s*:/g) ?? []).length,
+    imports: (inside.match(/["']?module["']?\s*:/g) ?? []).length,
+  };
+}
+
 /**
  * The handful of settings an adapter needs to say what it is missing, read out of a
  * JavaScript settings file WITHOUT running it.
@@ -1435,6 +1546,10 @@ function settingsFromText(text) {
     electron: ['binary'],
     web: ['url', 'start'],
     http: ['start', 'url'],
+    // Left out until 2026-08-31, and the Windows adapter was handed an empty settings object
+    // as a result: it could not see the machine the settings named, nor the built program,
+    // so it asked for both while both were sitting in the file.
+    windows: ['host', 'remoteExe', 'exe'],
   };
   for (const [block, keys] of Object.entries(wanted)) {
     const at = new RegExp(`["']?${block}["']?\\s*:\\s*\\{`).exec(clean);
@@ -1564,11 +1679,14 @@ async function findReference(root) {
  * @param {import('./browsers.js').BrowserSurvey} browsers
  * @param {{where: string, how: string}|null} desktopApp
  * @param {DriverReport[]} drivers      What this copy of the tool can drive at all.
- * @param {{android: FoundApp|null, ios: FoundApp|null}} phones
+ * @param {{android: FoundApp|null, ios: FoundApp|null, windows: FoundApp|null}} phones
  * @param {Map<string, Need[]>} asked   What each separate adapter says IT is missing.
+ * @param {{commands: number, imports: number}} [wires]
+ *   What this project's own settings wire for the command-line surface. A surface with
+ *   nothing wired covers nothing here, whatever this machine could do.
  * @returns {SurfaceReport[]}
  */
-function describeSurfaces(tools, hosts, configured, browsers, desktopApp, drivers, phones, asked) {
+function describeSurfaces(tools, hosts, configured, browsers, desktopApp, drivers, phones, asked, wires = { commands: 0, imports: 0 }) {
   /** @param {string} surface */
   const canDrive = (surface) => drivers.find((d) => d.surface === surface)?.present !== false;
   /** @param {string} surface */
@@ -1578,6 +1696,9 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
   const browser = browsers.chosen !== null;
   const ownBrowser = browsers.chosen !== null && !browsers.chosen.everyday;
   const windowsHost = hosts.find((h) => h.reachable && h.windows === true);
+  // Nothing was dialled at all: every host carries the sentence that says so. That is a
+  // different answer from "they were dialled and none of them runs Windows".
+  const nobodyWasDialled = hosts.length > 0 && hosts.every((h) => /NOT dialled|not dialled/.test(String(h.how ?? '')));
 
   /** Every channel that needs no driver at all — a child process is enough. */
   const withoutADriver = ['effects', 'complaints', 'results', 'contract', 'counters'];
@@ -1597,14 +1718,31 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
    */
   const notInThisProject = new Set();
 
+  // READY is about this PROJECT, not about this machine. Hard-coded ready meant doctor said
+  // command-line tools were "fully covered here" on a settings file that wires no commands
+  // and nothing to import — and a check then answered "Nothing that worked has changed"
+  // having run not one command.
+  const wiredForCli = configured && wires.commands + wires.imports > 0;
   surfaces.push({
     id: 'cli',
     name: 'command-line tools and libraries',
-    status: 'ready',
-    summary: 'Fully covered here. What it printed, what it exited with, what it wrote, what it called out to, and what it exports.',
+    status: wiredForCli ? 'ready' : 'partial',
+    summary: wiredForCli
+      ? 'Fully covered here. What it printed, what it exited with, what it wrote, what it called out to, and what it exports.'
+      : configured
+        ? 'This machine can cover it in full — what a command printed, what it exited with, what it wrote, what it called out to, what it exports — but these settings wire no command to run and nothing to import, so a check runs none of it and a clean result says nothing about any of it.'
+        : 'This machine can cover it in full, but nothing is set up in this folder yet, so a check cannot run here at all.',
     canCheck: withoutADriver,
     cannotCheck: ['meaning', 'pixels'],
-    needs: [],
+    needs: wiredForCli
+      ? []
+      : [{
+          what: 'a command to run, or something to import',
+          why: 'Nothing here is walked otherwise, and a run that walks nothing still finishes and still says nothing changed.',
+          fix: 'Add `process: { commands: [{ name: "help", run: "node bin/cli.js --help" }] }` to your settings, or `imports: [{ name: "the package entry", module: "index.js" }]`.',
+          automatic: true,
+          unlocks: 'Everything a command does — what it printed, what it exited with, what it wrote to disk, what it reached for.',
+        }],
   });
 
   surfaces.push({
@@ -1754,7 +1892,20 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
   const iosBlocked = iosWants.some(blocks);
   const iosReady = iosMachine && canDrive('ios') && phones.ios !== null && iosWants.length === 0;
   const iosPartly = iosMachine && canDrive('ios') && phones.ios !== null && !iosReady && !iosBlocked;
-  if (!onAMac) {
+  // THE PROJECT IS ASKED BEFORE THE MACHINE, and the order is the whole point. "There is no
+  // iPhone app in this repository" and "this machine cannot run one" are different sentences
+  // with different things to do about them, and a machine reason given for a project that has
+  // no iPhone app in it sends somebody to install thirty gigabytes of Xcode for nothing. On a
+  // Mac this was already right; on Linux the platform test came first, so every project on
+  // every Linux machine was told its non-existent iPhone app was out of reach. Caught by CI
+  // on 2026-08-31 — the Mac suite was green and said nothing about it.
+  if (phones.ios === null) {
+    notInThisProject.add('ios');
+    impossible.set(
+      'ios',
+      'This project has no iPhone app in it, so there is nothing for a simulator to run. If yours is built somewhere else, name the built .app in your settings under ios.app.'
+    );
+  } else if (!onAMac) {
     impossible.set('ios', 'An iPhone build can only be run on a Mac. Everything else on this list is unaffected — check the iPhone app from a Mac, and let this machine cover the rest.');
   } else if (phones.ios === null) {
     notInThisProject.add('ios');
@@ -1772,10 +1923,10 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
     id: 'ios',
     name: 'iPhone apps, on the simulator',
     status: iosReady ? 'ready' : iosPartly ? 'partial' : 'unavailable',
-    summary: !onAMac
-      ? 'Cannot run here: iOS needs a Mac.'
-      : phones.ios === null
-        ? 'Nothing to check: no iPhone app was found in this project, and the settings do not name one.'
+    summary: phones.ios === null
+      ? 'Nothing to check: no iPhone app was found in this project, and the settings do not name one.'
+      : !onAMac
+        ? 'Cannot run here: iOS needs a Mac.'
         : !canDrive('ios')
           ? `An iPhone app is here (${phones.ios.how}), and this copy of Stays Fixed cannot drive one. ${noDriver('ios')}`
           : !iosMachine
@@ -1819,6 +1970,20 @@ 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');
+  // Same rule as iPhone and Android: the project is asked before the machine. A repository
+  // with no native Windows program in it does not need a Windows machine, and "no Windows
+  // desktop is reachable from here" about one is a machine reason given for a project fact.
+  // Caught by CI on 2026-08-31, where a Linux runner reported native Windows apps as out of
+  // reach for a project that contains none.
+  if (phones.windows === null) {
+    notInThisProject.add('windows');
+    impossible.set(
+      'windows',
+      'This project has no native Windows program named in its settings, so there is nothing to open on a Windows desktop. '
+      + 'If yours is built somewhere else, name it under windows.remoteExe (already on that machine) or windows.exe (copied over each run). '
+      + 'Most Windows products are Electron, and those are covered over their debug port from any machine.'
+    );
+  }
   // 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
@@ -1829,8 +1994,15 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
     id: 'windows',
     name: 'native Windows apps',
     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.'
+    summary: phones.windows === null
+      ? 'Nothing to check: this project names no native Windows program in its settings. Most Windows products are Electron, and those are covered over their debug port from any machine.'
+      : !windowsHost
+      ? nobodyWasDialled
+        // Not "no Windows desktop is reachable" — nothing was dialled, so that is not known.
+        // The two were the same sentence until 2026-08-31, and it stated as a fact about the
+        // world an answer that came from a decision not to look.
+        ? 'No machine was dialled, so whether a Windows desktop can be reached from here is unknown. This is usually fine: an Electron product on Windows is watched over the debug port instead, from any machine. `staysfixed doctor --machines` asks the machines in your ssh config, and naming one under `windows: { host: "..." }` in your settings asks that one every time.'
+        : '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')}`
         // The adapter's own paragraph, not a second one written here. It knows whether
@@ -1970,7 +2142,10 @@ function whatThisRunActuallyCovers(surfaces, setUpHere = true) {
     if (noSuchProduct.length) {
       parts.push(`There is nothing of ${noSuchProduct.length === 1 ? 'that kind' : 'those kinds'} in this repository — ${plainList(noSuchProduct)} — so there is nothing here to check, and that is not a limit of this machine.`);
     }
-    if (noSuchMachine.length) parts.push(`${plainList(noSuchMachine, true)} cannot be done here at all, and the reason for each is in notCovered.`);
+    // "the reason for each is listed above", not "is in notCovered": this lands in
+    // covers.short, which `staysfixed doctor` and `staysfixed coverage` both print at a
+    // person. A JSON field name is not somewhere a person can go and look.
+    if (noSuchMachine.length) parts.push(`${plainList(noSuchMachine, true)} cannot be done here at all, and the reason for each is listed above.`);
   }
   if (out.everything) parts.push('Nothing is being left out on this machine.');
   out.short = parts.join(' ');

package/src/v2/init.js

@@ -163,12 +163,24 @@ export async function plan(options = {}) {
   const root = existing ? rootForConfig(existing) : cwd;
 
   const project = await detectProject({ root, readCode: options.readCode });
-  const machine = await readMachine({ cwd: root, offline: options.offline });
+
+  // The settings are worked out BEFORE the machine is asked, and handed over. Doctor reads
+  // the settings to answer half its questions, and on a fresh project there is no settings
+  // file yet — so it used to answer every one of them against nothing, and init printed the
+  // result as this project's readiness. A plain Node command-line tool was told it needed
+  // "a command to run" by the same run that had already written `node cli.js --help` into
+  // its settings. Settings that already exist are read from disk as before; this only hands
+  // over the ones that are about to be written.
+  const config = await planConfig(root, project, existing);
+  const machine = await readMachine({
+    cwd: root,
+    offline: options.offline,
+    settingsText: config.exists ? undefined : config.text,
+  });
 
   const readiness = readinessFor(project, machine);
   const journeys = proposeJourneys(project);
   const needs = sortNeeds(readiness, project, machine);
-  const config = await planConfig(root, project, existing);
   const covers = whatItCovers(readiness);
 
   return {
@@ -250,13 +262,13 @@ export async function init(options = {}) {
  * survey throws, and the honest degradation is "nothing is known about this machine", which
  * makes every surface a person's problem rather than silently a ready one.
  *
- * @param {{cwd: string, offline?: boolean}} opts
+ * @param {{cwd: string, offline?: boolean, settingsText?: string}} opts
  * @returns {Promise<Capabilities|null>}
  */
 async function readMachine(opts) {
   try {
     const { capabilities } = await import('./doctor.js');
-    return await capabilities({ cwd: opts.cwd, offline: opts.offline });
+    return await capabilities({ cwd: opts.cwd, offline: opts.offline, settingsText: opts.settingsText });
   } catch {
     return null;
   }
@@ -385,6 +397,31 @@ function insteadFor(product, project) {
   }
 }
 
+/**
+ * Is the file a package says other code should import actually sitting there?
+ *
+ * Asked before this command tells anybody a library "can be checked here now". The answer
+ * has to allow for the shorthands package.json is allowed to use — `"main": "index"` and
+ * `"main": "./lib"` are both perfectly ordinary and both name something real — so the same
+ * endings and the same folder entry point Node itself would try are tried here. Erring on
+ * the side of "it is there" is the safe direction for THIS question: a way in that exists
+ * and is not recognised would put a job on somebody's list that they cannot do anything
+ * about, and a way in that is missing is caught the moment a check actually runs.
+ *
+ * Exported so a test can ask about one path without building a whole project.
+ *
+ * @param {string} root      The project's own folder.
+ * @param {string} where     Which folder inside it this product lives in. '.' for the root.
+ * @param {string} module    Exactly what package.json said, e.g. './index.js'.
+ * @returns {boolean}
+ */
+export function isThereOnDisk(root, where, module) {
+  const base = path.resolve(root, where === '' ? '.' : where, module);
+  const endings = ['', '.js', '.mjs', '.cjs', '.json', '.node', '.ts'];
+  if (endings.some((end) => existsSync(base + end))) return true;
+  return ['index.js', 'index.mjs', 'index.cjs', 'index.json'].some((name) => existsSync(path.join(base, name)));
+}
+
 /**
  * What this particular product is short of, from what was actually found on disk.
  *
@@ -554,6 +591,36 @@ function productNeeds(product, project) {
     });
   }
 
+  // A way in that package.json promises and the folder has not got.
+  //
+  // package.json is a DECLARATION, not a fact. `"exports": {".": "./index.js"}` in a
+  // repository with no index.js in it reads, to everything upstream of here, as a perfectly
+  // good library with a perfectly good entry point — so nothing was outstanding, the product
+  // came back "ready", and this command told somebody "the library other code imports can be
+  // checked here now" and "right now a check here covers it in full", about a file that was
+  // not there. Measured 2026-08-31 on a package whose entry had never been built. An import
+  // that cannot resolve walks nothing, so "in full" covered nothing at all — which is the one
+  // shape of answer this tool exists to make impossible.
+  const missingWaysIn = (Array.isArray(suggest.imports) ? suggest.imports : [])
+    .map((one) => String(one?.module ?? ''))
+    .filter((module) => module !== '' && (module.startsWith('.') || path.isAbsolute(module)))
+    .filter((module) => !isThereOnDisk(project.root, product.where, module));
+  if (missingWaysIn.length > 0) {
+    const one = missingWaysIn.length === 1;
+    const build = project.scripts.build;
+    needs.push({
+      what: `${plainList(missingWaysIn)} — the ${one ? 'file' : 'files'} other code is told to import, ${one ? 'which is' : 'which are'} not there`,
+      why: `package.json points other projects at ${one ? 'that file' : 'those files'}, and nothing is at that path. There is nothing to import, so a check would compare none of what this library exports — and a clean result would be a clean result about nothing.`,
+      unlocks: 'every name this library exports, and what those exports actually do',
+      fix: build
+        ? `Run \`${build}\` — that is what writes ${one ? 'it' : 'them'} — then \`staysfixed init --force\`. If the entry in package.json is simply pointing at the wrong path, correct it there instead.`
+        : `Either create ${plainList(missingWaysIn)}, or correct the "exports" (or "main") entry in package.json so it names the file that really is the way in.`,
+      who: build ? 'the agent' : 'a person',
+      product: product.name,
+      topic: 'commands',
+    });
+  }
+
   // A command-line program that has to be built before it can be run. This is what a product
   // nothing in package.json names looks like on a fresh clone: the source is there, the
   // program is real, and the file that would be run does not exist yet.
@@ -938,13 +1005,18 @@ export function proposeJourneys(project) {
     }
     if (product.kind === 'library' && Array.isArray(suggest.imports)) {
       for (const entry of suggest.imports) {
+        const module = String(entry.module);
         out.push({
           name: String(entry.name),
-          what: `import ${String(entry.module)} and compare what it exports`,
+          what: `import ${module} and compare what it exports`,
           from: 'package.json',
           surface: 'library',
           automatic: false,
-          ready: true,
+          // Only if the file is really there. package.json naming an entry does not put one
+          // on the disk, and this line printed with no caveat beside it — "import ./index.js
+          // and compare what it exports" — about a file that did not exist. A journey listed
+          // as ready is a promise that a check will walk it.
+          ready: isThereOnDisk(project.root, product.where, module),
         });
       }
     }
@@ -1300,9 +1372,11 @@ export function configText(project) {
   w('  // ───────────────────────────────────────────────────────────────────────');
   w(web ? '  web: {' : '  // web: {');
   const webOn = web ? '    ' : '  //   ';
-  w(`${webOn}// The command that starts it, listening on the PORT it is given. Much better than`);
-  w(`${webOn}// an address: one address can only serve one build, so with an address alone both`);
-  w(`${webOn}// halves of the comparison read the same running copy and prove nothing.`);
+  w(`${webOn}// The command that starts it, listening on the PORT it is given and on 127.0.0.1.`);
+  w(`${webOn}// Much better than an address: one address can only serve one build, so with an`);
+  w(`${webOn}// address alone both halves of the comparison read the same running copy and prove`);
+  w(`${webOn}// nothing. A command that ignores the port it was handed is named within a second`);
+  w(`${webOn}// or two, by name, rather than after a minute and a half of waiting.`);
   const webStart = web?.suggest?.start;
   const flatSite = !webStart && Array.isArray(web?.suggest?.screens) && web.suggest.screens.length > 0;
   if (webStart) {
@@ -1319,7 +1393,11 @@ export function configText(project) {
     w(`${webOn}// package the first time it runs, and that is a decision rather than a default.`);
     w(`${webOn}// start: 'npx --yes serve -l $PORT .',`);
   } else {
-    w(`${webOn}// start: 'npm run dev',`);
+    w(`${webOn}// It has to listen on the PORT it is given AND on 127.0.0.1, and both halves`);
+    w(`${webOn}// matter: measured on 2026-08-31, Vite ignores the PORT and HOST it is handed`);
+    w(`${webOn}// in the environment and binds the name "localhost", which on a Mac is the IPv6`);
+    w(`${webOn}// loopback — so the site comes up somewhere these settings never said.`);
+    w(`${webOn}// start: 'npm run dev -- --port $PORT --strictPort --host 127.0.0.1',`);
   }
   w(`${webOn}// Or, if it is already running somewhere and you accept the weaker answer:`);
   w(`${webOn}// url: 'http://localhost:3000',`);
@@ -1815,7 +1893,15 @@ export async function run(ctx) {
   const others = (result.plan?.readiness ?? [])
     .map((/** @type {any} */ r) => String(r.product ?? ''))
     .filter((/** @type {string} */ n, /** @type {number} */ i, /** @type {string[]} */ all) => n !== '' && all.indexOf(n) === i);
-  if (result.written.length > 0) ok(`Written: ${result.written.map((f) => shortPath(f)).join(', ')}`);
+  if (result.written.length > 0) {
+    ok(`Written: ${result.written.map((f) => shortPath(f)).join(', ')}`);
+    // Worth one line, because of what happens if it is not done. These files are part of the
+    // build now: until they are committed the working tree is not what git has, so the first
+    // reference gets cut from a tree that has no commit of its own — and a later check cannot
+    // put that build back on the machine to walk it live. It falls back to the stored record,
+    // says so, and is weaker for it. One `git add` avoids the whole thing.
+    say('Commit them before you ship. Settings that are not committed leave the first reference tied to a build git does not have, and a later check can then only compare against the record rather than running the old build live.');
+  }
   if (others.length > 1) {
     warn(
       `Those settings describe ONE product. ${others.length} were found here (${others.join(', ')}), and the others are not covered by this file. ` +

package/src/v2/mcp/server.js

@@ -219,7 +219,10 @@ export async function serveMcp(opts = {}) {
         }
         await enqueue(async () => {
           try {
-            const result = await callTool(name, args, { root, cwd, version, protocolVersion });
+            // `audience: 'agent'` is the default in tools.js and is written out anyway: it is
+            // the field that decides whose name goes on a sealed intent and on a waiver, and
+            // a record of who declared something must never rest on a default being right.
+            const result = await callTool(name, args, { root, cwd, version, protocolVersion, audience: 'agent' });
             reply(id, result);
           } catch (e) {
             // A tool that blows up is still a RESULT, not a protocol error: the