@detergent-software/conductor 2.2.0-dev.1 → 2.2.0-dev.3

package/mod/hooks/register.tsx

@@ -1,12 +1,13 @@
-import { atom, read, update } from 'claude-code';
 import type { EngineInterface, Register, RenderElement, Timer } from 'claude-code';
 
+import { atom, read, update } from 'claude-code';
+
 import type { ConductorSnapshot } from '../types';
 
 import {
   age,
-  type ApiAnswer,
   answerText,
+  type ApiAnswer,
   bandEntries,
   clearedText,
   CONSOLE_SKILL,
@@ -65,11 +66,11 @@ const ATTACH_RUN_MS = 10 * 60_000;
 const ANSWER_RUN_MS = 2 * 60_000;
 const NOT_RUNNING = 'the conductor is not running (conduct serve)';
 
-const snapshot = atom({ plugin: 'conductor', key: 'snapshot' } as const, null);
-const confirming = atom({ plugin: 'conductor', key: 'confirming' } as const, null);
-const expanded = atom({ plugin: 'conductor', key: 'expanded' } as const, null);
-const hasSkill = atom({ plugin: 'conductor', key: 'hasSkill' } as const, false);
-const cleared = atom({ plugin: 'conductor', key: 'cleared' } as const, null);
+const snapshot = atom({ key: 'snapshot', plugin: 'conductor' } as const, null);
+const confirming = atom({ key: 'confirming', plugin: 'conductor' } as const, null);
+const expanded = atom({ key: 'expanded', plugin: 'conductor' } as const, null);
+const hasSkill = atom({ key: 'hasSkill', plugin: 'conductor' } as const, false);
+const cleared = atom({ key: 'cleared', plugin: 'conductor' } as const, null);
 
 // The console is the session started with CONDUCTOR_CONSOLE=1 (`conduct console` sets it): only it
 // draws the band and the pane, answers the commands, follows the stream and acts on events. Both
@@ -94,22 +95,70 @@ let isWindows = false;
 
 type Endpoint = { port: number; token: string };
 
-// The running daemon's port and token, from its home's files. Throws when none runs.
-async function endpoint($: EngineInterface): Promise<Endpoint> {
-  const home = homeOf({
-    conductorHome: await $.env.get('CONDUCTOR_HOME'),
-    home: await $.env.get('HOME'),
-    userProfile: await $.env.get('USERPROFILE'),
-  });
-  if (home === null) throw new Error(NOT_RUNNING);
-  let found: Endpoint | null;
+// Jason's answer to an inbox item, as `conduct approve|revise|done` posts it; the line to show.
+// Approve and revise run `conduct` (ANSWER_RUN_MS), by inbox id. Without the CLI, the API, which
+// $.http.fetch cuts off after 30 s, possibly after the comment was posted. Done doesn't ask Linear.
+async function answer(
+  $: EngineInterface,
+  id: number,
+  body: { action: 'approve' | 'done' } | { action: 'revise'; text: string },
+): Promise<string> {
   try {
-    found = endpointOf(await $.fs.read(`${home}/port`), await $.fs.read(`${home}/token`));
-  } catch {
-    found = null;
+    const cli = cliOf($);
+    if (body.action !== 'done' && (await $.fs.exists(cli))) {
+      const failed = `not ${body.action}d`;
+      const argv = body.action === 'revise' ? ['revise', `#${id}`, body.text] : ['approve', `#${id}`];
+      let run;
+      try {
+        run = await $.process.run(['node', cli, ...argv], { timeoutMs: ANSWER_RUN_MS });
+      } catch (error) {
+        return `${failed}: ${error instanceof Error ? error.message : String(error)}`;
+      }
+      refreshSoon($);
+      return runText(run, {
+        failed,
+        ok: `${body.action === 'approve' ? 'approved' : 'asked for a revision of'} #${id}`,
+      });
+    }
+    const at = await endpoint($);
+    let result: ApiAnswer;
+    try {
+      result = await callApi($, 'POST', `/inbox/${id}/resolve`, body, at);
+    } catch (error) {
+      if (body.action === 'done') throw error;
+      return `not ${body.action}d: ${error instanceof Error ? error.message : String(error)}; ${MAYBE_POSTED}`;
+    }
+    refreshSoon($);
+    return answerText(body.action, id, result);
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
+// Starts the console's idle point over: WARM_AFTER_MS from now, unless a turn comes first.
+function armIdle($: EngineInterface): void {
+  idleTimer?.cancel();
+  idleTimer = $.clock.after(WARM_AFTER_MS, () => void onIdle($));
+}
+
+// Through `conduct attach` (ATTACH_RUN_MS), by id: a name is unique only within its project.
+// Without the CLI, the API, which answers within 30 s only when the worker needs no settle time
+// and resumes quickly. The daemon refuses a second attach of a worker while one runs.
+async function attach($: EngineInterface, id: number, name: string): Promise<string> {
+  try {
+    const cli = cliOf($);
+    if (await $.fs.exists(cli)) {
+      $.ui.toast(`attaching to ${name}…`);
+      const run = await $.process.run(['node', cli, 'attach', `#${id}`], { timeoutMs: ATTACH_RUN_MS });
+      refreshSoon($);
+      return runText(run, { failed: `could not attach to ${name}`, ok: `attached to ${name}` });
+    }
+    const result = await callApi($, 'POST', `/workers/${id}/attach`);
+    refreshSoon($);
+    return result.status === 200 ? `attached to ${name}` : `could not attach to ${name}: ${errorOf(result)}`;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
   }
-  if (found === null) throw new Error(NOT_RUNNING);
-  return found;
 }
 
 // One call on the daemon's API (127.0.0.1, with its token). Throws when none runs.
@@ -129,7 +178,7 @@ async function callApi(
     },
     method,
   });
-  let parsed: unknown = null;
+  let parsed: unknown;
   try {
     parsed = answer.text ? JSON.parse(answer.text) : null;
   } catch {
@@ -138,116 +187,90 @@ async function callApi(
   return { body: parsed, status: answer.status };
 }
 
-// Reads /fleet, /inbox and /notify into the state the drawings read.
-async function refresh($: EngineInterface): Promise<ConductorSnapshot> {
-  const readAt = await $.clock.now();
-  let next: ConductorSnapshot;
-  try {
-    const at = await endpoint($);
-    const [fleet, inbox, notify] = await Promise.all([
-      callApi($, 'GET', '/fleet', undefined, at),
-      callApi($, 'GET', '/inbox', undefined, at),
-      callApi($, 'GET', '/notify', undefined, at),
-    ]);
-    next = snapshotOf(fleet, inbox, readAt, notify);
-  } catch (error) {
-    next = {
-      error: error instanceof Error ? error.message : String(error),
-      inbox: [],
-      notify: null,
-      readAt,
-      workers: [],
-    };
-  }
-  await update($, snapshot, () => next);
-  return next;
+// The conductor's own CLI, beside the mod in its package; a mod checkout without a build has none.
+function cliOf($: EngineInterface): string {
+  return `${$.plugin.root}/../build/cli.js`;
 }
 
-// Many events land together (a note raises an item and a wait); one read covers them.
-function refreshSoon($: EngineInterface): void {
-  if (isRefreshing) return;
-  isRefreshing = true;
-  $.clock.after(DEBOUNCE_MS, () => {
-    isRefreshing = false;
-    void refresh($);
-  });
+// Stages a band approve for its `y`; it lapses unless pressed within CONFIRM_MS.
+async function confirm($: EngineInterface, id: number): Promise<void> {
+  await update($, confirming, () => id);
+  $.clock.after(CONFIRM_MS, () => void update($, confirming, (staged) => (staged === id ? null : staged)));
 }
 
-// One line of the follow stream, carried out.
-async function onLine($: EngineInterface, text: string): Promise<void> {
-  const line = parseLine(text);
-  if (line === null) return;
-  if (line.id !== null) lastEventId = line.id;
-  const act = reaction(line);
-  try {
-    switch (act.kind) {
-      case 'disconnected': {
-        const readAt = await $.clock.now();
-        await update($, snapshot, () => ({ error: NOT_RUNNING, inbox: [], notify: null, readAt, workers: [] }));
-        return;
-      }
-      case 'escalate':
-        // The one place the mod wakes the console's model: facts only, as the rules engine wrote them.
-        await $.prompt.submit({ text: act.text });
-        return;
-      case 'ignore':
-        return;
-      case 'push':
-        await push($, act.message);
-        return;
-      case 'refresh':
-        if (act.toast !== null) $.ui.toast(act.toast);
-        refreshSoon($);
-        return;
-      case 'send':
-        await $.session.send({ text: act.text, to: act.to });
-        return;
-    }
-  } catch (error) {
-    $.ui.log(`conductor: ${line.kind} failed: ${error instanceof Error ? error.message : String(error)}`, {
-      to: 'debug',
-    });
-  }
+async function copy(
+  $: EngineInterface,
+  text: string,
+  surface: Parameters<EngineInterface['ui']['copy']>[0]['surface'],
+): Promise<void> {
+  const copied = await $.ui.copy({ surface, text });
+  $.ui.toast(copied.isCopied ? `copied: ${text}` : `not copied: ${text}`);
 }
 
-// Pushes to the phone through PushNotification, tells the daemon what came of it whatever it was
-// (`conduct notify` shows it), and says once in the console when pushes stop reaching the phone
-// (ATK-255): Remote Control off, pushes off in the config, or the call failing.
-async function push($: EngineInterface, message: string): Promise<void> {
-  let outcome: PushOutcome;
-  try {
-    outcome = pushOutcome(await $.tool.call({ message, status: 'proactive', tool: 'PushNotification' }));
-  } catch (error) {
-    outcome = { detail: error instanceof Error ? error.message : String(error), state: 'failed' };
-  }
-  const warning = pushWarning(outcome);
-  if (outcome.state === 'ok') warnedInactive = false;
-  if (warning !== null && !warnedInactive) {
-    warnedInactive = true;
-    $.ui.toast(warning);
-  }
-  try {
-    await callApi($, 'POST', '/notify/report', {
-      channel: 'remote-control',
-      result: outcome.detail,
-      state: reportedState(outcome),
-    });
-  } catch (error) {
-    $.ui.log(`conductor: notify report failed: ${error instanceof Error ? error.message : String(error)}`, {
-      to: 'debug',
-    });
-  }
+function disarmIdle(): void {
+  idleTimer?.cancel();
+  idleTimer = null;
 }
 
-// Starts the console's idle point over: WARM_AFTER_MS from now, unless a turn comes first.
-function armIdle($: EngineInterface): void {
-  idleTimer?.cancel();
-  idleTimer = $.clock.after(WARM_AFTER_MS, () => void onIdle($));
+// The running daemon's port and token, from its home's files. Throws when none runs.
+async function endpoint($: EngineInterface): Promise<Endpoint> {
+  const home = homeOf({
+    conductorHome: await $.env.get('CONDUCTOR_HOME'),
+    home: await $.env.get('HOME'),
+    userProfile: await $.env.get('USERPROFILE'),
+  });
+  if (home === null) throw new Error(NOT_RUNNING);
+  let found: Endpoint | null;
+  try {
+    found = endpointOf(await $.fs.read(`${home}/port`), await $.fs.read(`${home}/token`));
+  } catch {
+    found = null;
+  }
+  if (found === null) throw new Error(NOT_RUNNING);
+  return found;
 }
 
-function disarmIdle(): void {
-  idleTimer?.cancel();
-  idleTimer = null;
+// `conduct events --follow` from this package's own build, so the mod and the CLI are one version
+// and no .cmd shim is in the way. It reconnects by itself; a child that ends is started again after
+// the last event it showed, so nothing in between is lost. One that keeps exiting at once (no
+// build, no node) is given up on, and the poll carries on alone.
+async function follow($: EngineInterface): Promise<void> {
+  const cli = cliOf($);
+  if (!(await $.fs.exists(cli))) {
+    $.ui.log(`conductor: no ${cli}; the console polls instead of following events`, { to: 'debug' });
+    return;
+  }
+  for (let quickExits = 0; quickExits < 3;) {
+    const startedAt = await $.clock.now();
+    let buffer = '';
+    try {
+      // --console: while this stream is open, the daemon knows escalations have a console to wake.
+      const argv = [
+        'node',
+        cli,
+        'events',
+        '--follow',
+        '--console',
+        ...(lastEventId === null ? [] : ['--since', String(lastEventId)]),
+      ];
+      for await (const chunk of $.process.spawn({ argv })) {
+        if (chunk.stream !== 'stdout') continue;
+        buffer += chunk.text;
+        for (let end = buffer.indexOf('\n'); end >= 0; end = buffer.indexOf('\n')) {
+          const text = buffer.slice(0, end).trim();
+          buffer = buffer.slice(end + 1);
+          if (text !== '') await onLine($, text);
+        }
+      }
+    } catch (error) {
+      $.ui.log(`conductor: conduct events failed: ${error instanceof Error ? error.message : String(error)}`, {
+        to: 'debug',
+      });
+    }
+    quickExits = (await $.clock.now()) - startedAt < 10_000 ? quickExits + 1 : 0;
+    await new Promise<void>((done) => $.clock.after(RESTART_MS, done));
+  }
+  $.ui.log('conductor: conduct events keeps exiting; the console polls instead', { to: 'debug' });
 }
 
 // The console has been idle WARM_AFTER_MS: keep its cache warm with a ping, or clear it (ATK-386).
@@ -301,108 +324,57 @@ async function onIdle($: EngineInterface): Promise<void> {
   await reportCache($, { action: outcome.kind, contextTokens: contextTokens ?? null, usage: outcome.usage, warms });
 }
 
-async function reportCache($: EngineInterface, body: Record<string, unknown>): Promise<void> {
-  try {
-    await callApi($, 'POST', '/console/cache', body);
+// One line of the follow stream, carried out.
+async function onLine($: EngineInterface, text: string): Promise<void> {
+  const line = parseLine(text);
+  if (line === null) return;
+  if (line.id !== null) lastEventId = line.id;
+  const act = reaction(line);
+  try {
+    switch (act.kind) {
+      case 'disconnected': {
+        const readAt = await $.clock.now();
+        await update($, snapshot, () => ({ error: NOT_RUNNING, inbox: [], notify: null, readAt, workers: [] }));
+        return;
+      }
+      case 'escalate':
+        // The one place the mod wakes the console's model: facts only, as the rules engine wrote them.
+        await $.prompt.submit({ text: act.text });
+        return;
+      case 'ignore':
+        return;
+      case 'push':
+        await push($, act.message);
+        return;
+      case 'refresh':
+        if (act.toast !== null) $.ui.toast(act.toast);
+        refreshSoon($);
+        return;
+      case 'send':
+        await $.session.send({ text: act.text, to: act.to });
+        return;
+    }
   } catch (error) {
-    $.ui.log(`conductor: console cache report failed: ${error instanceof Error ? error.message : String(error)}`, {
+    $.ui.log(`conductor: ${line.kind} failed: ${error instanceof Error ? error.message : String(error)}`, {
       to: 'debug',
     });
   }
 }
 
-// `/notify <profile> [--until <when>]` and the pane's picker: switch the notification profile.
-async function switchProfile($: EngineInterface, name: string, until: null | string = null): Promise<string> {
+// The Windows terminal's [open]: the default browser, run once (ATK-494). A Link there is an OSC 8
+// span, which a ctrl+click in a pane opened twice: the pane and Windows Terminal each opened it.
+// rundll32 hands the URL over whole (explorer.exe would split it at a comma) and exits 0.
+async function openLink($: EngineInterface, href: string): Promise<void> {
   try {
-    const result = await callApi($, 'POST', '/notify/profile', until === null ? { name } : { name, until });
-    refreshSoon($);
-    return profileText(name, result, await $.clock.now());
-  } catch (error) {
-    return error instanceof Error ? error.message : String(error);
-  }
-}
-
-// `conduct events --follow` from this package's own build, so the mod and the CLI are one version
-// and no .cmd shim is in the way. It reconnects by itself; a child that ends is started again after
-// the last event it showed, so nothing in between is lost. One that keeps exiting at once (no
-// build, no node) is given up on, and the poll carries on alone.
-async function follow($: EngineInterface): Promise<void> {
-  const cli = cliOf($);
-  if (!(await $.fs.exists(cli))) {
-    $.ui.log(`conductor: no ${cli}; the console polls instead of following events`, { to: 'debug' });
-    return;
-  }
-  for (let quickExits = 0; quickExits < 3;) {
-    const startedAt = await $.clock.now();
-    let buffer = '';
-    try {
-      // --console: while this stream is open, the daemon knows escalations have a console to wake.
-      const argv = [
-        'node',
-        cli,
-        'events',
-        '--follow',
-        '--console',
-        ...(lastEventId === null ? [] : ['--since', String(lastEventId)]),
-      ];
-      for await (const chunk of $.process.spawn({ argv })) {
-        if (chunk.stream !== 'stdout') continue;
-        buffer += chunk.text;
-        for (let end = buffer.indexOf('\n'); end >= 0; end = buffer.indexOf('\n')) {
-          const text = buffer.slice(0, end).trim();
-          buffer = buffer.slice(end + 1);
-          if (text !== '') await onLine($, text);
-        }
-      }
-    } catch (error) {
-      $.ui.log(`conductor: conduct events failed: ${error instanceof Error ? error.message : String(error)}`, {
-        to: 'debug',
-      });
-    }
-    quickExits = (await $.clock.now()) - startedAt < 10_000 ? quickExits + 1 : 0;
-    await new Promise<void>((done) => $.clock.after(RESTART_MS, done));
+    const run = await $.process.run(['rundll32.exe', 'url.dll,FileProtocolHandler', href]);
+    if (run.exitCode !== 0) $.ui.toast(`not opened: ${href}`);
+  } catch {
+    $.ui.toast(`not opened: ${href}`);
   }
-  $.ui.log('conductor: conduct events keeps exiting; the console polls instead', { to: 'debug' });
 }
 
-// Jason's answer to an inbox item, as `conduct approve|revise|done` posts it; the line to show.
-// Approve and revise run `conduct` (ANSWER_RUN_MS), by inbox id. Without the CLI, the API, which
-// $.http.fetch cuts off after 30 s, possibly after the comment was posted. Done doesn't ask Linear.
-async function answer(
-  $: EngineInterface,
-  id: number,
-  body: { action: 'approve' | 'done' } | { action: 'revise'; text: string },
-): Promise<string> {
-  try {
-    const cli = cliOf($);
-    if (body.action !== 'done' && (await $.fs.exists(cli))) {
-      const failed = `not ${body.action}d`;
-      const argv = body.action === 'approve' ? ['approve', `#${id}`] : ['revise', `#${id}`, body.text];
-      let run;
-      try {
-        run = await $.process.run(['node', cli, ...argv], { timeoutMs: ANSWER_RUN_MS });
-      } catch (error) {
-        return `${failed}: ${error instanceof Error ? error.message : String(error)}`;
-      }
-      refreshSoon($);
-      return runText(run, {
-        failed,
-        ok: `${body.action === 'approve' ? 'approved' : 'asked for a revision of'} #${id}`,
-      });
-    }
-    const at = await endpoint($);
-    let result: ApiAnswer;
-    try {
-      result = await callApi($, 'POST', `/inbox/${id}/resolve`, body, at);
-    } catch (error) {
-      if (body.action === 'done') throw error;
-      return `not ${body.action}d: ${error instanceof Error ? error.message : String(error)}; ${MAYBE_POSTED}`;
-    }
-    refreshSoon($);
-    return answerText(body.action, id, result);
-  } catch (error) {
-    return error instanceof Error ? error.message : String(error);
-  }
+async function openPane($: EngineInterface): Promise<void> {
+  await $.ui.open({ focus: true, id: PANE, title: TITLE });
 }
 
 // `/pause`, `/unpause`, `/focus-project` and the pane's buttons: an override that ends on its own, as
@@ -419,69 +391,68 @@ async function override($: EngineInterface, command: 'focus' | 'pause' | 'unpaus
   }
 }
 
-// The rule behind an item's newest action (`conduct why <item>`), in one line.
-async function why($: EngineInterface, item: string): Promise<string> {
+// Pushes to the phone through PushNotification, tells the daemon what came of it whatever it was
+// (`conduct notify` shows it), and says once in the console when pushes stop reaching the phone
+// (ATK-255): Remote Control off, pushes off in the config, or the call failing.
+async function push($: EngineInterface, message: string): Promise<void> {
+  let outcome: PushOutcome;
   try {
-    return whyText(item, await callApi($, 'GET', `/why?item=${encodeURIComponent(item)}`));
+    outcome = pushOutcome(await $.tool.call({ message, status: 'proactive', tool: 'PushNotification' }));
   } catch (error) {
-    return error instanceof Error ? error.message : String(error);
+    outcome = { detail: error instanceof Error ? error.message : String(error), state: 'failed' };
+  }
+  const warning = pushWarning(outcome);
+  if (outcome.state === 'ok') warnedInactive = false;
+  if (warning !== null && !warnedInactive) {
+    warnedInactive = true;
+    $.ui.toast(warning);
   }
-}
-
-// The conductor's own CLI, beside the mod in its package; a mod checkout without a build has none.
-function cliOf($: EngineInterface): string {
-  return `${$.plugin.root}/../build/cli.js`;
-}
-
-// Through `conduct attach` (ATTACH_RUN_MS), by id: a name is unique only within its project.
-// Without the CLI, the API, which answers within 30 s only when the worker needs no settle time
-// and resumes quickly. The daemon refuses a second attach of a worker while one runs.
-async function attach($: EngineInterface, id: number, name: string): Promise<string> {
   try {
-    const cli = cliOf($);
-    if (await $.fs.exists(cli)) {
-      $.ui.toast(`attaching to ${name}…`);
-      const run = await $.process.run(['node', cli, 'attach', `#${id}`], { timeoutMs: ATTACH_RUN_MS });
-      refreshSoon($);
-      return runText(run, { failed: `could not attach to ${name}`, ok: `attached to ${name}` });
-    }
-    const result = await callApi($, 'POST', `/workers/${id}/attach`);
-    refreshSoon($);
-    return result.status === 200 ? `attached to ${name}` : `could not attach to ${name}: ${errorOf(result)}`;
+    await callApi($, 'POST', '/notify/report', {
+      channel: 'remote-control',
+      result: outcome.detail,
+      state: reportedState(outcome),
+    });
   } catch (error) {
-    return error instanceof Error ? error.message : String(error);
+    $.ui.log(`conductor: notify report failed: ${error instanceof Error ? error.message : String(error)}`, {
+      to: 'debug',
+    });
   }
 }
 
-async function copy(
-  $: EngineInterface,
-  text: string,
-  surface: Parameters<EngineInterface['ui']['copy']>[0]['surface'],
-): Promise<void> {
-  const copied = await $.ui.copy({ surface, text });
-  $.ui.toast(copied.isCopied ? `copied: ${text}` : `not copied: ${text}`);
-}
-
-// The Windows terminal's [open]: the default browser, run once (ATK-494). A Link there is an OSC 8
-// span, which a ctrl+click in a pane opened twice: the pane and Windows Terminal each opened it.
-// rundll32 hands the URL over whole (explorer.exe would split it at a comma) and exits 0.
-async function openLink($: EngineInterface, href: string): Promise<void> {
+// Reads /fleet, /inbox and /notify into the state the drawings read.
+async function refresh($: EngineInterface): Promise<ConductorSnapshot> {
+  const readAt = await $.clock.now();
+  let next: ConductorSnapshot;
   try {
-    const run = await $.process.run(['rundll32.exe', 'url.dll,FileProtocolHandler', href]);
-    if (run.exitCode !== 0) $.ui.toast(`not opened: ${href}`);
-  } catch {
-    $.ui.toast(`not opened: ${href}`);
+    const at = await endpoint($);
+    const [fleet, inbox, notify] = await Promise.all([
+      callApi($, 'GET', '/fleet', undefined, at),
+      callApi($, 'GET', '/inbox', undefined, at),
+      callApi($, 'GET', '/notify', undefined, at),
+    ]);
+    next = snapshotOf(fleet, inbox, readAt, notify);
+  } catch (error) {
+    next = {
+      error: error instanceof Error ? error.message : String(error),
+      inbox: [],
+      notify: null,
+      readAt,
+      workers: [],
+    };
   }
+  await update($, snapshot, () => next);
+  return next;
 }
 
-// Stages a band approve for its `y`; it lapses unless pressed within CONFIRM_MS.
-async function confirm($: EngineInterface, id: number): Promise<void> {
-  await update($, confirming, () => id);
-  $.clock.after(CONFIRM_MS, () => void update($, confirming, (staged) => (staged === id ? null : staged)));
-}
-
-async function openPane($: EngineInterface): Promise<void> {
-  await $.ui.open({ focus: true, id: PANE, title: TITLE });
+// Many events land together (a note raises an item and a wait); one read covers them.
+function refreshSoon($: EngineInterface): void {
+  if (isRefreshing) return;
+  isRefreshing = true;
+  $.clock.after(DEBOUNCE_MS, () => {
+    isRefreshing = false;
+    void refresh($);
+  });
 }
 
 async function registerCommands($: EngineInterface): Promise<void> {
@@ -526,6 +497,36 @@ async function registerCommands($: EngineInterface): Promise<void> {
   });
 }
 
+async function reportCache($: EngineInterface, body: Record<string, unknown>): Promise<void> {
+  try {
+    await callApi($, 'POST', '/console/cache', body);
+  } catch (error) {
+    $.ui.log(`conductor: console cache report failed: ${error instanceof Error ? error.message : String(error)}`, {
+      to: 'debug',
+    });
+  }
+}
+
+// `/notify <profile> [--until <when>]` and the pane's picker: switch the notification profile.
+async function switchProfile($: EngineInterface, name: string, until: null | string = null): Promise<string> {
+  try {
+    const result = await callApi($, 'POST', '/notify/profile', until === null ? { name } : { name, until });
+    refreshSoon($);
+    return profileText(name, result, await $.clock.now());
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
+// The rule behind an item's newest action (`conduct why <item>`), in one line.
+async function why($: EngineInterface, item: string): Promise<string> {
+  try {
+    return whyText(item, await callApi($, 'GET', `/why?item=${encodeURIComponent(item)}`));
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
 export const register: Register = (on) => {
   on('session.start', async ($, e, next) => {
     const started = await next(e);