@detergent-software/conductor 1.0.0-dev.2 → 1.0.0-dev.20

package/build/cli.js

@@ -5,29 +5,93 @@ import { resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { z } from 'zod';
+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 { 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 { 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 { queueLines, queueViewSchema } from "./scheduler.js";
+import { formatTokens } from "./spend.js";
 import { installStartup, removeStartup, runStartup, startupRunsCli, TASK_NAME } from "./startup.js";
-import { openStore, projectSchema, workerSchema } from "./store.js";
-import { parseTag, upgrade } from "./upgrade.js";
+import { inboxItemSchema, openStore, projectSchema, waitSchema, workerSchema } from "./store.js";
+import { parseTag, restartDaemon, 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)
+  start                     start the daemon detached (the logon task, else a detached serve) and
+                            wait until it answers; nothing when it runs already
   stop                      stop the running daemon
-  status [--json]           the daemon's pid, port, projects and workers
+  status [--json]           the daemon's pid, port, projects, workers and held locks
   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)
+  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; with neither,
+                            its items go first (weight 100)
+  why <event id | item> [--json]
+                            the rule behind an action, and the events that led to it
+  console [--project <name>] [--here]
+                            open the console (the Claude session the conductor mod serves) in a
+                            Windows Terminal tab in the project's main checkout; --here runs it in
+                            this terminal. Also how to get it back after it closed
+  escalations [--json]      what rules escalated to the console and it hasn't handled (14 days)
+  escalations done <id> [--ask] <text>
+                            the console's finding on escalation #<id>, logged; --ask also puts it
+                            in the inbox for you (a "console" item)
+  history [<range>] [--since <when>] [--until <when>] [--project <name>] [--json]
+                            what a window of the log says: shipped items, time in each phase by tier,
+                            plan latency, waits by kind, stalls, failures, inbox, slot use, rules, spend
+  retro [<range>] [--project <name>]
+                            the same as a Markdown report. A <range> is today, yesterday, a date
+                            (2026-10-10), A..B (2026-10-10..2026-10-11), or a span (24h, the default; 7d)
+  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)
@@ -37,13 +101,32 @@ 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>]
+  ports [<path>] [--prefer <slot>] [--json]
+                            the checkout's dev ports from the port broker: its project's base ports
+                            + its slot, which no other project's worktree shares (a main checkout:
+                            slot 0); --prefer asks for a slot first. Without <path>, every worktree's.
+                            Exit 3 when no conductor brokered it, so the caller keeps its own ports
+  lock acquire|release|status <name> [--owner <id>] [--wait <minutes>]
+                            a lock every project shares, such as chrome for verify runs; stale 30 min
+                            after its holder last acquired it (acquire again to keep it). The owner is
+                            this checkout's worker's item unless given; --wait polls. Prints JSON;
+                            exit 3 when no conductor answers
+  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).`;
@@ -58,6 +141,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() });
@@ -77,6 +162,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;
@@ -87,10 +179,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 })));
@@ -109,6 +229,83 @@ async function awaitDaemon(paths) {
     }
     throw new ConductorError(`the conductor did not answer within ${START_WAIT_MS / 1000} s`, [`see ${paths.log}`]);
 }
+// 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']);
+    }
+    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) {
+    return {
+        awaitDaemon: () => awaitDaemon(paths),
+        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(),
+        // 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) {
+    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)
@@ -127,13 +324,63 @@ 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);
+// `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)
+        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));
@@ -167,15 +414,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)
@@ -186,20 +425,54 @@ 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 });
+    }
+    // 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') {
+        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 new ConductorError('usage: conduct escalations done <id> [--ask] "<what you found or did>"');
+        return escalationDone(conductorPaths(), ref, { ask, 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' },
+            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();
@@ -209,10 +482,33 @@ 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 'console':
+            return consoleCommand(paths, { here: values.here === true, project: values.project });
+        case 'done':
+            if (sub === undefined)
+                throw new ConductorError('usage: conduct done <inbox id>');
+            return answer(paths, sub, { action: 'done' });
+        case 'escalations':
+            if (sub !== undefined)
+                throw new ConductorError('usage: conduct escalations [--json] | conduct escalations done <id> [--ask] <text>');
+            return escalations(paths, values.json === true);
+        case 'events':
+            return events(paths, values.follow === true, values.since);
+        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':
+            return values.remove ? removeMod(modDeps()) : installMod(fileURLToPath(new URL('../mod', import.meta.url)), modDeps());
         case 'install-startup':
             return values.remove ? uninstall() : install();
         case 'launch':
@@ -224,41 +520,216 @@ async function main(argv) {
                 project: values.project,
                 prompt: values.prompt,
             });
+        case 'lock': {
+            if (sub === undefined || arg === undefined)
+                throw new ConductorError('usage: conduct lock <acquire|release|status> <name> [--owner <id>] [--wait <minutes>]');
+            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>]');
+            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 '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 new ConductorError('usage: conduct rules [--json] | conduct rules test <file> [--json]');
         case 'retire':
             if (sub === undefined)
                 throw new ConductorError('usage: conduct retire <worker> [--force]');
             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);
+            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})`;
 }
+// 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, {
@@ -286,23 +757,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 (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 {
@@ -317,15 +851,28 @@ 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);
+    // 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, pid, port, projects, running: true, workers }, null, 2));
+        return out(JSON.stringify({ home: paths.home, inbox: items, locks, 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 (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
+        out(items.length === 0 ? 'inbox: empty' : `inbox: ${items.length} open (conduct inbox)`);
 }
 // True when it stopped a daemon, false when none ran.
 async function stopDaemon(paths) {
@@ -355,10 +902,14 @@ async function stopDaemon(paths) {
 function uninstall() {
     out(removeStartup() ? `removed the "${TASK_NAME}" logon task` : `no "${TASK_NAME}" logon task to remove`);
 }
-async function upgradeCommand(paths, tag) {
+// --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({ tag: parseTag(tag) }, {
-        awaitDaemon: () => awaitDaemon(paths),
+    await upgrade({ allowDowngrade, tag: parseTag(tag) }, {
+        ...daemonStarter(paths, cliPath),
         cliPath,
         installedVersion: version,
         npmInstall: (spec) => npm(['install', '--global', spec], NPM_INSTALL_TIMEOUT_MS),
@@ -376,15 +927,7 @@ async function upgradeCommand(paths, tag) {
             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.
@@ -415,9 +958,31 @@ 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 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);
     }
@@ -425,12 +990,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('  ·  ');