@detergent-software/conductor 1.0.0-dev.9 → 1.0.0

package/build/cli.js

@@ -5,79 +5,37 @@ import { resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { z } from 'zod';
+import { briefCommand } from "./brief-cli.js";
+import { heldLocks, lockCommand, lockLine, portsCommand } from "./broker-cli.js";
 import { callApi, NotRunningError, ping, readEndpoint } from "./client.js";
-import { startDaemon } from "./daemon.js";
+import { loadConfig } from "./config.js";
+import { CONSOLE_ARGS, CONSOLE_WINDOW, consoleProject, consoleTabArgs, escalationLines, escalationSchema, handledSchema } from "./console.js";
+import { logCrashes, startDaemon } from "./daemon.js";
 import { ConductorError } from "./errors.js";
 import { eventsCommand } from "./events.js";
+import { commandHelp, isCommand, listing, unknownCommand, usageError } from "./help.js";
+import { flagWindow, historyLines, historyReport, historySchema, parseRange, retroMarkdown } from "./history.js";
 import { inboxLines } from "./inbox.js";
+import { parseJsonc } from "./jsonc.js";
 import { processAlive, readPid } from "./lock.js";
-import { fleetWorkerSchema } from "./manager.js";
+import { fleetWorkerSchema, storedFleet } 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 { rulesLines, rulesService, rulesTestResultSchema, rulesViewSchema, testLines } from "./rules-service.js";
+import { resolveUntil } from "./rules.js";
 import { outputOf, run } from "./run.js";
-import { formatTokens } from "./spend.js";
+import { queueLines, queueViewSchema } from "./scheduler.js";
+import { awaitStart, serveDetached, ServeStartError } from "./serve.js";
+import { formatTokens, localDay } 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 { parseTag, restartDaemon, upgrade } from "./upgrade.js";
 import { waitCommand } from "./wait.js";
-const USAGE = `Usage: conduct <command>
-
-  serve                     run the daemon in this process (one per machine)
-  stop                      stop the running daemon
-  status [--json]           the daemon's pid, port, projects and workers
-  project add <path>        register the project whose checkout holds .claude/conductor.json
-  project list [--json]     the registered projects
-  launch <item>             start a worker: its worktree, a background session, a tab
-      [--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)
-  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)
-      pr <n> merged|checks|comment [--repo <owner>/<repo>]
-      run <pipeline> <run id> [done]
-      npm <version> [--tag <dist-tag>] [--package <name>]
-      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 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).`;
+import { whyLines, whySchema } from "./why.js";
 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;
@@ -127,7 +85,9 @@ 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()}`);
 }
@@ -164,25 +124,94 @@ 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);
+// The pid of the daemon once it answers /health, for upgrade's restart. failure: the detached
+// serve's spawn error, which ends the wait early.
+async function awaitDaemon(paths, failure) {
+    return awaitStart({
+        answer: async () => {
+            const pid = readPid(paths.pid);
+            return pid !== null && (await ping(paths, pid)) ? pid : null;
+        },
+        failure,
+        log: paths.log,
+        timeoutMs: START_WAIT_MS,
+    });
+}
+// What `conduct ports` and `conduct lock` print to and run in.
+function brokerIo() {
+    return { cwd: process.cwd(), err: (line) => process.stderr.write(`${line}\n`), out };
+}
+// `conduct console`: the console (design note, section 11), the Claude session the conductor mod
+// serves, started with CONDUCTOR_CONSOLE=1 in the project's main checkout, where the console skill
+// is installed. It keeps no state of its own, so a new one after a close loses nothing.
+async function consoleCommand(paths, options) {
+    const project = consoleProject(await projectsNow(paths), options.project);
+    if (options.here) {
+        const child = spawn('claude', CONSOLE_ARGS, { cwd: project.root, env: { ...process.env, CONDUCTOR_CONSOLE: '1' }, stdio: 'inherit' });
+        // Ctrl+C belongs to the session; this process only waits for it to end.
+        process.on('SIGINT', () => { });
+        process.exitCode = await new Promise((done, fail) => {
+            child.on('error', (error) => fail(new ConductorError('could not start claude', [error.message])));
+            child.on('exit', (code) => done(code ?? 1));
+        });
+        return;
+    }
+    if (process.platform !== 'win32') {
+        throw new ConductorError('conduct console opens a Windows Terminal tab', ['run `conduct console --here` in a terminal of your own']);
+    }
+    // A tab starts with Windows Terminal's environment, not this one's.
+    if (process.env.CONDUCTOR_HOME) {
+        throw new ConductorError('a console tab would not see CONDUCTOR_HOME', ['run `conduct console --here` in a terminal where it is set']);
     }
-    throw new ConductorError(`the conductor did not answer within ${START_WAIT_MS / 1000} s`, [`see ${paths.log}`]);
+    const args = consoleTabArgs(project, process.execPath, realpathSync(fileURLToPath(import.meta.url)));
+    const result = await run('wt.exe', args, { cwd: project.root, timeoutMs: 60_000 });
+    if (result.code !== 0)
+        throw new ConductorError('could not open the console tab', [outputOf(result, 500), 'run `conduct console --here` in a terminal instead']);
+    out(`opened the console in ${project.root} (Windows Terminal window "${CONSOLE_WINDOW}")`);
+}
+// How `conduct start` and upgrade's restart start the daemon detached from this process.
+function daemonStarter(paths, cliPath) {
+    let failure = () => undefined;
+    return {
+        awaitDaemon: () => awaitDaemon(paths, failure),
+        runTask: runStartup,
+        serveDetached: () => {
+            failure = serveDetached(paths.home, process.execPath, [cliPath, 'serve']);
+        },
+        // The logon task's daemon uses ~/.conductor, so it can't start one kept in CONDUCTOR_HOME.
+        taskRunsCli: () => !process.env.CONDUCTOR_HOME && startupRunsCli(cliPath),
+    };
+}
+// `conduct escalations done`: the console reports back on an escalation.
+async function escalationDone(paths, ref, finding) {
+    const id = /^#?(\d+)$/.exec(ref)?.[1];
+    if (id === undefined)
+        throw new ConductorError(`"${ref}" is not an escalation id`, ['`conduct escalations` lists them as #<id>']);
+    const answer = await callApi(paths, { body: finding, method: 'POST', path: `/console/escalations/${id}` });
+    if (answer.status === 404 && !errorBody.safeParse(answer.body).data?.details)
+        throw olderDaemon('no console escalations');
+    const { escalation, event, inbox: raised } = handledSchema.parse(await expectOk(Promise.resolve(answer)));
+    out(`handled escalation #${escalation.id}${escalation.item ? ` on ${escalation.item}` : ''} (event #${event})`);
+    if (raised)
+        out(`and raised inbox item #${raised.id} (console) for you`);
+}
+async function escalations(paths, json) {
+    const answer = await callApi(paths, { method: 'GET', path: '/console/escalations' });
+    if (answer.status === 404)
+        throw olderDaemon('no console escalations');
+    const { escalations: open } = z.object({ escalations: z.array(escalationSchema) }).parse(await expectOk(Promise.resolve(answer)));
+    if (json)
+        return out(JSON.stringify(open, null, 2));
+    escalationLines(open, new Date()).forEach((line) => out(line));
 }
 // `conduct events`: until Ctrl+C with --follow.
