cawdev-cli 1.0.2-beta → 1.0.4-beta

package/runner/attach.mjs

@@ -50,13 +50,14 @@ import { connect } from 'node:net';
 import { basename, dirname } from 'node:path';
 import { listSockets, socketPathFor } from './control.mjs';
 import {
-  addProject, addWorkspace, agentsOf, pathsOf, readConfigFile, reloadIfRunning,
-  setAcceptsRulesFromConsole, setAgentEnabled, slugsOf,
+  RESTART_FROM_ATTACH, addProject, addWorkspace, agentsOf, pathsOf, readConfigFile, reloadIfRunning,
+  setAcceptsRulesFromConsole, setAgentEnabled, setQuality, slugsOf,
 } from './configure.mjs';
 import {
   TYPE_A_PATH, absolute, completePath, describe, inspectPath, listDirectories,
 } from './paths.mjs';
 import { clip, keyList, padVisible, painter, stripAnsi, visibleWidth, wrap } from '../lib/ansi.mjs';
+import { restartNeededFor } from '../lib/runner-config.mjs';
 import { oneLine } from './brand.mjs';
 import { Scrollback } from './scrollback.mjs';
 import { Session, signInThroughBrowser, storedSession } from './sign-in.mjs';
@@ -490,6 +491,20 @@ export function footerLines(state, width, ink = painter(3)) {
 
   lines.push(settingsBar(runner, runs, width, ink));
 
+  // R294: the config file has moved on from what this daemon booted with, in
+  // ways only a restart applies. A row while it is true and nothing when it
+  // is not — the daemon decides, off the file's own mtime, so an edit by hand
+  // shows here too and an edit reverted clears it. Pinned, because the one
+  // sentence R288 printed about this scrolled off with the next transcript
+  // line, and a person who added a project here believed it was being served.
+  const stale = Array.isArray(runner?.restartNeeded) ? runner.restartNeeded : [];
+  if (stale.length) {
+    lines.push(padVisible(clip(
+      ` ${ink.warn('!')} ${ink.muted('config changed:')} ${ink.text(stale.join(', '))} ${ink.muted(`— restart to apply (${RESTART_FROM_ATTACH})`)}`,
+      width,
+    ), width));
+  }
+
   // Who and where. The runner's NAME is what the console shows and what
   // `--runner` takes, so it is the word somebody would type; the email is what
   // every action here is done as, and "watching only" is not a lesser state,
@@ -690,16 +705,36 @@ const KNOWN_AGENTS = ['claude', 'agy'];
  * "enable" would ask the person to remember what the file says. The hint is
  * where the current value lives; the label is the change.
  */
+/** A project entry's `quality` block, whatever shape the entry is — R300. */
+function qualityOf(entry) {
+  return entry && typeof entry === 'object' && entry.quality ? entry.quality : null;
+}
+
 export function configMenu(file, runner = {}) {
   const slugs = slugsOf(file);
   const agents = agentsOf(file);
   const rulesOn = file.acceptsRulesFromConsole === true;
-  const checkouts = slugs.map((slug) => `${slug}: ${pathsOf(file.projects[slug]).length}`).join(', ');
+  // R294: the file and the daemon can disagree, and the row says so rather
+  // than claiming the file is what runs. `served` is what the hello says the
+  // daemon booted with; a slug in the file and not there is "restart".
+  const stale = Array.isArray(runner.restartNeeded) ? runner.restartNeeded : [];
+  const served = Array.isArray(runner.projects) ? runner.projects : null;
+  const notServed = served && stale.includes('projects') ? slugs.filter((slug) => !served.includes(slug)) : [];
+  const serving = slugs.length
+    ? `serves ${slugs.filter((slug) => !notServed.includes(slug)).join(', ') || 'nothing yet'}`
+    : 'serves nothing yet';
+  const pending = notServed.length ? ` · ${notServed.join(', ')} after a restart` : '';
+  const checkouts = slugs.map((slug) => {
+    const count = pathsOf(file.projects[slug]).length;
+    const booted = runner.workspaces?.[slug];
+    const moved = stale.includes('projects') && typeof booted === 'number' && booted !== count;
+    return `${slug}: ${moved ? `${booted}, ${count} after a restart` : count}`;
+  }).join(', ');
   return new Select({
     kind: 'config',
     title: `this machine — ${runner.name ?? file.name ?? 'cawdev'}`,
     rows: [
-      { id: 'add-project', label: 'Add a project', hint: slugs.length ? `serves ${slugs.join(', ')}` : 'serves nothing yet' },
+      { id: 'add-project', label: 'Add a project', hint: `${serving}${pending}` },
       { id: 'add-workspace', label: 'Add a workspace to a project', hint: checkouts || 'no projects to add one to' },
       ...[...new Set([...KNOWN_AGENTS, ...agents])].map((command) => (agents.includes(command)
         ? { id: `agent:${command}`, label: `Disable ${command}`, hint: 'spawned here now' }
@@ -707,6 +742,11 @@ export function configMenu(file, runner = {}) {
       rulesOn
         ? { id: 'rules', label: 'Stop accepting permission rules from the console', hint: 'on now' }
         : { id: 'rules', label: 'Accept permission rules from the console', hint: 'off now' },
+      // R300: one row per served project, saying whether its branches are
+      // scanned here now — the state the row would change, R288's rule.
+      ...slugs.map((slug) => (qualityOf(file.projects[slug])
+        ? { id: `quality:${slug}`, label: `Stop scanning ${slug} with SonarQube`, hint: `${qualityOf(file.projects[slug]).command ?? 'sonar-scanner'} after TEST now` }
+        : { id: `quality:${slug}`, label: `Scan ${slug} with SonarQube after TEST`, hint: 'not scanned here' })),
       { id: 'show', label: "Show this machine's config", hint: runner.configPath ?? '' },
     ],
   });
@@ -959,6 +999,13 @@ export class Attached {
       this.runner = event.runner;
       this.runs = event.runs;
       this.chooseWatched();
+    } else if (event.type === 'runner') {
+      // R294: the daemon re-read its config — after a signal, or because the
+      // file's mtime moved — and says what it applied and what it could not.
+      // The hello was sent once, when this terminal attached; this is the
+      // same object again, so the footer and the `c` screen read what is
+      // true now.
+      this.runner = event.runner;
     } else if (event.type === 'runs') {
       this.runs = event.runs;
       this.chooseWatched();
@@ -2125,22 +2172,22 @@ export class Attached {
       if (!this.requireSignIn('add a project to this machine')) {
         return undefined;
       }
-      await addProject({
+      const next = await addProject({
         configPath, file, url, session: this.session, ask, say, ink, pick,
         askPath: (spec) => this.askPath(spec),
         inspect: this.options.inspect ?? inspectPath,
         clone: (gitUrl, path) => this.cloneInto(gitUrl, path),
       });
-      return this.afterProjectsChanged();
+      return this.reloadDaemon(file, next);
     }
     if (chosen.id === 'add-workspace') {
-      await addWorkspace({
+      const next = await addWorkspace({
         configPath, file, url, session: this.session, ask, say, ink, pick,
         askPath: (spec) => this.askPath(spec),
         inspect: this.options.inspect ?? inspectPath,
         clone: (gitUrl, path) => this.cloneInto(gitUrl, path),
       });
-      return this.afterProjectsChanged();
+      return this.reloadDaemon(file, next);
     }
     if (chosen.id.startsWith('agent:')) {
       const command = chosen.id.slice('agent:'.length);
@@ -2148,44 +2195,53 @@ export class Attached {
         file, configPath, ask, say, ink, command, enabled: !agentsOf(file).includes(command),
       });
       this.runner.agents = agentsOf(next);
-      return this.reloadDaemon(next);
+      return this.reloadDaemon(file, next);
+    }
+    if (chosen.id.startsWith('quality:')) {
+      const slug = chosen.id.slice('quality:'.length);
+      const next = await setQuality({
+        file, configPath, ask, say, ink, slug, enabled: !qualityOf(file.projects?.[slug]),
+      });
+      return this.reloadDaemon(file, next);
     }
     if (chosen.id === 'rules') {
       const next = await setAcceptsRulesFromConsole({
         file, configPath, ask, say, ink, enabled: file.acceptsRulesFromConsole !== true,
       });
       this.runner.acceptsConsoleRules = next.acceptsRulesFromConsole === true;
-      return this.reloadDaemon(next);
+      return this.reloadDaemon(file, next);
     }
     return this.note('');
   }
 
   /**
-   * The two settings the daemon re-reads on SIGHUP, applied to the one this
-   * terminal is attached to — R283's `reloadIfRunning` with the pid handed in,
-   * since the hello already says which process this is.
+   * Every change ends here — R294. The daemon this terminal is attached to is
+   * signalled through the pid the hello carries (R283's `reloadIfRunning`),
+   * and what is printed is the DAEMON's verdict: the keys in
+   * lib/runner-config.mjs's `HOT_SWAPPABLE` were applied, or the file has
+   * moved on in ways only a restart picks up. The daemon pushes its re-read
+   * hello to this terminal as a `runner` event, so `hello` here reads
+   * `this.runner` and waits for `configReadAt` to move — no second socket.
+   *
+   * The footer then carries `restartNeeded` for as long as it is true, which
+   * is the change from R288: a muted line that scrolled away was the only
+   * thing that said a project added here was not being served yet.
    */
-  async reloadDaemon(next) {
-    await reloadIfRunning(next.name, (line) => this.say(line), this.ink, {
-      pidOf: async () => this.runner?.pid ?? null,
+  async reloadDaemon(file, next) {
+    const verdict = await reloadIfRunning(next.name, (line) => this.say(line), this.ink, {
+      hello: async () => this.runner,
+      fallback: restartNeededFor(file, next),
       // Injectable so a test can watch the signal without sending one.
       kill: this.options.kill ?? ((pid, signal) => process.kill(pid, signal)),
+      restartHint: RESTART_FROM_ATTACH,
+      waitMs: this.options.reloadWaitMs ?? 3000,
     });
-    return this.note('');
-  }
-
-  /**
-   * Adding a project or a workspace is not hot-swappable — `config.projects`
-   * is read once at boot — so this says what happens next rather than letting
-   * the row above look like it took effect. The same sentence `cawdev --setup`
-   * says, because it is the same fact.
-   */
-  afterProjectsChanged() {
-    const ink = this.ink;
-    this.say(`  ${ink.muted('This daemon is still on the config it booted with.')}`);
-    this.say(`  ${ink.muted('Press')} ${ink.text('q')} ${ink.muted('to stop it, and the next')} `
-      + `${ink.text('cawdev')} ${ink.muted('starts one on what you just set up.')}`);
-    return this.note('saved — q, then cawdev, to serve it');
+    if (!verdict.running) {
+      // Reachable when the hello carried no pid — a daemon older than R81.
+      this.say(`  ${this.ink.muted('Saved. This daemon is still on the config it booted with — q, then cawdev, to serve it.')}`);
+      return this.note('saved — q, then cawdev, to serve it');
+    }
+    return this.note(verdict.restartNeeded.length ? 'saved — restart to apply' : '');
   }
 
   /**

package/runner/cawdev.mjs

@@ -29,9 +29,10 @@ import { attach, urlFrom, valueOf } from './attach.mjs';
 import { asker, askOne, mintForThisMachine, setUpThisMachine } from './bootstrap.mjs';
 import { liveSockets, probeSocket, socketPathFor } from './control.mjs';
 import {
-  addProject, addWorkspace, readConfigFile, reloadIfRunning, setAcceptsRulesFromConsole,
+  addProject, addWorkspace, readConfigFile, reloadIfRunning, setAcceptsRulesFromConsole, setQuality,
   setAgentEnabled,
 } from './configure.mjs';
+import { restartNeededFor } from '../lib/runner-config.mjs';
 import { Select } from './select.mjs';
 import { storedSession } from './sign-in.mjs';
 import { loadToken } from './token-store.mjs';
@@ -63,6 +64,8 @@ const USAGE = `
                                           already serve — R47's concurrency
   cawdev config agent enable|disable <claude|agy>
   cawdev config rules on|off             accept permission rules from the console
+  cawdev config quality on|off <slug>    scan that project's branches with
+                                         SonarQube after a run's TEST stage
   cawdev config show                     this machine's config, token redacted
 
   On a machine with no config, cawdev sets one up: it signs you in through the
@@ -404,7 +407,8 @@ async function runVersion(argv, ink) {
 /**
  * `cawdev config` — R283's granular half of the setup walk, on a machine
  * already configured. A direct subcommand (`add-project`, `add-workspace`,
- * `agent enable|disable <command>`, `rules on|off`, `show`) or, with none, a
+ * `agent enable|disable <command>`, `rules on|off`, `quality on|off <slug>`,
+ * `show`) or, with none, a
  * menu — the same `Select` widget everything that offers a choice uses.
  */
 async function runConfig(args, ink) {
@@ -448,6 +452,8 @@ export async function pickAction(ask, say, pick = askOne) {
       { id: 'agent-disable', label: 'Disable an agent' },
       { id: 'rules-on', label: 'Accept permission rules from the console' },
       { id: 'rules-off', label: 'Stop accepting rules from the console' },
+      { id: 'quality-on', label: 'Scan a project\'s branches with SonarQube after TEST' },
+      { id: 'quality-off', label: 'Stop scanning a project\'s branches' },
       { id: 'show', label: 'Show this machine\'s config' },
     ],
   }));
@@ -458,22 +464,32 @@ export async function pickAction(ask, say, pick = askOne) {
   }
   if (id === 'rules-on') return ['rules', 'on'];
   if (id === 'rules-off') return ['rules', 'off'];
+  if (id === 'quality-on' || id === 'quality-off') {
+    const slug = (await ask.line('  Which project (slug)? ')).trim();
+    return ['quality', id === 'quality-on' ? 'on' : 'off', slug];
+  }
   return [id];
 }
 
-export async function runAction([verb, ...rest], { configPath, file, url, session, ask, say, ink }) {
+export async function runAction([verb, ...rest], { configPath, file, url, session, ask, say, ink, reloadOptions = {} }) {
   if (verb === 'show') {
     printConfig(file, ink, say);
     return;
   }
+  // R294: every change ends the same way — the daemon on this config, if one
+  // is running, is signalled and its own verdict is printed. For a project or
+  // a workspace that verdict is "needs a restart", because `config.projects`
+  // is read once at boot; but it is the daemon saying so about the file it is
+  // actually on, not this command guessing about a daemon it cannot see.
+  const reload = (next) => reloadIfRunning(file.name, say, ink, {
+    fallback: restartNeededFor(file, next), ...reloadOptions,
+  });
   if (verb === 'add-project') {
-    await addProject({ configPath, file, url, session, ask, say, ink });
-    await afterProjectsChanged(file, say, ink);
+    await reload(await addProject({ configPath, file, url, session, ask, say, ink }));
     return;
   }
   if (verb === 'add-workspace') {
-    await addWorkspace({ configPath, file, url, session, ask, say, ink });
-    await afterProjectsChanged(file, say, ink);
+    await reload(await addWorkspace({ configPath, file, url, session, ask, say, ink }));
     return;
   }
   if (verb === 'agent') {
@@ -481,32 +497,27 @@ export async function runAction([verb, ...rest], { configPath, file, url, sessio
     if (!['claude', 'agy'].includes(command)) {
       throw new Error('Name an agent: cawdev config agent enable|disable claude|agy');
     }
-    await setAgentEnabled({
+    await reload(await setAgentEnabled({
       file, configPath, ask, say, ink, command, enabled: sub === 'enable',
-    });
-    await reloadIfRunning(file.name, say, ink);
+    }));
     return;
   }
   if (verb === 'rules') {
     const [sub] = rest;
-    await setAcceptsRulesFromConsole({ file, configPath, ask, say, ink, enabled: sub === 'on' });
-    await reloadIfRunning(file.name, say, ink);
+    await reload(await setAcceptsRulesFromConsole({ file, configPath, ask, say, ink, enabled: sub === 'on' }));
     return;
   }
-  throw new Error(`Not a cawdev config command: ${verb}. See cawdev --help.`);
-}
-
-/**
- * Adding a project or a workspace is NOT hot-swappable — `config.projects` is
- * read once at boot and threaded everywhere by value, unlike the three
- * settings runner.mjs's SIGHUP handler re-reads. So this only says why
- * nothing happened yet, on the daemon this config would actually restart as.
- */
-export async function afterProjectsChanged(file, say, ink, { probe = probeSocket } = {}) {
-  if (await probe(socketPathFor(file.name))) {
-    say(`  ${ink.muted('A runner is already running here, on the config it booted with.')}`);
-    say(`  ${ink.muted('Attach and quit to stop it, and the next cawdev starts one on what you just set up.')}`);
+  if (verb === 'quality') {
+    // R300. The block is captured per project at boot, so the daemon's own
+    // verdict here is always "restart" — and it is the daemon that says so.
+    const [sub, slug] = rest;
+    if (!['on', 'off'].includes(sub) || !slug) {
+      throw new Error('Name a project: cawdev config quality on|off <slug>');
+    }
+    await reload(await setQuality({ file, configPath, ask, say, ink, slug, enabled: sub === 'on' }));
+    return;
   }
+  throw new Error(`Not a cawdev config command: ${verb}. See cawdev --help.`);
 }
 
 /** The config as somebody would want to read it back — never the secret. */

package/runner/configure.mjs

@@ -9,11 +9,14 @@
 // **Every change here writes the FILE and nothing else.** A daemon already
 // running keeps the config it booted with — `cawdev --setup` already says so,
 // and this repeats it rather than inventing a second story. The one exception
-// is `reloadIfRunning`: `agentCommands` and `acceptsRulesFromConsole` are read
-// fresh off the live `config` object on every use in runner.mjs (a spawn, or
-// the next heartbeat), so a SIGHUP that re-reads the file is enough to apply
-// them without a restart — see runner.mjs's own handler for why that is a
-// signal and not a command sent over R52's read-only socket.
+// is `reloadIfRunning`: the keys in lib/runner-config.mjs's `HOT_SWAPPABLE`
+// are read fresh off the live `config` object on every use in runner.mjs (a
+// spawn, or the next heartbeat), so a SIGHUP that re-reads the file is enough
+// to apply them without a restart — see runner.mjs's own handler for why that
+// is a signal and not a command sent over R52's read-only socket. R294: every
+// change goes through it, and what it prints is the DAEMON's verdict read off
+// the hello — applied, or these keys need a restart — never this file's guess
+// about which keys the daemon can take.
 //
 // R288: the same functions have a SECOND door — the attached terminal's `c`
 // key — and that is why every question here comes in through a parameter.
@@ -359,23 +362,86 @@ export async function setAcceptsRulesFromConsole({
 }
 
 /**
- * The pid of a daemon running on this exact config, or null.
+ * Turn a project's SonarQube scan on or off — R300.
+ *
+ * On writes a `quality` block into the project's entry (`{ command, tokenEnv }`,
+ * the two things the daemon needs; `runner.mjs`'s `qualityBlockOf` fills in
+ * the rest), asking for each with its default offered — Enter keeps it. Off
+ * deletes the block and leaves every other key of the entry as it was. A bare
+ * path entry is promoted to `{workspaces}` on the way, R47's third form, the
+ * way `addWorkspace` promotes one.
+ *
+ * Nothing here checks the scanner is installed: unlike an agent, the scanner
+ * can be missing on a machine that will be told so per run — the daemon
+ * reports "not installed" as an error reading, which is the page saying it
+ * — and a check here would refuse a config somebody is about to complete.
+ * The token is NOT asked for: it is an environment variable this machine
+ * exports, never a value in a file people commit.
+ */
+export async function setQuality({
+  file, configPath, slug, enabled,
+  command, tokenEnv,
+  ask, say, ink = painter(3),
+  write = writeRunnerConfig,
+} = {}) {
+  const projects = file.projects ?? {};
+  if (!slug || !(slug in projects)) {
+    throw new Error(`This machine does not serve ${slug || 'that project'}. `
+      + `It serves: ${Object.keys(projects).join(', ') || 'nothing yet'}.`);
+  }
+  const entry = typeof projects[slug] === 'string'
+    ? { workspaces: [projects[slug]] }
+    : { ...projects[slug] };
+
+  let next;
+  if (enabled) {
+    const chosenCommand = command
+      ?? (String(await ask.line('  Scanner command [sonar-scanner]: ')).trim() || 'sonar-scanner');
+    const chosenTokenEnv = tokenEnv
+      ?? (String(await ask.line('  Environment variable holding the scanner token [SONAR_TOKEN]: ')).trim()
+        || 'SONAR_TOKEN');
+    entry.quality = { ...(entry.quality ?? {}), command: chosenCommand, tokenEnv: chosenTokenEnv };
+    next = { ...file, projects: { ...projects, [slug]: entry } };
+    await write(configPath, next);
+    say(`  ${ink.success('✓')} ${ink.muted(`${slug} scans its branches with`)} ${ink.text(chosenCommand)}`
+      + ` ${ink.muted('after TEST, token from')} ${ink.text('$' + chosenTokenEnv)}`);
+    say(`  ${ink.muted(`Export ${chosenTokenEnv} where the daemon runs. It is never written to this file.`)}`);
+  } else {
+    if (!entry.quality) {
+      say(`  ${ink.muted(`${slug} was already not scanned here.`)}`);
+      return file;
+    }
+    delete entry.quality;
+    next = { ...file, projects: { ...projects, [slug]: entry } };
+    await write(configPath, next);
+    say(`  ${ink.success('✓')} ${ink.muted(`${slug} is no longer scanned on this machine.`)}`);
+  }
+  return next;
+}
+
+/**
+ * The hello of a daemon running on this exact config, or null.
  *
  * The socket is keyed by NAME (R52), not by config path, so a machine
  * renamed between `--setup` and now would miss its own daemon — an edge case
  * left alone deliberately: naming this wrong points the reload at nobody's
  * process rather than somebody else's.
+ *
+ * R294: the whole `runner` object and not only its pid, because the hello is
+ * where the daemon says what it could not apply (`restartNeeded`) and when it
+ * last read the file (`configReadAt`) — the two fields `reloadIfRunning`
+ * phrases its answer from.
  */
-async function livePidFor(name) {
+async function liveHello(name) {
   const path = socketPathFor(name);
   if (!(await probeSocket(path))) return null;
   return new Promise((done) => {
     const client = connectTo(path);
     let buffer = '';
-    const finish = (pid) => {
+    const finish = (runner) => {
       clearTimeout(timer);
       try { client.destroy(); } catch { /* already gone */ }
-      done(pid);
+      done(runner);
     };
     const timer = setTimeout(() => finish(null), 1000);
     client.setEncoding('utf8');
@@ -384,7 +450,7 @@ async function livePidFor(name) {
       const newline = buffer.indexOf('\n');
       if (newline === -1) return;
       try {
-        finish(JSON.parse(buffer.slice(0, newline))?.runner?.pid ?? null);
+        finish(JSON.parse(buffer.slice(0, newline))?.runner ?? null);
       } catch {
         finish(null);
       }
@@ -393,20 +459,77 @@ async function livePidFor(name) {
   });
 }
 
+/** How to restart, said from the shell: attach, quit, start again. */
+export const RESTART_FROM_SHELL = 'cawdev, then q, then cawdev again';
+/** The same, said from inside the attached terminal. */
+export const RESTART_FROM_ATTACH = 'q, then cawdev';
+
 /**
- * SIGHUP a daemon already running on this config, so `agentCommands` and
- * `acceptsRulesFromConsole` take effect without a restart. Never a socket
- * command — see this file's header and runner.mjs's handler for why.
+ * SIGHUP a daemon already running on this config, and say what came of it.
+ *
+ * Never a socket command — see this file's header and runner.mjs's handler for
+ * why. R294: the daemon applies what it can (`HOT_SWAPPABLE`) and advertises
+ * the rest as `restartNeeded`, so this WAITS for the re-read — `configReadAt`
+ * moving past the one the hello carried before the signal — and repeats the
+ * daemon's own verdict rather than guessing at it. Three sentences, and each
+ * is a fact the daemon stated: applied and nothing else changed; applied, and
+ * these keys need a restart; signalled, and nothing came back.
+ *
+ * @param hello reads the daemon's current hello — the socket by default; the
+ *   attached terminal hands in its own copy, which the daemon pushes to it
+ * @param restartHint how to restart from where the person is standing
+ * @param fallback what THIS door believes needs a restart — `restartNeededFor`
+ *   over the file before and after its own write — used only for a daemon
+ *   too old to say (no `configReadAt` on its hello). The daemon's answer wins
+ *   whenever there is one, because the daemon knows what it booted with and
+ *   the door only knows what it just changed
+ * @returns what happened, for a caller that wants to draw it:
+ *   `{ running, applied, restartNeeded }`
  */
-export async function reloadIfRunning(name, say, ink = painter(3), { pidOf = livePidFor, kill = process.kill } = {}) {
-  const pid = await pidOf(name);
-  if (!pid) return false;
+export async function reloadIfRunning(name, say, ink = painter(3), {
+  hello = liveHello,
+  kill = process.kill,
+  restartHint = RESTART_FROM_SHELL,
+  fallback = [],
+  waitMs = 3000,
+  tick = (ms) => new Promise((done) => setTimeout(done, ms)),
+} = {}) {
+  const before = await hello(name);
+  if (!before?.pid) return { running: false, applied: false, restartNeeded: [] };
   try {
-    kill(pid, 'SIGHUP');
-    say(`  ${ink.success('✓')} ${ink.muted(`Told the running daemon (pid ${pid}) to re-read this — no restart needed.`)}`);
-    return true;
+    kill(before.pid, 'SIGHUP');
   } catch (failure) {
-    say(`  ${ink.warn('!')} ${ink.muted(`Could not signal the running daemon (${failure.message}) — restart it to pick this up.`)}`);
-    return false;
+    say(`  ${ink.warn('!')} ${ink.muted(`Could not signal the running daemon (${failure.message}) — restart it to pick this up: ${restartHint}.`)}`);
+    return { running: true, applied: false, restartNeeded: [] };
+  }
+
+  // An older daemon carries no `configReadAt` and cannot be waited for; the
+  // most this can say about it is what R283 said.
+  let after = null;
+  if (before.configReadAt !== undefined) {
+    const deadline = Date.now() + waitMs;
+    while (Date.now() < deadline) {
+      const now = await hello(name);
+      if (now?.configReadAt && now.configReadAt !== before.configReadAt) {
+        after = now;
+        break;
+      }
+      await tick(100);
+    }
+  }
+
+  if (!after && before.configReadAt !== undefined) {
+    say(`  ${ink.warn('!')} ${ink.muted(`Signalled the daemon (pid ${before.pid}) but it did not re-read the file — restart it: ${restartHint}.`)}`);
+    return { running: true, applied: false, restartNeeded: [] };
+  }
+
+  const restartNeeded = after
+    ? (Array.isArray(after.restartNeeded) ? after.restartNeeded : [])
+    : fallback;
+  if (restartNeeded.length) {
+    say(`  ${ink.warn('!')} ${ink.muted('Saved. The running daemon (pid')} ${ink.text(String(before.pid))}${ink.muted(') needs a restart to pick up')} ${ink.text(restartNeeded.join(', '))} ${ink.muted(`— ${restartHint}.`)}`);
+  } else {
+    say(`  ${ink.success('✓')} ${ink.muted(`Told the running daemon (pid ${before.pid}) to re-read this — applied, no restart needed.`)}`);
   }
+  return { running: true, applied: true, restartNeeded };
 }