cawdev-cli 1.0.2-beta → 1.0.3-beta

package/lib/runner-config.mjs

@@ -0,0 +1,81 @@
+// R294 — which parts of a runner's config a running daemon can take without a
+// restart, and which it cannot.
+//
+// The daemon reads its config ONCE at boot and threads most of it by value —
+// `projects` and their checkouts, `url`, `name`, the token, the MCP servers.
+// Three keys are the exception: they are read fresh off the live `config`
+// object on every use (a spawn, or the next heartbeat), so a SIGHUP that
+// re-reads the file is enough to apply them. That list was spelled in three
+// places — configure.mjs's header, attach.mjs's `reloadDaemon`, runner.mjs's
+// handler — and nothing pinned that the three agreed. It is spelled HERE and
+// nowhere else now, and the one question everything asks of it is
+// `restartNeededFor`: given what the daemon booted with and what the file says
+// now, which keys would only a restart change?
+//
+// Pure, because the daemon answers it and both config doors repeat the answer,
+// and a function all three share is the only way they cannot disagree.
+//
+// Zero dependencies, like everything in tools/.
+
+/**
+ * The keys runner.mjs's SIGHUP handler applies without a restart.
+ *
+ * Only settings that are genuinely safe to hot-swap belong here: each one
+ * must be read off `config` at the moment it is used, never captured at boot.
+ * Adding a key that IS captured would make the daemon claim it applied
+ * something it did not, which is worse than saying restart.
+ */
+export const HOT_SWAPPABLE = Object.freeze(['agentCommands', 'grantable', 'acceptsRulesFromConsole']);
+
+/**
+ * The legacy spelling of one key, read as the current one — so a config that
+ * says `agentCommand: "claude"` is not reported as differing from one that
+ * says `agentCommands: ["claude"]`. runner.mjs's `readConfig` makes the same
+ * move; this is it applied to a raw file rather than a booted config.
+ */
+export function normaliseConfigFile(file) {
+  const { agentCommand, ...rest } = file ?? {};
+  if (agentCommand !== undefined && rest.agentCommands === undefined) {
+    rest.agentCommands = [agentCommand];
+  }
+  return rest;
+}
+
+/**
+ * The keys a restart would change: everything that differs between what the
+ * daemon booted with and what the file says now, minus {@link HOT_SWAPPABLE}.
+ *
+ * Compared against the BOOTED file and not the last one read, so an edit
+ * somebody reverts by hand clears the notice by itself. Values are compared
+ * with a key-sorted stringify, because `{workspaces: [...], name}` and
+ * `{name, workspaces: [...]}` are one config. Names only, never values: the
+ * answer is shown in a footer and logged, and the token is one of the keys.
+ *
+ * @returns {string[]} sorted, empty when nothing needs a restart
+ */
+export function restartNeededFor(booted, file) {
+  const before = normaliseConfigFile(booted);
+  const after = normaliseConfigFile(file);
+  const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+  return [...keys]
+    .filter((key) => !HOT_SWAPPABLE.includes(key))
+    .filter((key) => canonical(before[key]) !== canonical(after[key]))
+    .sort();
+}
+
+/** Applied, or would be on a SIGHUP: the hot-swappable keys that differ. */
+export function reloadableFor(booted, file) {
+  const before = normaliseConfigFile(booted);
+  const after = normaliseConfigFile(file);
+  return HOT_SWAPPABLE.filter((key) => canonical(before[key]) !== canonical(after[key]));
+}
+
+/** JSON with object keys in one order, so two spellings of one value agree. */
+function canonical(value) {
+  if (value === undefined) return 'undefined';
+  return JSON.stringify(value, (_, inner) => (
+    inner && typeof inner === 'object' && !Array.isArray(inner)
+      ? Object.fromEntries(Object.keys(inner).sort().map((key) => [key, inner[key]]))
+      : inner
+  ));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cawdev-cli",
-  "version": "1.0.2-beta",
+  "version": "1.0.3-beta",
   "description": "cawdev's terminal client and runner daemon — zero dependencies, on purpose",
   "type": "module",
   "bin": {

package/runner/README.md

@@ -138,15 +138,31 @@ travels beside the secret since this card, and a machine set up before it
 falls back to a lookup by label the first time this runs, after which it
 remembers.
 
-Adding a project or a workspace needs a restart to take effect, same as any
-other change to `"projects"` — a live daemon says so. Enabling or disabling an
-agent and turning `rules` on or off do **not**: `cawdev config` — and the `c`
-screen, through the pid the hello names — sends the running daemon a `SIGHUP`,
-which re-reads just those three settings from the file and updates what the
-hello advertises, so the next `c` shows the new state. That is a unix convention asked of a process this operator already
-owns, not a command sent over the control socket in `attach.mjs` — that socket
-is deliberately read-only (see its own header), and a config change is not an
-exception carved into it.
+**What takes effect when** (R294). Three settings a running daemon takes
+without a restart — `agentCommands`, `grantable`, `acceptsRulesFromConsole`,
+the `HOT_SWAPPABLE` list in `tools/lib/runner-config.mjs`, spelled once —
+because the daemon reads them fresh on every use. Everything else in the file
+(`projects` and their workspaces, `url`, `name`, the token, `browser`, the
+tuning) is read once at boot. Every change made by either door ends the same
+way: the running daemon is sent a `SIGHUP` (through the pid the hello names —
+a unix convention asked of a process this operator already owns, not a command
+over the control socket in `attach.mjs`, which is deliberately read-only), it
+re-reads the file, applies what it can, and **says what it could not**: the
+hello carries `restartNeeded`, the keys the file has moved on from since boot
+that only a restart applies, and `configReadAt`. The door waits for that
+re-read and repeats the daemon's own verdict — "applied, no restart needed",
+or "needs a restart to pick up `projects` — q, then cawdev". A daemon too old
+to answer gets the door's own reading of the same function.
+
+While `restartNeeded` is non-empty the attached terminal pins a row in its
+footer — `! config changed: projects — restart to apply (q, then cawdev)` — and
+the `c` screen names what is in the file and not yet served ("serves cawdev ·
+dycrypt after a restart", "cawdev: 1, 2 after a restart"). It is compared
+against the file the daemon **booted** with, not the last one it read, so an
+edit reverted by hand clears it. And it is off the file's own mtime, checked
+on every heartbeat: a change made in an editor with nobody signalling anything
+reaches the footer within thirty seconds. A notice, never a restart — the
+daemon says, a person decides.
 
 ### What it shows you
 

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,
+  RESTART_FROM_ATTACH, addProject, addWorkspace, agentsOf, pathsOf, readConfigFile, reloadIfRunning,
   setAcceptsRulesFromConsole, setAgentEnabled, 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,
@@ -694,12 +709,27 @@ 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' }
@@ -959,6 +989,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 +2162,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 +2185,46 @@ 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 === '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

@@ -32,6 +32,7 @@ import {
   addProject, addWorkspace, readConfigFile, reloadIfRunning, setAcceptsRulesFromConsole,
   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';
@@ -461,19 +462,25 @@ export async function pickAction(ask, say, pick = askOne) {
   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,34 +488,19 @@ 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.')}`);
-  }
-}
-
 /** The config as somebody would want to read it back — never the secret. */
 export function printConfig(file, ink, say) {
   const shown = { ...file };

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,28 @@ export async function setAcceptsRulesFromConsole({
 }
 
 /**
- * The pid of a daemon running on this exact config, or null.
+ * 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 +392,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 +401,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 };
 }

package/runner/runner.mjs

@@ -38,6 +38,7 @@ import {
 import { capabilityIn, describeCall } from '../lib/tool-line.mjs';
 import { findSecret } from '../lib/secrets.mjs';
 import { cliVersion, isBelow } from '../lib/version.mjs';
+import { reloadableFor, restartNeededFor } from '../lib/runner-config.mjs';
 
 // --- configuration -----------------------------------------------------------
 
@@ -409,6 +410,14 @@ async function readConfig() {
      * daemon's cwd is not the terminal's: `cawdev` starts it detached.
      */
     configPath: fromFile ? resolve(path) : null,
+    /**
+     * The file as it was when this daemon booted — R294. What every later
+     * reading is compared against, so the daemon can say which of its
+     * settings the file has moved on from and only a restart would apply.
+     * The RAW file, not `config`: the question is what the operator changed,
+     * and defaults filled in here are not something they wrote.
+     */
+    bootedFile: fromFile ? file : null,
   };
 
   if (!config.token) {
@@ -7659,6 +7668,11 @@ async function main() {
     // inventing a file.
     agents: [...config.agentCommands],
     configPath: config.configPath,
+    // R294: the keys the file has moved on from since boot that only a restart
+    // would apply — nothing, at boot, by definition — and when the file was
+    // last read, so a door that just signalled can wait for a fresh answer.
+    restartNeeded: [],
+    configReadAt: new Date().toISOString(),
     // R81. `cawdev` starts a daemon for you when it finds none, and
     // quitting the UI leaves it running — it is driving sessions. A
     // background process you did not know you started is the cost of that
@@ -7668,45 +7682,88 @@ async function main() {
   };
 
   // R283. `cawdev config agent enable/disable` and `cawdev config rules
-  // on/off` write the file and, if a daemon is running on it, send this — NOT
+  // on/off` write the file and, if a daemon is running on it, send SIGHUP — NOT
   // a control-socket command. `control.mjs` is deliberately read-only ("no
   // command can" change anything, so a person acting through it never gets
   // more than their own HTTPS session already grants); SIGHUP is a unix
   // convention for "re-read your config", asked of a process this operator
   // already owns, so it does not open that door. Only the settings that are
-  // genuinely safe to hot-swap: `agentCommands`, `grantable` and
-  // `acceptsRulesFromConsole` are read fresh from `config` on every use
-  // (spawn, or the next heartbeat), never captured once at boot — so mutating
+  // genuinely safe to hot-swap — `HOT_SWAPPABLE`, in lib/runner-config.mjs,
+  // the ONE spelling of that list — are applied: `agentCommands`, `grantable`
+  // and `acceptsRulesFromConsole` are read fresh from `config` on every use
+  // (spawn, or the next heartbeat), never captured once at boot, so mutating
   // them here is enough, with no further plumbing.
-  process.on('SIGHUP', async () => {
-    const path = configPathFromArgv();
+  //
+  // R294: and the daemon SAYS what it could not apply. Everything else in the
+  // file is read once at boot, and until this a project added to the file was
+  // logged as "nothing changed" — the handler diffed only the three keys it
+  // could swap. `rereadConfig` compares the whole file against the one this
+  // process BOOTED with (not the last one read, so an edit reverted by hand
+  // clears the notice by itself) and publishes the keys only a restart would
+  // apply as `restartNeeded` on the hello, with `configReadAt` so a door that
+  // just signalled can tell a fresh answer from the old one. A notice, never a
+  // restart — R113's rule: the daemon says so, and a person decides. Two
+  // triggers, one function: the signal, and the heartbeat noticing the file's
+  // mtime moved, which is what covers a hand edit with no door at all.
+  let configSeenAt = null;
+  const rereadConfig = async (why) => {
+    const path = config.configPath ?? configPathFromArgv();
     try {
+      // The mtime first, so a re-read on a signal is not followed by a second
+      // one on the next beat for the same write.
+      configSeenAt = (await stat(path).catch(() => null))?.mtimeMs ?? configSeenAt;
       const file = JSON.parse(await readFile(path, 'utf8'));
-      const before = {
-        acceptsRulesFromConsole: config.acceptsRulesFromConsole,
-        grantable: config.grantable,
-        agentCommands: config.agentCommands,
+      // What the three keys RESOLVE to, defaults filled in as `readConfig`
+      // fills them, so a key the file omits is not reported as a change.
+      const resolved = {
+        acceptsRulesFromConsole: file.acceptsRulesFromConsole ?? DEFAULTS.acceptsRulesFromConsole,
+        grantable: file.grantable ?? DEFAULTS.grantable,
+        agentCommands: file.agentCommands
+          ?? (file.agentCommand ? [file.agentCommand] : null)
+          ?? DEFAULTS.agentCommands,
       };
-      config.acceptsRulesFromConsole =
-        file.acceptsRulesFromConsole ?? DEFAULTS.acceptsRulesFromConsole;
-      config.grantable = file.grantable ?? DEFAULTS.grantable;
-      config.agentCommands = file.agentCommands
-        ?? (file.agentCommand ? [file.agentCommand] : null)
-        ?? DEFAULTS.agentCommands;
+      const applied = reloadableFor({
+        agentCommands: config.agentCommands,
+        grantable: config.grantable,
+        acceptsRulesFromConsole: config.acceptsRulesFromConsole,
+      }, resolved);
+      Object.assign(config, resolved);
       // R288: the hello describes the current state, not the booted one — an
       // attach opened after a toggle would otherwise offer to turn on what is
       // already on. The same object `serveControl` sends, mutated in place.
       advertised.acceptsConsoleRules = config.acceptsRulesFromConsole === true;
       advertised.agents = [...config.agentCommands];
-      const changed = Object.keys(before)
-        .filter((key) => JSON.stringify(before[key]) !== JSON.stringify(config[key]));
-      log(changed.length
-        ? `re-read ${path} on SIGHUP — changed: ${changed.join(', ')}`
-        : `re-read ${path} on SIGHUP — nothing changed`);
+      advertised.restartNeeded = config.bootedFile ? restartNeededFor(config.bootedFile, file) : [];
+      advertised.configReadAt = new Date().toISOString();
+      const said = [
+        applied.length ? `applied: ${applied.join(', ')}` : null,
+        advertised.restartNeeded.length ? `needs restart: ${advertised.restartNeeded.join(', ')}` : null,
+      ].filter(Boolean);
+      log(`re-read ${path} on ${why} — ${said.length ? said.join('; ') : 'nothing changed'}`);
     } catch (failure) {
-      log(`SIGHUP re-read of ${path} failed: ${failure.message}`);
+      log(`${why} re-read of ${path} failed: ${failure.message}`);
     }
-  });
+    // A terminal already attached got its hello before this; the daemon tells
+    // it rather than waiting for the next attach. An older client ignores an
+    // event type it does not know.
+    control?.publish({ type: 'runner', runner: advertised });
+  };
+  process.on('SIGHUP', () => rereadConfig('SIGHUP'));
+
+  // The heartbeat's half of R294: the file's mtime, read once per beat, and a
+  // re-read when it moved. `stat` and nothing more when it did not, which is
+  // what makes this affordable every thirty seconds. Skipped for a daemon
+  // booted from the environment alone — there is no file to have changed.
+  configSeenAt = config.configPath ? (await stat(config.configPath).catch(() => null))?.mtimeMs ?? null : null;
+  const noticeConfigEdits = async () => {
+    if (!config.configPath) return;
+    const seen = (await stat(config.configPath).catch(() => null))?.mtimeMs ?? null;
+    if (seen === null || seen === configSeenAt) return;
+    // `rereadConfig` records the mtime before it reads: a file caught
+    // mid-write fails to parse, and the write that finishes it moves the
+    // mtime again.
+    await rereadConfig('edit');
+  };
 
   // R52. Nothing here is load-bearing for running an agent, so a daemon that
   // cannot open a socket says so and carries on: trading the ability to run
@@ -7814,7 +7871,7 @@ async function main() {
           : [];
       }
     }).catch((failure) => log(`heartbeat failed: ${failure.message}`));
-    await Promise.all([workspacesReported, heartbeatAnswered]);
+    await Promise.all([workspacesReported, heartbeatAnswered, noticeConfigEdits()]);
   };
 
   await beat();