-async function events(paths, follow, since) {
+async function events(paths, follow, since, isConsole) {
     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 });
+    await eventsCommand(paths, { console: isConsole, follow, since: since === undefined ? undefined : Number(since) }, { out, signal: stop.signal });
 }
 async function expectOk(call) {
     const { body, status } = await call;
@@ -202,6 +231,55 @@ 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}`));
 }
+// `conduct help <name>`; `conduct help help` is the listing.
+function helpOf(name) {
+    if (name === 'help')
+        return listing();
+    if (!isCommand(name))
+        throw unknownCommand(name);
+    return commandHelp(name);
+}
+// `conduct history` and `retro`: from the daemon, or straight from conductor.db when none runs or
+// it is older than /history. Reading needs no daemon: the report is a query over the store.
+async function history(paths, command, range, options) {
+    const flags = options.since !== undefined || options.until !== undefined;
+    if (flags && range !== undefined)
+        throw new ConductorError(`conduct ${command} takes a <range> or --since/--until, not both`);
+    const now = new Date();
+    const window = flags ? flagWindow(options.since, options.until, now) : parseRange(range, now);
+    const request = { project: options.project ?? null, since: window.since.toISOString(), until: window.until.toISOString() };
+    // Read-only: a daemon older than this build may be running, and a migration would strand it.
+    const local = () => {
+        try {
+            return withStore(paths, (store) => historyReport(store, request), { readOnly: true });
+        }
+        catch (error) {
+            if (error instanceof ConductorError)
+                throw error;
+            throw new ConductorError(`could not read ${paths.db}`, [
+                error instanceof Error ? error.message : String(error),
+                'a schema older than this conduct, or a log left by a crash: start the conductor once (conduct serve, or conduct upgrade), then try again',
+            ]);
+        }
+    };
+    let report;
+    try {
+        const query = new URLSearchParams({ since: request.since, until: request.until, ...(options.project ? { project: options.project } : {}) });
+        const answer = await callApi(paths, { method: 'GET', path: `/history?${query.toString()}`, timeoutMs: 60_000 });
+        report = answer.status === 404 ? local() : historySchema.parse(await expectOk(Promise.resolve(answer)));
+    }
+    catch (error) {
+        if (!(error instanceof NotRunningError))
+            throw error;
+        report = local();
+    }
+    if (options.json)
+        return out(JSON.stringify(report, null, 2));
+    if (command === 'retro')
+        process.stdout.write(retroMarkdown(report));
+    else
+        historyLines(report).forEach((line) => out(line));
+}
 async function inbox(paths, json) {
     const items = await openItems(paths);
     if (items === null)
@@ -227,6 +305,9 @@ function install() {
         out('warning: that build is in a worktree, which goes away; run install-startup from the main checkout');
     }
 }
+function isHelpFlag(word) {
+    return word === '--help' || word === '-h';
+}
 async function launch(paths, item, options) {
     const { worker } = workerBody.parse(await expectOk(callApi(paths, { body: { item, ...options }, method: 'POST', path: '/workers' })));
     out(`launching ${worker.name} in ${worker.project} (worker ${worker.id}): worktree, then session`);
@@ -251,15 +332,7 @@ async function launch(paths, item, options) {
     ]);
 }
 async function listProjects(paths, json) {
-    let projects;
-    try {
-        projects = projectsBody.parse(await expectOk(callApi(paths, { method: 'GET', path: '/projects' }))).projects;
-    }
-    catch (error) {
-        if (!(error instanceof NotRunningError))
-            throw error;
-        projects = withStore(paths, (store) => store.listProjects());
-    }
+    const projects = await projectsNow(paths);
     if (json)
         return out(JSON.stringify(projects, null, 2));
     if (projects.length === 0)
@@ -269,62 +342,108 @@ async function listProjects(paths, json) {
 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));
+        return argv.slice(1).some(isHelpFlag) ? out(commandHelp('wait')) : 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') {
+        // A lone help flag as the text is a call for help: posted, it would be a revision of "--help".
+        if (isHelpFlag(argv[1]) || (argv.length === 3 && isHelpFlag(argv[2])))
+            return out(commandHelp('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>"');
+            throw usageError('revise');
         return answer(conductorPaths(), ref, { action: 'revise', text });
     }
-    const { positionals, values } = parseArgs({
+    // The same for a finding: free text after the id, with --ask as a word of its own anywhere.
+    if (argv[0] === 'escalations' && argv[1] === 'done') {
+        if (isHelpFlag(argv[2]) || (argv.length === 4 && isHelpFlag(argv[3])))
+            return out(commandHelp('escalations'));
+        const [ref, ...rest] = argv.slice(2);
+        const ask = rest.includes('--ask');
+        const text = rest.filter((word) => word !== '--ask').join(' ').trim();
+        if (ref === undefined || !text)
+            throw usageError('escalations');
+        return escalationDone(conductorPaths(), ref, { ask, text });
+    }
+    // The first word that names a command: an option's value (--project atk) comes before it at times.
+    const { positionals, values } = parsing(argv.find((word) => isCommand(word)), () => parseArgs({
         allowPositionals: true,
         args: argv,
         options: {
             'allow-downgrade': { type: 'boolean' },
             channel: { type: 'string' },
             conductor: { type: 'string' },
+            console: { type: 'boolean' },
             follow: { type: 'boolean' },
             force: { type: 'boolean' },
+            fresh: { type: 'boolean' },
             help: { short: 'h', type: 'boolean' },
+            here: { type: 'boolean' },
             json: { type: 'boolean' },
             kind: { type: 'string' },
+            owner: { type: 'string' },
+            prefer: { 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' },
+            wait: { type: 'string' },
+            weight: { type: 'string' },
             worker: { type: 'string' },
         },
-    });
+    }));
     const paths = conductorPaths();
     const [command, sub, arg] = positionals;
     if (values.version)
         return out(version());
-    if (values.help || command === undefined || command === 'help')
-        return out(USAGE);
+    if (command === undefined || command === 'help')
+        return out(sub === undefined ? listing() : helpOf(sub));
+    if (!isCommand(command))
+        throw unknownCommand(command);
+    if (values.help)
+        return out(commandHelp(command));
     switch (command) {
         case 'approve':
             if (sub === undefined)
-                throw new ConductorError('usage: conduct approve <item> [--text <text>]');
+                throw usageError('approve');
             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>');
+                throw usageError('attach');
             return attach(paths, sub);
+        case 'brief':
+            if (sub === undefined)
+                throw usageError('brief');
+            process.exitCode = await briefCommand(paths, sub, { fresh: values.fresh === true, json: values.json === true }, {
+                err: (line) => process.stderr.write(`${line}\n`),
+                out,
+            });
+            return;
+        case 'console':
+            return consoleCommand(paths, { here: values.here === true, project: values.project });
         case 'done':
             if (sub === undefined)
-                throw new ConductorError('usage: conduct done <inbox id>');
+                throw usageError('done');
             return answer(paths, sub, { action: 'done' });
+        case 'escalations':
+            if (sub !== undefined)
+                throw usageError('escalations');
+            return escalations(paths, values.json === true);
         case 'events':
-            return events(paths, values.follow === true, values.since);
+            // CONDUCTOR_CONSOLE as well: a console still running a mod from before --console (until
+            // /reload-plugins after an upgrade) starts this package's new build, in the console's env.
+            return events(paths, values.follow === true, values.since, values.console === true || process.env.CONDUCTOR_CONSOLE === '1');
+        case 'history':
+        case 'retro':
+            return history(paths, command, sub, { json: values.json === true, project: values.project, since: values.since, until: values.until });
         case 'inbox':
             return inbox(paths, values.json === true);
         case 'install-mod':
@@ -333,16 +452,25 @@ async function main(argv) {
             return values.remove ? uninstall() : install();
         case 'launch':
             if (sub === undefined)
-                throw new ConductorError('usage: conduct launch <item> [--project <name>] [--probe]');
+                throw usageError('launch');
             return launch(paths, sub, {
                 conductor: values.conductor,
                 probe: values.probe,
                 project: values.project,
                 prompt: values.prompt,
             });
+        case 'lock': {
+            if (sub === undefined || arg === undefined)
+                throw usageError('lock');
+            const waitMinutes = values.wait === undefined ? undefined : Number(values.wait);
+            if (waitMinutes !== undefined && !(waitMinutes >= 0))
+                throw new ConductorError('--wait takes minutes, such as --wait 30');
+            process.exitCode = await lockCommand(paths, sub, arg, { owner: values.owner, waitMinutes }, brokerIo());
+            return;
+        }
         case 'note':
             if (sub === undefined || arg === undefined)
-                throw new ConductorError('usage: conduct note <item> <file> [--worker <worker>]');
+                throw usageError('note');
             process.exitCode = await noteCommand(paths, sub, arg, { worker: values.worker }, {
                 cwd: process.cwd(),
                 err: (line) => process.stderr.write(`${line}\n`),
@@ -356,53 +484,85 @@ async function main(argv) {
                 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');
+            throw usageError('notify');
         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');
+            throw usageError('project');
+        case 'focus':
+            if (sub === undefined || values.until === undefined)
+                throw usageError('focus');
+            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 'ports':
+            process.exitCode = await portsCommand(paths, sub, { json: values.json === true, ...(values.prefer === undefined ? {} : { prefer: wholeNumber('--prefer', values.prefer) }) }, brokerIo());
+            return;
+        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 usageError('rules');
         case 'retire':
             if (sub === undefined)
-                throw new ConductorError('usage: conduct retire <worker> [--force]');
+                throw usageError('retire');
             return retire(paths, sub, values.force === true);
         case 'serve':
             return serve(paths);
+        case 'start':
+            return start(paths);
         case 'status':
             return status(paths, values.json === true);
         case 'stop':
             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);
-        default:
-            throw new ConductorError(`unknown command "${command}"`, ['run `conduct help` for the commands']);
+        case 'why':
+            if (sub === undefined)
+                throw usageError('why');
+            return why(paths, sub, values.json === true);
+        // Only when an option comes first: as the first word they parse their own arguments, above.
+        case 'revise':
+        case 'wait':
+            throw usageError(command, `conduct ${command} takes its arguments right after the command`);
+        default: {
+            const unhandled = command;
+            throw unknownCommand(String(unhandled));
+        }
     }
 }
 function modDeps() {
     return { claude: (args) => run('claude', args, { timeoutMs: 120_000 }), out };
 }
 function noInbox() {
-    return new ConductorError('the running conductor has no inbox: it is older than this conduct', [
-        'restart it on this build: conduct stop, then conduct serve (or conduct upgrade)',
-    ]);
+    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 new ConductorError('the running conductor has no notifier: it is older than this conduct', [
-            'restart it on this build: conduct stop, then conduct serve (or conduct upgrade)',
-        ]);
-    }
+    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>');
+            throw usageError('notify', '--until needs a profile: conduct notify profile <name> --until <when>');
         return notifyStatus(paths, false);
     }
     const body = { name, ...(until === undefined ? {} : { until: parseUntil(until, new Date()).toISOString() }) };
@@ -438,6 +598,11 @@ async function notifyTest(paths, options) {
 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' });
@@ -448,6 +613,39 @@ async function openItems(paths) {
 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`);
