@detergent-software/conductor 1.0.0-dev.1 → 1.0.0-dev.11

package/build/cli.js

@@ -1,20 +1,35 @@
 #!/usr/bin/env node
-import { mkdirSync, realpathSync } from 'node:fs';
-import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import { mkdirSync, readFileSync, realpathSync } from 'node:fs';
 import { resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { z } from 'zod';
-import { callApi, NotRunningError, readEndpoint } from "./client.js";
+import { callApi, NotRunningError, ping, readEndpoint } from "./client.js";
+import { loadConfig } from "./config.js";
 import { startDaemon } from "./daemon.js";
 import { ConductorError } from "./errors.js";
-import { readPid } from "./lock.js";
+import { eventsCommand } from "./events.js";
+import { inboxLines } from "./inbox.js";
+import { parseJsonc } from "./jsonc.js";
+import { processAlive, readPid } from "./lock.js";
 import { fleetWorkerSchema } from "./manager.js";
+import { installMod, removeMod } from "./mod.js";
+import { noteCommand } from "./note.js";
+import { notifyLines, notifyStatusSchema, parseUntil, testResultSchema } from "./notify.js";
+import { overrideViewSchema, PAUSE } from "./overrides.js";
 import { conductorPaths } from "./paths.js";
 import { registerProject } from "./registry.js";
-import { installStartup, removeStartup, TASK_NAME } from "./startup.js";
-import { openStore, projectSchema, workerSchema } from "./store.js";
+import { rulesLines, rulesService, rulesTestResultSchema, rulesViewSchema, testLines } from "./rules-service.js";
+import { resolveUntil } from "./rules.js";
+import { outputOf, run } from "./run.js";
+import { queueLines, queueViewSchema } from "./scheduler.js";
+import { formatTokens } from "./spend.js";
+import { installStartup, removeStartup, runStartup, startupRunsCli, TASK_NAME } from "./startup.js";
+import { inboxItemSchema, openStore, projectSchema, waitSchema, workerSchema } from "./store.js";
+import { parseTag, upgrade } from "./upgrade.js";
 import { waitCommand } from "./wait.js";
+import { whyLines, whySchema } from "./why.js";
 const USAGE = `Usage: conduct <command>
 
   serve                     run the daemon in this process (one per machine)
@@ -26,6 +41,37 @@ const USAGE = `Usage: conduct <command>
       [--project <name>] [--probe] [--prompt <text>] [--conductor <name>]
   retire <worker> [--force] stop a worker, remove its worktree and session; refuses unfinished work
   attach <worker>           wake a parked worker (no event text) and open it in a tab
+  inbox [--json]            what waits on you: each open item with its commands and links
+  approve <item> [--text <text>]
+                            approve a plan: post "approve" on the item as you, wake its worker;
+                            <item> is ATK-312, or the inbox item's id as #12
+  revise <item> <text>      ask for a revised plan: post "revise: <text>", wake its worker
+  done <id>                 mark an inbox item done (a physical action, or one you handled)
+  notify [--json]           the notification profile, quiet hours, and each channel's state
+  notify profile [<name>] [--until <when>]
+                            switch the profile now (built in: default, away, focus); --until 17:00 or
+                            a date and time hands back to the one before it then
+  notify test [--kind <kind>] [--channel remote-control|pushover] [--raise]
+                            push a sample item (default npm-otp) on the profile's channels now;
+                            --raise puts a real item in the inbox instead (quiet hours, reminders)
+  queue [--json] [--fresh]  what the scheduler picks next and why the rest wait (--fresh: read now)
+  pause [<project>] [--until <when>]
+                            no new launches in the project (every project without one), until
+                            17:00, tomorrow, monday or a date and time; unpause ends it
+  unpause [<project>]       launch again
+  focus <project> [--slots <n>] [--weight <n>] --until <when>
+                            the project's slots or ordering weight, for a while
+  why <event id | item> [--json]
+                            the rule behind an action, and the events that led to it
+  rules [--json]            the rules in force (project, machine, built-in defaults), what replaces
+                            what, and any rules file refused; machine rules are ~/.conductor/rules.json
+  rules test <file> [--json]
+                            dry-run the rules on a sample, a JSON file such as
+                            { "event": "pr.comment", "project": "atk", "fields": { "wait.kind": "merge" } }
+                            (no event: a state rule's subject); acts on nothing
+  note <item> <file>        post the file as a phase note on the item ("## <work skill> · <Phase>"), and
+                            record its phase on the worker (this checkout's, or --worker <worker>);
+                            exit 3 when nobody posted it (no conductor, or the tracker refused it)
   wait <condition>          wait for an outside event: in a worker's worktree with the daemon
                             running, register it and end the turn (the daemon resumes the session);
                             otherwise check it here and block (exit 0 when it holds, 2 at --timeout)
@@ -35,15 +81,29 @@ const USAGE = `Usage: conduct <command>
       health <env> --version <x> | --commit <sha>
       approval [<item>]       an approve / revise: comment after the item's newest Plan note
       item <item> <state> | item <item> label|note <value>
-      time <when>             such as 2026-10-10T09:00 (local)
+      time <when>             such as 17:00 (the next one) or 2026-10-10T09:00 (local)
       <full form>             such as pr:ado:Emergent.AgenticToolkit#1850:merged
       [--local] [--timeout <minutes, local only; 29>] [--worker <worker>] [--item <item>]
+  events [--since <id>]     the event log after <id> (all of it without), one JSON event per line
+  events --follow [--since <id>]
+                            keep following it (live without --since), reconnecting when the
+                            conductor restarts; state lines conduct.connected / conduct.disconnected
   install-startup           start the daemon at logon (Windows Task Scheduler)
   install-startup --remove  remove that logon task
+  install-mod               install the conductor mod in Claude Code (user scope) from this package:
+                            the status line in every session, the inbox band, pane and commands in
+                            the console (a session started with CONDUCTOR_CONSOLE=1)
+  install-mod --remove      uninstall it
+  upgrade [--tag dev|latest] stop the daemon, npm install the newest version on the tag (default:
+                            the tag the installed version came from), start the daemon again
+      [--allow-downgrade]     install the tag's version even when it is older than the installed one
 
 A <worker> is its item (ATK-309) or its name (probe-ATK-309).
 Files live in ~/.conductor (CONDUCTOR_HOME overrides it).`;
 const STOP_WAIT_MS = 10_000;
+// A restarted daemon opens its store and binds the port; under the logon task node starts cold.
+const START_WAIT_MS = 30_000;
+const NPM_INSTALL_TIMEOUT_MS = 5 * 60_000;
 // A launch makes a worktree (pnpm install) before the session starts.
 const LAUNCH_WAIT_MS = 15 * 60_000;
 // The daemon's worst cases, so the CLI never gives up on an operation that still runs: retire
@@ -51,6 +111,8 @@ const LAUNCH_WAIT_MS = 15 * 60_000;
 // attach waits out the settle time (up to 5 min), resumes (120 s) and opens the tab (60 s).
 const RETIRE_TIMEOUT_MS = 12 * 60_000;
 const ATTACH_TIMEOUT_MS = 9 * 60_000;
+// Approve and revise ask Linear twice (the issue, then the comment), each within 20 s.
+const ANSWER_TIMEOUT_MS = 60_000;
 const projectsBody = z.object({ projects: z.array(projectSchema) });
 const addBody = z.object({ created: z.boolean(), project: projectSchema });
 const errorBody = z.object({ details: z.array(z.string()).optional(), error: z.string() });
@@ -70,6 +132,13 @@ const retireBody = z.object({
     worker: workerSchema,
 });
 const attachBody = z.object({ resumed: z.boolean(), tab: z.string().nullable(), worker: workerSchema });
+const inboxBody = z.object({ items: z.array(inboxItemSchema) });
+const answerBody = z.object({
+    comment: z.object({ id: z.string(), url: z.string().nullable() }).nullable(),
+    item: inboxItemSchema,
+    waits: z.array(waitSchema),
+});
+const answerRefusal = z.object({ details: z.array(z.string()).optional(), error: z.string(), posted: z.enum(['no', 'unknown']).optional() });
 async function addProject(paths, path) {
     const absolute = resolve(path);
     let result;
@@ -80,10 +149,38 @@ async function addProject(paths, path) {
         if (!(error instanceof NotRunningError))
             throw error;
         // No daemon: write the store directly. The daemon reads it when it starts.
-        result = withStore(paths, (store) => registerProject(store, absolute));
+        // Its rules are checked against config.json here too, as the daemon would.
+        const check = rulesService({ config: loadConfig(paths.config), listProjects: () => [], paths }).checkProfile;
+        result = withStore(paths, (store) => registerProject(store, absolute, check));
     }
     out(`${result.created ? 'registered' : 'updated'} ${projectLine(result.project).trim()}`);
 }
+// `conduct approve|revise|done`: Jason's answer to an inbox item, by id, or for approve and revise
+// by the item whose plan waits.
+async function answer(paths, ref, request) {
+    const target = request.action === 'done' ? inboxId(ref) : await planItem(paths, ref);
+    const { body, status } = await callApi(paths, { body: request, method: 'POST', path: `/inbox/${target}/resolve`, timeoutMs: ANSWER_TIMEOUT_MS });
+    if (status !== 200) {
+        const refusal = answerRefusal.safeParse(body).data;
+        const details = [...(refusal?.details ?? [])];
+        if (status === 502 && refusal?.posted === 'unknown')
+            details.push('the comment may be on the item already: look before answering again');
+        if (status === 404) {
+            if ((await openItems(paths)) === null)
+                throw noInbox();
+            throw new ConductorError(`no inbox item #${target}`, ['`conduct inbox` lists the open ones']);
+        }
+        throw new ConductorError(refusal?.error ?? `the API answered ${status}`, details);
+    }
+    const result = answerBody.parse(body);
+    const { item } = result;
+    if (request.action === 'done')
+        return out(`done: #${item.id} (${item.kind}${item.item ? ` ${item.item}` : ''})`);
+    out(`${request.action === 'approve' ? 'approved' : 'asked for a revision of'} ${item.item ?? `#${item.id}`}: ${result.comment?.url ?? result.comment?.id ?? 'comment posted'}`);
+    out(result.waits.length > 0
+        ? `its worker's approval wait resolved; the conductor resumes it`
+        : 'no worker waits on its approval here: the worker reads the comment when it next looks');
+}
 async function attach(paths, ref) {
     const worker = await findWorker(paths, ref);
     const result = attachBody.parse(await expectOk(callApi(paths, { method: 'POST', path: `/workers/${worker.id}/attach`, timeoutMs: ATTACH_TIMEOUT_MS })));
@@ -91,6 +188,26 @@ async function attach(paths, ref) {
     if (result.tab)
         out(`no tab (${result.tab}); open it yourself: claude attach ${result.worker.handle ?? worker.name}`);
 }
+// The pid of the daemon once it answers /health, for upgrade's restart.
+async function awaitDaemon(paths) {
+    const deadline = Date.now() + START_WAIT_MS;
+    while (Date.now() < deadline) {
+        const pid = readPid(paths.pid);
+        if (pid !== null && (await ping(paths, pid)))
+            return pid;
+        await sleep(250);
+    }
+    throw new ConductorError(`the conductor did not answer within ${START_WAIT_MS / 1000} s`, [`see ${paths.log}`]);
+}
+// `conduct events`: until Ctrl+C with --follow.
+async function events(paths, follow, since) {
+    if (since !== undefined && !/^\d+$/.test(since))
+        throw new ConductorError('--since takes an event id, such as --since 120');
+    const stop = new AbortController();
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGBREAK'])
+        process.once(signal, () => stop.abort());
+    await eventsCommand(paths, { follow, since: since === undefined ? undefined : Number(since) }, { out, signal: stop.signal });
+}
 async function expectOk(call) {
     const { body, status } = await call;
     if (status >= 200 && status < 300)
@@ -109,13 +226,22 @@ async function findWorker(paths, ref) {
         throw new ConductorError(`no worker "${ref}" in flight`, ['`conduct status` lists them']);
     throw new ConductorError(`"${ref}" names several workers`, matches.map((w) => `${w.name} in ${w.project}`));
 }
-// 1234 → 1.2k, 3_400_000 → 3.4M.
-function formatTokens(tokens) {
-    if (tokens >= 1_000_000)
-        return `${(tokens / 1_000_000).toFixed(1)}M`;
-    if (tokens >= 1_000)
-        return `${(tokens / 1_000).toFixed(1)}k`;
-    return String(tokens);
+async function inbox(paths, json) {
+    const items = await openItems(paths);
+    if (items === null)
+        throw noInbox();
+    if (json)
+        return out(JSON.stringify(items, null, 2));
+    if (items.length === 0)
+        return out('the inbox is empty');
+    inboxLines(items, new Date()).forEach((line) => out(line));
+}
+// An inbox id as `conduct inbox` prints it (#12), or bare (12).
+function inboxId(ref) {
+    const id = /^#?(\d+)$/.exec(ref)?.[1];
+    if (id === undefined)
+        throw new ConductorError(`"${ref}" is not an inbox item id`, ['`conduct inbox` lists them as #<id>']);
+    return Number(id);
 }
 function install() {
     const cliPath = realpathSync(fileURLToPath(import.meta.url));
@@ -168,19 +294,41 @@ async function main(argv) {
     // `wait` has options of its own: its --version is a value, not this CLI's version.
     if (argv[0] === 'wait')
         return wait(argv.slice(1));
+    // `revise` takes free text, which option parsing would cut at a word such as --force. Every word
+    // after the item is the text, quoted or not: a cut-off instruction would be posted as Jason's.
+    if (argv[0] === 'revise') {
+        const [ref, ...words] = argv.slice(1);
+        const text = words.join(' ').trim();
+        if (ref === undefined || ref.startsWith('-') || !text)
+            throw new ConductorError('usage: conduct revise <item> "<what to change>"');
+        return answer(conductorPaths(), ref, { action: 'revise', text });
+    }
     const { positionals, values } = parseArgs({
         allowPositionals: true,
         args: argv,
         options: {
+            'allow-downgrade': { type: 'boolean' },
+            channel: { type: 'string' },
             conductor: { type: 'string' },
+            follow: { type: 'boolean' },
             force: { type: 'boolean' },
+            fresh: { type: 'boolean' },
             help: { short: 'h', type: 'boolean' },
             json: { type: 'boolean' },
+            kind: { type: 'string' },
             probe: { type: 'boolean' },
             project: { type: 'string' },
             prompt: { type: 'string' },
+            raise: { type: 'boolean' },
             remove: { type: 'boolean' },
+            since: { type: 'string' },
+            slots: { type: 'string' },
+            tag: { type: 'string' },
+            text: { type: 'string' },
+            until: { type: 'string' },
             version: { short: 'v', type: 'boolean' },
+            weight: { type: 'string' },
+            worker: { type: 'string' },
         },
     });
     const paths = conductorPaths();
@@ -190,10 +338,24 @@ async function main(argv) {
     if (values.help || command === undefined || command === 'help')
         return out(USAGE);
     switch (command) {
+        case 'approve':
+            if (sub === undefined)
+                throw new ConductorError('usage: conduct approve <item> [--text <text>]');
+            return answer(paths, sub, { action: 'approve', ...(values.text?.trim() ? { text: values.text.trim() } : {}) });
         case 'attach':
             if (sub === undefined)
                 throw new ConductorError('usage: conduct attach <worker>');
             return attach(paths, sub);
+        case 'done':
+            if (sub === undefined)
+                throw new ConductorError('usage: conduct done <inbox id>');
+            return answer(paths, sub, { action: 'done' });
+        case 'events':
+            return events(paths, values.follow === true, values.since);
+        case 'inbox':
+            return inbox(paths, values.json === true);
+        case 'install-mod':
+            return values.remove ? removeMod(modDeps()) : installMod(fileURLToPath(new URL('../mod', import.meta.url)), modDeps());
         case 'install-startup':
             return values.remove ? uninstall() : install();
         case 'launch':
@@ -205,12 +367,49 @@ async function main(argv) {
                 project: values.project,
                 prompt: values.prompt,
             });
+        case 'note':
+            if (sub === undefined || arg === undefined)
+                throw new ConductorError('usage: conduct note <item> <file> [--worker <worker>]');
+            process.exitCode = await noteCommand(paths, sub, arg, { worker: values.worker }, {
+                cwd: process.cwd(),
+                err: (line) => process.stderr.write(`${line}\n`),
+                out,
+            });
+            return;
+        case 'notify':
+            if (sub === undefined)
+                return notifyStatus(paths, values.json === true);
+            if (sub === 'profile')
+                return notifyProfile(paths, arg, values.until);
+            if (sub === 'test')
+                return notifyTest(paths, { channel: values.channel, kind: values.kind, raise: values.raise === true });
+            throw new ConductorError('usage: conduct notify | conduct notify profile [<name>] [--until <when>] | conduct notify test');
         case 'project':
             if (sub === 'add' && arg !== undefined)
                 return addProject(paths, arg);
             if (sub === 'list')
                 return listProjects(paths, values.json === true);
             throw new ConductorError('usage: conduct project add <path> | conduct project list');
+        case 'focus':
+            if (sub === undefined || values.until === undefined)
+                throw new ConductorError('usage: conduct focus <project> [--slots <n>] [--weight <n>] --until <when>');
+            return override(paths, {
+                action: 'focus',
+                project: sub,
+                ...(values.slots === undefined ? {} : { slots: wholeNumber('--slots', values.slots) }),
+                until: untilOf(values.until),
+                ...(values.weight === undefined ? {} : { weight: wholeNumber('--weight', values.weight) }),
+            });
+        case 'pause':
+            return override(paths, { action: 'pause', ...(sub === undefined ? {} : { project: sub }), ...(values.until === undefined ? {} : { until: untilOf(values.until) }) });
+        case 'queue':
+            return queue(paths, values.json === true, values.fresh === true);
+        case 'rules':
+            if (sub === undefined)
+                return rules(paths, values.json === true);
+            if (sub === 'test' && arg !== undefined)
+                return rulesTest(paths, arg, values.json === true);
+            throw new ConductorError('usage: conduct rules [--json] | conduct rules test <file> [--json]');
         case 'retire':
             if (sub === undefined)
                 throw new ConductorError('usage: conduct retire <worker> [--force]');
@@ -220,18 +419,139 @@ async function main(argv) {
         case 'status':
             return status(paths, values.json === true);
         case 'stop':
-            return stop(paths);
+            await stopDaemon(paths);
+            return;
+        case 'unpause':
+            return override(paths, { action: 'unpause', ...(sub === undefined ? {} : { project: sub }) });
+        case 'upgrade':
+            return upgradeCommand(paths, values.tag, values['allow-downgrade'] === true);
+        case 'why':
+            if (sub === undefined)
+                throw new ConductorError('usage: conduct why <event id | item>');
+            return why(paths, sub, values.json === true);
         default:
             throw new ConductorError(`unknown command "${command}"`, ['run `conduct help` for the commands']);
     }
 }
+function modDeps() {
+    return { claude: (args) => run('claude', args, { timeoutMs: 120_000 }), out };
+}
+function noInbox() {
+    return olderDaemon('no inbox');
+}
+// GET /notify, or a ConductorError from a daemon older than the notifier.
+async function notifyAnswer(paths, request) {
+    const answer = await callApi(paths, request);
+    if (answer.status === 404)
+        throw olderDaemon('no notifier');
+    return expectOk(Promise.resolve(answer));
+}
+// `conduct notify profile`: the active profile, or switch to <name>.
+async function notifyProfile(paths, name, until) {
+    if (name === undefined) {
+        if (until !== undefined)
+            throw new ConductorError('usage: conduct notify profile <name> --until <when>');
+        return notifyStatus(paths, false);
+    }
+    const body = { name, ...(until === undefined ? {} : { until: parseUntil(until, new Date()).toISOString() }) };
+    const status = notifyStatusSchema.parse(await notifyAnswer(paths, { body, method: 'POST', path: '/notify/profile' }));
+    notifyLines(status).forEach((line) => out(line));
+}
+async function notifyStatus(paths, json) {
+    const status = notifyStatusSchema.parse(await notifyAnswer(paths, { method: 'GET', path: '/notify' }));
+    if (json)
+        return out(JSON.stringify(status, null, 2));
+    notifyLines(status).forEach((line) => out(line));
+}
+async function notifyTest(paths, options) {
+    if (options.raise && options.channel)
+        throw new ConductorError('--raise routes the item by the profile; it takes no --channel');
+    const body = { ...(options.channel ? { channel: options.channel } : {}), ...(options.kind ? { kind: options.kind } : {}), raise: options.raise };
+    // Pushover can take its 15 s, after a Credential Manager read.
+    const answer = await notifyAnswer(paths, { body, method: 'POST', path: '/notify/test', timeoutMs: 60_000 });
+    if (options.raise) {
+        const { item } = z.object({ item: inboxItemSchema }).parse(answer);
+        return out(`raised inbox item #${item.id} (${item.kind}); \`conduct done ${item.id}\` clears it`);
+    }
+    const result = testResultSchema.parse(answer);
+    if (result.channels.length === 0)
+        return out(`profile ${result.profile} sends a ${body.kind ?? 'npm-otp'} item nowhere`);
+    out(`profile ${result.profile}${result.quietNow ? ' (quiet hours now: a real item would wait for the summary)' : ''}`);
+    result.results.forEach((r) => out(`  ${r.channel}: ${r.ok ? 'ok' : 'failed'}: ${r.detail}`));
+    if (result.results.some((r) => !r.ok))
+        process.exitCode = 1;
+}
+// npm is a .cmd shim on Windows, which starts through a shell alone. The only argument from input is
+// the tag, which parseTag limits to dev or latest.
+function npm(args, timeoutMs) {
+    return run('npm', args, { shell: process.platform === 'win32', timeoutMs });
+}
+function olderDaemon(what) {
+    return new ConductorError(`the running conductor has ${what}: it is older than this conduct`, [
+        'restart it on this build: conduct stop, then conduct serve (or conduct upgrade)',
+    ]);
+}
+// The open inbox items, or null from a daemon older than the inbox (a linked build ahead of it).
+async function openItems(paths) {
+    const answer = await callApi(paths, { method: 'GET', path: '/inbox' });
+    if (answer.status === 404)
+        return null;
+    return inboxBody.parse(await expectOk(Promise.resolve(answer))).items;
+}
 function out(line) {
     process.stdout.write(`${line}\n`);
 }
+// `conduct pause|unpause|focus`: an override that ends on its own (unpause ends a pause).
+async function override(paths, body) {
+    const answer = await callApi(paths, { body: { ...body, by: `conduct ${String(body.action)}` }, method: 'POST', path: '/overrides' });
+    if (answer.status === 404)
+        throw olderDaemon('no overrides');
+    const { overrides, set } = z.object({ overrides: z.array(overrideViewSchema), set: z.array(overrideViewSchema) }).parse(await expectOk(Promise.resolve(answer)));
+    const untilOfView = (o) => (o.until === null ? ' until you unpause' : ` until ${new Date(o.until).toLocaleString()}`);
+    for (const o of set) {
+        const who = o.project ?? 'every project';
+        if (o.kind === PAUSE)
+            out(o.value === 'on' ? `paused launches in ${who}${untilOfView(o)}` : `launches in ${who} are no longer paused`);
+        else
+            out(`${who}: ${o.kind.replace('focus.', '')} ${o.value}${untilOfView(o)}`);
+    }
+    // A pause of every project still holds a project unpaused on its own.
+    const all = overrides.find((o) => o.kind === PAUSE && o.project === null);
+    if (body.action === 'unpause' && body.project !== undefined && all)
+        out(`but all launches stay paused${untilOfView(all)}: conduct unpause ends that`);
+}
+// The open plan item of `ref`: the item (ATK-312) whose plan waits, or an inbox id written #12. A
+// bare number is refused: it could be an issue's number, and the answer is posted as Jason's.
+async function planItem(paths, ref) {
+    if (ref.startsWith('#'))
+        return inboxId(ref);
+    if (/^\d+$/.test(ref)) {
+        throw new ConductorError(`"${ref}" is ambiguous`, [`name the item, such as ATK-${ref}, or the inbox id as #${ref}`]);
+    }
+    const items = await openItems(paths);
+    if (items === null)
+        throw noInbox();
+    const plans = items.filter((i) => i.kind === 'plan' && i.item?.toUpperCase() === ref.toUpperCase());
+    if (plans.length === 1 && plans[0])
+        return plans[0].id;
+    if (plans.length === 0)
+        throw new ConductorError(`no plan of ${ref} waits in the inbox`, ['`conduct inbox` lists what waits']);
+    throw new ConductorError(`several plans of ${ref} wait`, plans.map((p) => `#${p.id} in ${p.project ?? '?'}: pass #${p.id}`));
+}
 function projectLine(p) {
     const state = p.problem ? `${p.problem}; run \`conduct project add\` again` : p.enabled ? 'enabled' : 'disabled';
     return `  ${p.name}  ${p.root}  (protocol ${p.protocol}, ${state})`;
 }
+async function queue(paths, json, fresh) {
+    // A fresh read asks every project's tracker, within the shared rate budget.
+    const answer = await callApi(paths, { method: 'GET', path: `/queue${fresh ? '?fresh=true' : ''}`, timeoutMs: 120_000 });
+    if (answer.status === 404)
+        throw olderDaemon('no scheduler');
+    const view = queueViewSchema.parse(await expectOk(Promise.resolve(answer)));
+    if (json)
+        return out(JSON.stringify(view, null, 2));
+    queueLines(view).forEach((line) => out(line));
+}
 async function retire(paths, ref, force) {
     const worker = await findWorker(paths, ref);
     const { body, status } = await callApi(paths, {
@@ -259,6 +579,48 @@ async function retire(paths, ref, force) {
     out(`retired ${worker.name}`);
     steps.forEach((s) => out(`  ${s}`));
 }
+// `conduct rules`: from the daemon, or straight from the files when it isn't running.
+async function rules(paths, json) {
+    const view = await rulesAnswer(paths, { method: 'GET', path: '/rules' }, (body) => rulesViewSchema.parse(body), (service) => service.view());
+    if (json)
+        return out(JSON.stringify(view, null, 2));
+    rulesLines(view).forEach((line) => out(line));
+}
+// The daemon's answer, or, when none runs, the same thing worked out here from the files.
+async function rulesAnswer(paths, request, parse, local) {
+    let answer;
+    try {
+        answer = await callApi(paths, request);
+    }
+    catch (error) {
+        if (!(error instanceof NotRunningError))
+            throw error;
+        process.stderr.write('conduct: the conductor is not running; read from the files\n');
+        const config = loadConfig(paths.config);
+        return withStore(paths, (store) => {
+            const service = rulesService({ config, listProjects: () => store.listProjects(), paths });
+            service.reload();
+            return local(service);
+        });
+    }
+    if (answer.status === 404)
+        throw olderDaemon('no rules engine');
+    return parse(await expectOk(Promise.resolve(answer)));
+}
+async function rulesTest(paths, file, json) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        throw new ConductorError(`could not read ${file}`, [String(error)]);
+    }
+    const sample = parseJsonc(text, z.unknown(), file);
+    const result = await rulesAnswer(paths, { body: sample, method: 'POST', path: '/rules/test' }, (body) => rulesTestResultSchema.parse(body), (service) => service.test(sample));
+    if (json)
+        return out(JSON.stringify(result, null, 2));
+    testLines(result).forEach((line) => out(line));
+}
 async function serve(paths) {
     const daemon = await startDaemon(paths, { version: version() });
     out(`conductor listening on 127.0.0.1:${daemon.port} (pid ${process.pid}, home ${paths.home})`);
@@ -290,17 +652,24 @@ async function status(paths, json) {
         return;
     }
     const { workers } = fleetBody.parse(await expectOk(callApi(paths, { method: 'GET', path: '/fleet' })));
+    // A linked build's CLI can be newer than the daemon still running, which has no inbox (null).
+    const items = await openItems(paths);
     const pid = readPid(paths.pid);
     const port = readEndpoint(paths)?.port ?? null;
     if (json)
-        return out(JSON.stringify({ home: paths.home, pid, port, projects, running: true, workers }, null, 2));
+        return out(JSON.stringify({ home: paths.home, inbox: items, pid, port, projects, running: true, workers }, null, 2));
     out(`conductor running (pid ${pid ?? '?'}, port ${port ?? '?'}, home ${paths.home})`);
     out(projects.length === 0 ? 'no projects; add one with `conduct project add <path>`' : 'projects:');
     projects.forEach((p) => out(projectLine(p)));
     out(workers.length === 0 ? 'no workers' : 'workers:');
     workers.forEach((w) => out(workerLine(w)));
+    if (items === null)
+        out('inbox: not in this daemon (restart it to run this build)');
+    else
+        out(items.length === 0 ? 'inbox: empty' : `inbox: ${items.length} open (conduct inbox)`);
 }
-async function stop(paths) {
+// True when it stopped a daemon, false when none ran.
+async function stopDaemon(paths) {
     const pid = readPid(paths.pid);
     try {
         await expectOk(callApi(paths, { method: 'POST', path: '/shutdown' }));
@@ -309,7 +678,7 @@ async function stop(paths) {
         if (!(error instanceof NotRunningError))
             throw error;
         out('the conductor is not running');
-        return;
+        return false;
     }
     const deadline = Date.now() + STOP_WAIT_MS;
     while (readEndpoint(paths) !== null && Date.now() < deadline)
@@ -317,13 +686,56 @@ async function stop(paths) {
     if (readEndpoint(paths) !== null) {
         throw new ConductorError(`the conductor (pid ${pid ?? '?'}) did not stop within ${STOP_WAIT_MS / 1000} s`);
     }
+    // The port file goes before the process ends; a start (the logon task's especially) waits for it.
+    const exitDeadline = Date.now() + STOP_WAIT_MS;
+    while (pid !== null && processAlive(pid) && Date.now() < exitDeadline)
+        await sleep(100);
     out(`stopped the conductor (pid ${pid ?? '?'})`);
+    return true;
 }
 function uninstall() {
     out(removeStartup() ? `removed the "${TASK_NAME}" logon task` : `no "${TASK_NAME}" logon task to remove`);
 }
+// --until: 17:00 (the next one), tomorrow, a day such as monday, or a date and time.
+function untilOf(text) {
+    return resolveUntil({ kind: 'at', text }, new Date()).toISOString();
+}
+async function upgradeCommand(paths, tag, allowDowngrade) {
+    const cliPath = realpathSync(fileURLToPath(import.meta.url));
+    await upgrade({ allowDowngrade, tag: parseTag(tag) }, {
+        awaitDaemon: () => awaitDaemon(paths),
+        cliPath,
+        installedVersion: version,
+        npmInstall: (spec) => npm(['install', '--global', spec], NPM_INSTALL_TIMEOUT_MS),
+        npmRoot: async () => {
+            const result = await npm(['root', '--global']);
+            if (result.code !== 0)
+                throw new ConductorError('could not ask npm for its global folder', [outputOf(result)]);
+            return realpathSync(result.stdout.trim());
+        },
+        npmView: async (spec) => {
+            const result = await npm(['view', spec, 'version']);
+            const found = result.stdout.trim();
+            if (result.code !== 0 || found === '')
+                throw new ConductorError(`npm has no ${spec}`, [outputOf(result)]);
+            return found;
+        },
+        out,
+        runTask: runStartup,
+        // A failed start shows as awaitDaemon's timeout. The daemon runs in its home, not in the
+        // caller's directory, which it would hold open (a worktree it may later remove, say).
+        serveDetached: () => spawn(process.execPath, [cliPath, 'serve'], { cwd: paths.home, detached: true, stdio: 'ignore', windowsHide: true })
+            .on('error', () => { })
+            .unref(),
+        stopDaemon: () => stopDaemon(paths),
+        // The logon task's daemon uses ~/.conductor, so it can't restart one kept in CONDUCTOR_HOME.
+        taskRunsCli: () => !process.env.CONDUCTOR_HOME && startupRunsCli(cliPath),
+    });
+}
+// Read from disk each time: upgrade asks again after npm has replaced the package.
 function version() {
-    return z.object({ version: z.string() }).parse(createRequire(import.meta.url)('../package.json')).version;
+    const file = fileURLToPath(new URL('../package.json', import.meta.url));
+    return z.object({ version: z.string() }).parse(JSON.parse(readFileSync(file, 'utf8'))).version;
 }
 async function wait(argv) {
     const { positionals, values } = parseArgs({
@@ -348,6 +760,28 @@ async function wait(argv) {
         throw new ConductorError('usage: conduct wait <condition>', ['run `conduct help` for the conditions']);
     process.exitCode = await waitCommand(conductorPaths(), positionals, { ...values, timeoutMinutes: timeout }, { cwd: process.cwd(), err: (line) => process.stderr.write(`${line}\n`), out });
 }
+function wholeNumber(flag, text) {
+    if (!/^-?\d+$/.test(text))
+        throw new ConductorError(`${flag} takes a whole number, not "${text}"`);
+    return Number(text);
+}
+// `conduct why <event id>`: the rule behind it and its causes. `conduct why <item>`: the same for
+// each of the item's newest actions.
+async function why(paths, ref, json) {
+    const byId = /^#?(\d+)$/.exec(ref)?.[1];
+    const answer = await callApi(paths, { method: 'GET', path: byId === undefined ? `/why?item=${encodeURIComponent(ref)}` : `/why/${byId}` });
+    if (answer.status === 404 && byId !== undefined) {
+        const body = errorBody.safeParse(answer.body);
+        throw body.success && body.data.error === 'not_found' ? new ConductorError(`no event ${byId}`) : olderDaemon('no conduct why');
+    }
+    const body = await expectOk(Promise.resolve(answer));
+    const whys = byId === undefined ? z.object({ items: z.array(whySchema) }).parse(body).items : [whySchema.parse(body)];
+    if (json)
+        return out(JSON.stringify(byId === undefined ? whys : whys[0], null, 2));
+    if (whys.length === 0)
+        return out(`no action on ${ref} was caused by a rule`);
+    whys.forEach((w, i) => [...(i > 0 ? [''] : []), ...whyLines(w)].forEach((line) => out(line)));
+}
 function withStore(paths, use) {
     mkdirSync(paths.home, { recursive: true });
     const store = openStore(paths.db);
@@ -358,12 +792,13 @@ function withStore(paths, use) {
         store.close();
     }
 }
-// One line per worker: name, project, status and session activity, its waits, then spend.
+// One line per worker: name, project, status and session activity, its phase and waits, then spend.
 function workerLine(w) {
     const activity = w.status === 'running' ? `running, ${w.activity}` : w.status;
     const waits = w.waits.map((x) => (x.resolvedAt ? `${x.condition} (resolved)` : x.condition));
     return [
         `  ${w.name}  ${w.project}  ${activity}`,
+        ...(w.phase ? [`phase ${w.phase}`] : []),
         ...(waits.length > 0 ? [`waits: ${waits.join(', ')}`] : []),
         `spend ${formatTokens(w.spend.today)} today, ${formatTokens(w.spend.total)} total`,
     ].join('  ·  ');