+}
+// parseArgs' own errors (an unknown option, a missing value) with the command's usage, not every
+// command's.
+function parsing(command, parse) {
+    try {
+        return parse();
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && typeof error.code === 'string' && error.code.startsWith('ERR_PARSE_ARGS')))
+            throw error;
+        // Node's advice on `--` for a positional that starts with a dash is about the shell, not conduct.
+        const message = error.message.replace(/\. To specify a positional argument.*$/s, '');
+        throw isCommand(command) ? usageError(command, message) : new ConductorError(message, ['run `conduct help` for the commands']);
+    }
+}
 // 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) {
@@ -470,6 +668,27 @@ 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})`;
 }
+// The registered projects: from the daemon, or from the store when it isn't running.
+async function projectsNow(paths) {
+    try {
+        return projectsBody.parse(await expectOk(callApi(paths, { method: 'GET', path: '/projects' }))).projects;
+    }
+    catch (error) {
+        if (!(error instanceof NotRunningError))
+            throw error;
+        return withStore(paths, (store) => store.listProjects());
+    }
+}
+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, {
@@ -497,23 +716,86 @@ 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})`);
     for (const signal of ['SIGINT', 'SIGTERM', 'SIGBREAK']) {
         process.once(signal, () => void daemon.stop(signal));
     }
-    // Under the logon task nobody sees stderr, so a crash goes to the log. The pid file it leaves
-    // names a dead process, which the next start replaces.
-    process.on('uncaughtException', (error) => {
-        daemon.log.log('error', 'uncaught exception', { error: error.stack ?? String(error) });
-        process.exit(1);
-    });
+    logCrashes(daemon.log);
     await daemon.closed;
 }
 function sleep(ms) {
     return new Promise((done) => setTimeout(done, ms));
 }
+// `conduct start`: the daemon, detached from this process, so it outlives the shell or the Claude
+// session that started it (the console's start runs this). Nothing when one answers already.
+async function start(paths) {
+    const pid = readPid(paths.pid);
+    if (pid !== null && (await ping(paths, pid)))
+        return out(`the conductor is running (pid ${pid})`);
+    // A daemon that is still starting (the logon task's, say) holds the lock: wait for it rather than
+    // start a second one, which would exit on that lock. A pid a reboot reused gets a start after.
+    if (pid !== null && processAlive(pid)) {
+        try {
+            return out(`the conductor is running (pid ${await awaitDaemon(paths)})`);
+        }
+        catch {
+            // Not a daemon that answers: start one, which replaces a stale lock (or says who holds it).
+        }
+    }
+    try {
+        out(`started the conductor ${await restartDaemon(daemonStarter(paths, realpathSync(fileURLToPath(import.meta.url))))}`);
+    }
+    catch (error) {
+        const holder = readPid(paths.pid);
+        if (error instanceof ServeStartError || holder === null || !processAlive(holder))
+            throw error;
+        throw new ConductorError(`process ${holder} holds the conductor's lock (${paths.pid}) but doesn't answer`, ['if it is a hung conductor, stop it, then run conduct start again', `see ${paths.log}`]);
+    }
+}
 async function status(paths, json) {
     let projects;
     try {
@@ -522,23 +804,32 @@ async function status(paths, json) {
     catch (error) {
         if (!(json && error instanceof NotRunningError))
             throw error;
-        // Scripts and the conductor mod read the answer, so "not running" is JSON too (exit 1).
-        out(JSON.stringify({ home: paths.home, running: false }, null, 2));
+        // Scripts and the conductor mod read the answer, so "not running" is JSON too (exit 1), with the
+        // store's workers while the daemon restarts or upgrades.
+        const workers = storedFleet(paths.db, localDay(new Date()));
+        out(JSON.stringify({ home: paths.home, running: false, ...(workers ? { workers, workersFrom: 'store' } : {}) }, null, 2));
         process.exitCode = 1;
         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);
+    // Null from a daemon older than the broker.
+    const locks = await heldLocks(paths);
     const pid = readPid(paths.pid);
     const port = readEndpoint(paths)?.port ?? null;
     if (json)
-        return out(JSON.stringify({ home: paths.home, inbox: items, pid, port, projects, running: true, workers }, null, 2));
+        return out(JSON.stringify({ home: paths.home, inbox: items, locks, pid, port, projects, running: true, workers, workersFrom: 'daemon' }, 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 (locks === null)
+        out('locks: not in this daemon (restart it to run this build)');
+    else
+        out(locks.length === 0 ? 'locks: none held' : 'locks:');
+    locks?.forEach((l) => out(lockLine(l)));
     if (items === null)
         out('inbox: not in this daemon (restart it to run this build)');
     else
@@ -572,10 +863,14 @@ async function stopDaemon(paths) {
 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),
+        ...daemonStarter(paths, cliPath),
         cliPath,
         installedVersion: version,
         npmInstall: (spec) => npm(['install', '--global', spec], NPM_INSTALL_TIMEOUT_MS),
@@ -593,15 +888,7 @@ async function upgradeCommand(paths, tag, allowDowngrade) {
             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.
@@ -610,7 +897,7 @@ function version() {
     return z.object({ version: z.string() }).parse(JSON.parse(readFileSync(file, 'utf8'))).version;
 }
 async function wait(argv) {
-    const { positionals, values } = parseArgs({
+    const { positionals, values } = parsing('wait', () => parseArgs({
         allowPositionals: true,
         args: argv,
         options: {
@@ -624,17 +911,39 @@ async function wait(argv) {
             version: { type: 'string' },
             worker: { type: 'string' },
         },
-    });
+    }));
     const timeout = values.timeout === undefined ? undefined : Number(values.timeout);
     if (timeout !== undefined && !(timeout > 0))
         throw new ConductorError('--timeout takes minutes, such as --timeout 25');
     if (positionals.length === 0)
-        throw new ConductorError('usage: conduct wait <condition>', ['run `conduct help` for the conditions']);
+        throw usageError('wait');
     process.exitCode = await waitCommand(conductorPaths(), positionals, { ...values, timeoutMinutes: timeout }, { cwd: process.cwd(), err: (line) => process.stderr.write(`${line}\n`), out });
 }
-function withStore(paths, use) {
+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, options = {}) {
     mkdirSync(paths.home, { recursive: true });
-    const store = openStore(paths.db);
+    const store = openStore(paths.db, undefined, options);
     try {
         return use(store);
     }
@@ -657,9 +966,6 @@ main(process.argv.slice(2)).catch((error) => {
     if (error instanceof ConductorError) {
         process.stderr.write(`conduct: ${error.message}\n${error.details.map((d) => `  ${d}\n`).join('')}`);
     }
-    else if (error instanceof Error && 'code' in error && typeof error.code === 'string' && error.code.startsWith('ERR_PARSE_ARGS')) {
-        process.stderr.write(`conduct: ${error.message}\n${USAGE}\n`);
-    }
     else {
         process.stderr.write(`conduct: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
     }