@detergent-software/conductor 3.0.0-dev.4 → 3.0.0-dev.41

package/build/cli.js

@@ -1,22 +1,26 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
-import { join, resolve, sep } from 'node:path';
+import { delimiter, join } 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 { trustStep } from "./claude.js";
 import { callApi, NotRunningError, ping, readEndpoint } from "./client.js";
-import { branchCommand, checkoutCommand, fileCommand, landCommand, modeCommand, prCreateCommand, prThreadsCommand, replyCommand, runsCommand, stateCommand, } from "./code-host-cli.js";
+import { branchCommand, checkoutCommand, fileCommand, landCommand, modeCommand, prAbandonCommand, prCreateCommand, prStatusCommand, prThreadsCommand, replyCommand, runsCommand, stateCommand, timelineCommand, } from "./code-host-cli.js";
 import { configSchema, loadConfig } from "./config.js";
-import { claimConsole, CONSOLE_WINDOW, consoleArgs, consoleTabArgs, escalationLines, escalationSchema, handledSchema, } from "./console.js";
+import { claimConsole, CONSOLE_WINDOW, consoleArgs, consoleEnv, consoleTab, escalationLines, escalationSchema, handledSchema, } from "./console.js";
 import { AlreadyRunningError, logCrashes, startDaemon } from "./daemon.js";
 import { ConductorError } from "./errors.js";
 import { eventsCommand } from "./events.js";
 import { commandHelp, isCommand, listing, terminalStyle, terminalWidth, unknownCommand, usageError } from "./help.js";
 import { flagWindow, historyLines, historyReport, historySchema, parseRange, retroMarkdown, } from "./history.js";
+import { startup } from "./host/startup.js";
+import { terminal } from "./host/terminal.js";
 import { inboxLines } from "./inbox.js";
+import { initProject, terminalAsk } from "./init.js";
 import { parseJsonc } from "./jsonc.js";
 import { npmStage } from "./lib/providers/index.js";
 import { processAlive, readPid } from "./lock.js";
@@ -24,32 +28,32 @@ import { rotatingLog } from "./log.js";
 import { fleetWorkerSchema, storedFleet, workerByRef, workerLine } from "./manager.js";
 import { noteCommand } from "./note.js";
 import { isQuiet, notifyLines, notifyStatusSchema, parseUntil, testResultSchema } from "./notify.js";
+import { sharedNpmReads } from "./npm-reads.js";
 import { overrideViewSchema, PAUSE } from "./overrides.js";
 import { packageInfo } from "./package-info.js";
 import { conductorPaths } from "./paths.js";
 import { refreshConductorPlugin } from "./plugin.js";
-import { projectCheckCommand } from "./project-check-cli.js";
+import { profileLines, projectProfile } from "./profile-layers.js";
+import { projectCheckCommand, projectCheckReport } from "./project-check-cli.js";
 import { noProject } from "./project-check.js";
 import { pushoverCredential, pushoverSender } from "./pushover.js";
-import { registerProject } from "./registry.js";
+import { cloneProject, 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 { awaitStart, serveDetached, ServeStartError } from "./serve.js";
 import { localDay } from "./spend.js";
-import { installStartup, removeStartup, runStartup, startupRunsCli, startupSupervises, TASK_NAME } from "./startup.js";
 import { answerStopRequest, dropStaleStopRequest, pendingStopRequest, STOP_POLL_MS, stopSupervisor, } from "./stop-request.js";
 import { inboxItemSchema, openStore, projectSchema, waitSchema, workerSchema, } from "./store.js";
 import { RESTART_ENV, restartInfoSchema, SERVE_LOCKED_EXIT, serveChild, supervise, SUPERVISE_POLICY, } from "./supervise.js";
-import { openWindowsTerminal } from "./tab.js";
 import { commentsCommand, notesCommand, searchCommand } from "./tracker-reads-cli.js";
 import { trainCommand } from "./train-cli.js";
 import { parseTag, restartDaemon, tagVersion, upgrade } from "./upgrade.js";
 import { waitCommand } from "./wait.js";
 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.
+// A restarted daemon opens its store and binds the port; under the logon startup node starts cold.
 const START_WAIT_MS = 30_000;
 const NPM_INSTALL_TIMEOUT_MS = 5 * 60_000;
 // A launch makes a worktree (pnpm install) before the session starts.
@@ -61,6 +65,9 @@ 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;
+// A revise of an approved plan adds up to three brief reads (the tracker and the PR, each within
+// 20 s) 2 s apart after the comment, so a slow tracker doesn't cut off an answer whose comment landed.
+const REVISE_TIMEOUT_MS = 3 * 60_000;
 const projectsBody = z.object({ projects: z.array(projectSchema) });
 const addBody = z.object({ created: z.boolean(), project: projectSchema });
 const removeBody = z.object({ project: projectSchema, resolved: z.array(inboxItemSchema) });
@@ -85,23 +92,43 @@ const retireBody = z.object({
     work: workSchema.extend({ checkouts: z.record(z.string(), workSchema).optional() }).optional(),
     worker: workerSchema,
 });
-const attachBody = z.object({ resumed: z.boolean(), tab: z.string().nullable(), worker: workerSchema });
+// hint: from ATK-529 on; an older daemon sends none.
+const attachBody = z.object({
+    hint: z.string().nullable().default(null),
+    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 reviseAnswer = z.object({
+    revise: z.object({
+        comment: z.object({ id: z.string(), url: z.string().nullable() }),
+        item: z.string(),
+        landed: z.boolean(),
+        pending: z.string().nullable(),
+        revised: z.boolean(),
+        woken: z.number(),
+        worker: z.boolean(),
+    }),
+});
 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);
+// `conduct project add <url | path> [--name <name>]`: the clone is made here, where its progress
+// shows and no API timeout applies, then the daemon registers it (or the store, with none running).
+// `next`: false for `conduct init`, which says what comes next itself.
+async function addProject(paths, source, name, next = true) {
+    const made = await cloneProject(paths, source, { ...(name === undefined ? {} : { name }), say: out });
     let result;
     try {
-        result = addBody.parse(await expectOk(callApi(paths, { body: { path: absolute }, method: 'POST', path: '/projects' })));
+        result = addBody.parse(await expectOk(callApi(paths, { body: { name: made.name }, method: 'POST', path: '/projects' })));
     }
     catch (error) {
         if (!(error instanceof NotRunningError))
@@ -109,14 +136,25 @@ async function addProject(paths, path) {
         // No daemon: write the store directly. The daemon reads it when it starts.
         // 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));
+        result = withStore(paths, (store) => registerProject(store, paths, made.name, check));
     }
     out(`${result.created ? 'registered' : 'updated'} ${projectLine(result.project).trim()}`);
+    out(made.cloned ? `cloned ${made.url} into ${made.clone}` : `fetched ${made.clone}, the clone it has`);
+    out(`its machine profile, which wins over the repo's: ${result.project.profilePath}`);
+    // Claude Code trusts a worktree by its repository, and nobody has run Claude in a new clone yet.
+    if (made.cloned && next)
+        out(`next: ${trustStep(made.clone)}, then \`conduct project check ${made.name}\``);
+    return made;
 }
-// `conduct approve|revise|done`: Jason's answer to an inbox item, by id, or for approve and revise
-// by the item whose plan waits.
+// `conduct approve|revise|done`: the operator's answer to an inbox item, by id, or for approve and revise
+// by the item whose plan waits. A revise of an item with no plan waiting revises its approved plan.
 async function answer(paths, ref, request) {
     const target = request.action === 'done' ? inboxId(ref) : await planItem(paths, ref);
+    if (target === null) {
+        if (request.action === 'revise')
+            return reviseApproved(paths, ref, request.text);
+        throw new ConductorError(`no plan of ${ref} waits in the inbox`, ['`conduct inbox` lists what waits']);
+    }
     const { body, status } = await callApi(paths, {
         body: request,
         method: 'POST',
@@ -150,6 +188,8 @@ async function attach(paths, ref) {
     out(`${result.resumed ? 'woke' : 'attached to'} ${worker.name} (session ${result.worker.handle ?? '?'})`);
     if (result.tab)
         out(`no tab (${result.tab}); open it yourself: claude attach ${result.worker.handle ?? worker.name}`);
+    else if (result.hint)
+        out(`to see its tab: ${result.hint}`);
 }
 // 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.
@@ -192,7 +232,7 @@ async function consoleCommand(paths, options) {
         await claimConsole(paths, options.force);
         const child = spawn('claude', consoleArgs(paths.plugin), {
             cwd: paths.console,
-            env: { ...process.env, CONDUCTOR_CONSOLE: '1' },
+            env: consoleEnv(process.env),
             stdio: 'inherit',
         });
         // Ctrl+C belongs to the session; this process only waits for it to end.
@@ -207,40 +247,33 @@ async function consoleCommand(paths, options) {
         });
         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(paths.console, process.execPath, realpathSync(fileURLToPath(import.meta.url)));
+    const where = terminal({ choice: loadConfig(paths.config).workers.terminal });
+    const tab = consoleTab(paths.console, process.execPath, realpathSync(fileURLToPath(import.meta.url)), process.env);
     await claimConsole(paths, options.force);
-    const result = await openWindowsTerminal(args, paths.console);
-    if (result.code !== 0)
-        throw new ConductorError('could not open the console tab', [
-            outputOf(result, 500),
+    const failed = await where.open(tab);
+    if (failed !== null)
+        throw new ConductorError(`could not open the console tab in ${where.name}`, [
+            failed,
             'run `conduct console --here --force` in a terminal instead',
         ]);
-    out(`opened the console in ${paths.console} (Windows Terminal window "${CONSOLE_WINDOW}")`);
+    const hint = where.attachHint(CONSOLE_WINDOW);
+    out(`opened the console in ${paths.console} (${hint === null ? `${where.name} window "${CONSOLE_WINDOW}"` : `${where.name}: ${hint}`})`);
 }
 // How `conduct start` and upgrade's restart start the daemon detached from this process.
 function daemonStarter(paths, cliPath) {
     let failure = () => undefined;
+    const task = startup();
     return {
         awaitDaemon: () => awaitDaemon(paths, failure),
-        runTask: runStartup,
+        runTask: () => task.run(),
         serveDetached: () => {
             // --fail-fast: a first serve that can't start ends the supervisor, so the start says why at once.
             failure = serveDetached(paths.home, process.execPath, [cliPath, 'supervise', '--fail-fast']);
         },
-        // The logon task's daemon uses ~/.conductor, so it can't start one kept in CONDUCTOR_HOME.
-        taskRunsCli: () => !process.env.CONDUCTOR_HOME && startupRunsCli(cliPath),
-        taskSupervises: startupSupervises,
+        taskName: task.name,
+        // The startup's daemon uses ~/.conductor, so it can't start one kept in CONDUCTOR_HOME.
+        taskRunsCli: async () => !process.env.CONDUCTOR_HOME && (await task.runsCli(cliPath)),
+        taskSupervises: () => task.supervises(),
     };
 }
 // `conduct escalations done`: the console reports back on an escalation.
@@ -365,11 +398,20 @@ function inboxId(ref) {
         throw new ConductorError(`"${ref}" is not an inbox item id`, ['`conduct inbox` lists them as #<id>']);
     return Number(id);
 }
-function install() {
+// `conduct install-startup`: the machine's startup (host/startup.ts) runs this build's supervise.
+async function install() {
     const cliPath = realpathSync(fileURLToPath(import.meta.url));
-    installStartup({ cliPath, nodePath: process.execPath });
-    out(`registered the "${TASK_NAME}" logon task: ${process.execPath} ${cliPath} supervise`);
-    if (cliPath.includes(`${sep}.claude${sep}worktrees${sep}`)) {
+    const task = startup();
+    // Less what `pnpm exec` or `npm run` put first, which a worktree's removal takes away.
+    const path = (process.env.PATH ?? '')
+        .split(delimiter)
+        .filter((dir) => !/[\\/]node_modules[\\/]\.bin[\\/]?$/.test(dir))
+        .join(delimiter);
+    const notes = await task.install({ cliPath, nodePath: process.execPath, path });
+    out(`registered ${task.name}: ${process.execPath} ${cliPath} supervise`);
+    for (const note of notes)
+        out(note);
+    if (/[\\/](?:\.claude|\.conductor[\\/]projects[\\/][^\\/]+)[\\/]worktrees[\\/]/.test(cliPath)) {
         out('warning: that build is in a worktree, which goes away; run install-startup from the main checkout');
     }
 }
@@ -404,7 +446,7 @@ async function listProjects(paths, json) {
     if (json)
         return out(JSON.stringify(projects, null, 2));
     if (projects.length === 0)
-        return out('no projects; add one with `conduct project add <path>`');
+        return out('no projects; add one with `conduct project add <url | path>`');
     projects.forEach((p) => out(projectLine(p)));
 }
 async function main(argv) {
@@ -412,7 +454,7 @@ async function main(argv) {
     if (argv[0] === 'wait')
         return argv.slice(1).some(isHelpFlag) ? help('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.
+    // after the item is the text, quoted or not: a cut-off instruction would be posted as the operator'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])))
@@ -437,19 +479,22 @@ async function main(argv) {
             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.
+    // The first word that names a command: an option's value (--project web) comes before it at times.
     const { positionals, values } = parsing(argv.find((word) => isCommand(word)), () => parseArgs({
         allowPositionals: true,
         args: argv,
         options: {
             'allow-downgrade': { type: 'boolean' },
             area: { type: 'string' },
+            base: { type: 'string' },
             'blocked-by': { multiple: true, type: 'string' },
             'body-file': { type: 'string' },
+            branch: { type: 'string' },
             channel: { type: 'string' },
             comments: { type: 'boolean' },
             conductor: { type: 'string' },
             console: { type: 'boolean' },
+            count: { type: 'string' },
             'dry-run': { type: 'boolean' },
             'fail-fast': { type: 'boolean' },
             files: { type: 'string' },
@@ -457,20 +502,24 @@ async function main(argv) {
             for: { type: 'string' },
             force: { type: 'boolean' },
             fresh: { type: 'boolean' },
+            grep: { type: 'string' },
             help: { short: 'h', type: 'boolean' },
             here: { type: 'boolean' },
             human: { type: 'boolean' },
             item: { type: 'string' },
             json: { type: 'boolean' },
+            key: { type: 'string' },
             kind: { type: 'string' },
             last: { type: 'boolean' },
             mode: { type: 'string' },
+            name: { type: 'string' },
             'no-worktree': { type: 'boolean' },
             owner: { type: 'string' },
             phase: { type: 'string' },
             probe: { type: 'boolean' },
             project: { type: 'string' },
             prompt: { type: 'string' },
+            query: { type: 'string' },
             raise: { type: 'boolean' },
             rearm: { type: 'boolean' },
             reason: { type: 'string' },
@@ -478,18 +527,23 @@ async function main(argv) {
             remove: { type: 'boolean' },
             repo: { type: 'string' },
             requeue: { type: 'string' },
+            shared: { type: 'boolean' },
             since: { type: 'string' },
             slots: { type: 'string' },
             tag: { type: 'string' },
+            task: { type: 'string' },
+            team: { type: 'string' },
             text: { type: 'string' },
             tier: { type: 'string' },
             title: { type: 'string' },
+            tracker: { type: 'string' },
             until: { type: 'string' },
             version: { short: 'v', type: 'boolean' },
             wait: { type: 'string' },
             'waits-release': { type: 'boolean' },
             weight: { type: 'string' },
             worker: { type: 'string' },
+            yes: { type: 'boolean' },
         },
     }));
     const paths = conductorPaths();
@@ -516,7 +570,7 @@ async function main(argv) {
         case 'branch':
             if (sub === undefined || arg === undefined)
                 throw usageError('branch');
-            process.exitCode = await branchCommand(sub, arg, item, verbIo());
+            process.exitCode = await branchCommand(paths, sub, arg, item, verbIo());
             return;
         case 'brief':
             if (sub === undefined)
@@ -530,7 +584,7 @@ async function main(argv) {
         case 'checkout':
             if (sub === undefined || arg === undefined || fourth === undefined)
                 throw usageError('checkout');
-            process.exitCode = await checkoutCommand(sub, arg, fourth, item, verbIo());
+            process.exitCode = await checkoutCommand(paths, sub, arg, fourth, item, verbIo());
             return;
         case 'comments': {
             if (sub === undefined || arg !== undefined)
@@ -559,10 +613,10 @@ async function main(argv) {
             // /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 'file':
-            if (sub !== undefined || !values.title || !values['body-file'] || !values.area)
+            if (sub !== undefined || !values.title || !values['body-file'])
                 throw usageError('file');
             process.exitCode = await fileCommand(paths, {
-                area: values.area,
+                area: values.area ?? '',
                 blockedBy: values['blocked-by'] ?? [],
                 bodyFile: values['body-file'],
                 human: values.human === true,
@@ -592,6 +646,26 @@ async function main(argv) {
             });
         case 'inbox':
             return inbox(paths, values.json === true);
+        case 'init':
+            if (arg !== undefined)
+                throw usageError('init');
+            process.exitCode = await initProject({
+                add: (checkout, name) => addProject(paths, checkout, name, false),
+                ask: terminalAsk(),
+                check: (name) => projectCheckReport(paths, name, { worktree: true }, { err: (line) => process.stderr.write(`${line}\n`) }),
+                out,
+                paths,
+            }, sub ?? '.', {
+                shared: values.shared === true,
+                yes: values.yes === true,
+                ...(values.base === undefined ? {} : { base: values.base }),
+                ...(values.key === undefined ? {} : { key: values.key }),
+                ...(values.name === undefined ? {} : { name: values.name }),
+                ...(values.query === undefined ? {} : { query: values.query }),
+                ...(values.team === undefined ? {} : { team: values.team }),
+                ...(values.tracker === undefined ? {} : { tracker: values.tracker }),
+            });
+            return;
         case 'install-startup':
             return values.remove ? uninstall() : install();
         case 'land': {
@@ -611,6 +685,7 @@ async function main(argv) {
                 ...repo,
                 ...(mode === undefined ? {} : { mode }),
                 ...(tier === undefined ? {} : { tier }),
+                ...(values.requeue === undefined ? {} : { requeue: wholeNumber('--requeue', values.requeue) }),
             }, verbIo());
             return;
         }
@@ -638,7 +713,7 @@ async function main(argv) {
                 throw usageError('mode');
             if (tier !== 'S' && tier !== 'M' && tier !== 'L')
                 throw new ConductorError('--tier takes S, M or L');
-            process.exitCode = await modeCommand({ files: values.files, tier }, verbIo());
+            process.exitCode = await modeCommand(paths, { files: values.files, tier }, verbIo());
             return;
         }
         case 'note':
@@ -670,10 +745,20 @@ async function main(argv) {
                 return notifyTest(paths, { channel: values.channel, kind: values.kind, raise: values.raise === true });
             throw usageError('notify');
         case 'pr':
+            if (sub === 'abandon' && arg !== undefined) {
+                if (values.reason === undefined)
+                    throw usageError('pr');
+                process.exitCode = await prAbandonCommand(paths, { force: values.force === true, pr: wholeNumber('<pr>', arg), reason: values.reason, ...item, ...repo }, verbIo());
+                return;
+            }
             if (sub === 'threads' && arg !== undefined) {
                 process.exitCode = await prThreadsCommand(paths, { pr: wholeNumber('<pr>', arg), ...repo }, verbIo());
                 return;
             }
+            if (sub === 'status' && arg !== undefined) {
+                process.exitCode = await prStatusCommand(paths, { pr: wholeNumber('<pr>', arg), ...repo }, verbIo());
+                return;
+            }
             if (sub !== 'create' || values.title === undefined || values['body-file'] === undefined)
                 throw usageError('pr');
             process.exitCode = await prCreateCommand(paths, { bodyFile: values['body-file'], dryRun: values['dry-run'] === true, title: values.title, ...item, ...repo }, verbIo());
@@ -687,9 +772,21 @@ async function main(argv) {
         case 'ports':
             process.exitCode = await portsCommand(paths, sub, { json: values.json === true }, brokerIo());
             return;
+        case 'profile': {
+            if (sub === undefined || arg !== undefined)
+                throw usageError('profile');
+            // Resolved here from the machine file and the clone, as the daemon resolves it.
+            const layered = projectProfile(paths, sub);
+            if (values.json === true)
+                return out(JSON.stringify({ profile: layered.profile, sources: layered.sources }, null, 2));
+            profileLines(sub, layered).forEach((line) => out(line));
+            return;
+        }
         case 'project':
-            if (sub === 'add' && arg !== undefined)
-                return addProject(paths, arg);
+            if (sub === 'add' && arg !== undefined) {
+                await addProject(paths, arg, values.name);
+                return;
+            }
             if (sub === 'remove' && arg !== undefined)
                 return removeProject(paths, arg);
             if (sub === 'list')
@@ -730,6 +827,7 @@ async function main(argv) {
                 ...item,
                 ...repo,
                 ...(values.for === undefined ? {} : { for: values.for }),
+                ...(values.grep === undefined ? {} : { grep: values.grep }),
                 ...(values.requeue === undefined ? {} : { requeue: values.requeue }),
             }, verbIo());
             return;
@@ -755,6 +853,19 @@ async function main(argv) {
         case 'supervise':
             process.exitCode = await superviseCommand(paths, values['fail-fast'] === true);
             return;
+        case 'timeline':
+            if (arg !== undefined)
+                throw usageError('timeline');
+            process.exitCode = await timelineCommand(paths, {
+                ...repo,
+                ...(sub === undefined ? {} : { run: sub }),
+                ...(values.branch === undefined ? {} : { branch: values.branch }),
+                ...(values.count === undefined ? {} : { count: values.count }),
+                ...(values.for === undefined ? {} : { for: values.for }),
+                ...(values.grep === undefined ? {} : { grep: values.grep }),
+                ...(values.task === undefined ? {} : { task: values.task }),
+            }, verbIo());
+            return;
         case 'train':
             return trainCommand(paths, sub, { dryRun: values['dry-run'] === true }, { out });
         case 'unpause':
@@ -810,7 +921,7 @@ async function notifyTest(paths, options) {
         ...(options.kind ? { kind: options.kind } : {}),
         raise: options.raise,
     };
-    // Pushover can take its 15 s, after a Credential Manager read.
+    // Pushover can take its 15 s, after a secret store 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);
@@ -888,33 +999,35 @@ function parsing(command, parse) {
             : 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.
+// The open plan item of `ref`: the item (ENG-312) whose plan waits, or an inbox id written #12; null
+// when no plan of the item waits. A bare number is refused: it could be an issue's number, and the
+// answer is posted as the operator's.
 async function planItem(paths, ref) {
     if (ref.startsWith('#'))
         return inboxId(ref);
+    const items = await openItems(paths);
     if (/^\d+$/.test(ref)) {
-        throw new ConductorError(`"${ref}" is ambiguous`, [
-            `name the item, such as ATK-${ref}, or the inbox id as #${ref}`,
-        ]);
+        // The waiting plans whose key ends in the number, else a placeholder: the project's key isn't known here.
+        const keys = (items ?? []).flatMap((i) => (i.kind === 'plan' && i.item?.endsWith(`-${ref}`) ? [i.item] : []));
+        const item = keys.length > 0 ? keys.join(' or ') : `<KEY>-${ref}`;
+        throw new ConductorError(`"${ref}" is ambiguous`, [`name the item, such as ${item}, 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']);
+        return null;
     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}; the daemon reads ${p.profilePath} again when it starts or the file is saved`
+        ? `${p.problem}; the daemon reads the profile again when it starts, when ~/.conductor/projects/${p.name}.json is saved, and after each fetch of the clone`
         : p.enabled
             ? 'enabled'
             : 'disabled';
-    return `  ${p.name}  ${p.root}  (protocol ${p.protocol}, ${state})`;
+    return `  ${p.name}  ${p.clone}  (protocol ${p.protocol}, ${state})`;
 }
 // The registered projects: from the daemon, or from the store when it isn't running.
 async function projectsNow(paths) {
@@ -959,7 +1072,7 @@ async function removeProject(paths, name) {
         });
     }
     const { project, resolved } = result;
-    out(`removed ${project.name} (${project.root})`);
+    out(`removed ${project.name} (${project.clone})`);
     for (const item of resolved)
         out(`  resolved #${item.id} (${item.kind}${item.item ? ` ${item.item}` : ''})`);
 }
@@ -1009,6 +1122,45 @@ async function retire(paths, ref, force) {
     out(`retired ${worker.name}`);
     steps.forEach((s) => out(`  ${s}`));
 }
+// `conduct revise <item>` with no plan of the item in the inbox: the daemon posts the revise on an
+// approved plan and wakes its worker at once, as its revise sweep would (ATK-664).
+async function reviseApproved(paths, item, text) {
+    const { body, status } = await callApi(paths, {
+        body: { text },
+        method: 'POST',
+        path: `/items/${encodeURIComponent(item)}/revise`,
+        timeoutMs: REVISE_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');
+        // A conductor from before ATK-664 has no such route.
+        if (status === 404)
+            throw new ConductorError(`no plan of ${item} waits in the inbox`, [
+                '`conduct inbox` lists what waits',
+                'a conductor started before ATK-664 revises no approved plan: restart it for that',
+            ]);
+        throw new ConductorError(refusal?.error ?? `the API answered ${status}`, details);
+    }
+    const r = reviseAnswer.parse(body).revise;
+    out(`asked for a revision of ${r.item}'s approved plan: ${r.comment.url ?? r.comment.id}`);
+    out(reviseOutcome(r));
+}
+// What became of a revise of an approved plan after its comment, in one line.
+function reviseOutcome(r) {
+    const none = 'no worker is on it: one launched on it reads the revise in its brief';
+    if (r.pending !== null)
+        return `nothing recorded yet (${r.pending}): ${r.worker ? 'the revise sweep records it and wakes its worker within 5 minutes' : none}`;
+    if (!r.revised)
+        return 'a revise of its plan was recorded already: its worker re-plans on the first one';
+    if (r.woken > 0)
+        return 'woke its worker to re-plan';
+    if (r.landed)
+        return 'its PR has merged: its worker learns of it at its next note, for a follow-up PR';
+    return r.worker ? 'its worker is running: its next note is held back, and it re-plans' : none;
+}
 // `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());
@@ -1089,7 +1241,7 @@ async function shutdownDaemon(paths) {
     if (readEndpoint(paths) !== null) {
         throw new ConductorError(`the conductor (pid ${pid ?? '?'}) did not stop within ${STOP_WAIT_MS / 1000} s`);
     }
-    // The port file goes before the process ends; a start (the logon task's especially) waits for it.
+    // The port file goes before the process ends; a start (the logon startup's especially) waits for it.
     const exitDeadline = Date.now() + STOP_WAIT_MS;
     while (pid !== null && processAlive(pid) && Date.now() < exitDeadline)
         await sleep(100);
@@ -1105,7 +1257,7 @@ 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
+    // A daemon that is still starting (the logon startup'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 {
@@ -1153,7 +1305,7 @@ async function status(paths, json) {
     if (json)
         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:');
+    out(projects.length === 0 ? 'no projects; add one with `conduct project add <url | path>`' : 'projects:');
     projects.forEach((p) => out(projectLine(p)));
     out(workers.length === 0 ? 'no workers' : 'workers:');
     workers.forEach((w) => out(workerLine(w)));
@@ -1191,7 +1343,7 @@ async function stopDaemon(paths) {
             out('the conductor is not running');
             return false;
         case 'supervisor': {
-            // It answers just before it ends; a start (the logon task's especially) needs it gone.
+            // It answers just before it ends; a start (the logon startup's especially) needs it gone.
             const deadline = Date.now() + STOP_WAIT_MS;
             while (processAlive(stop.pid) && Date.now() < deadline)
                 await sleep(100);
@@ -1200,7 +1352,7 @@ async function stopDaemon(paths) {
         }
     }
 }
-// `conduct supervise`: keeps `conduct serve` running (supervise.ts, ATK-417). The logon task runs
+// `conduct supervise`: keeps `conduct serve` running (supervise.ts, ATK-417). The logon startup runs
 // it; `conduct start` runs it with --fail-fast. The config is read again for each push, so one fixed
 // while the daemon is down counts, and one that doesn't load (a reason it may be down) leaves the
 // defaults: no quiet hours, the default credential.
@@ -1222,7 +1374,7 @@ async function superviseCommand(paths, failFast) {
                 rotatingLog(paths.log, config().log).log(...line);
             }
             catch {
-                // Nowhere else to say it: under the logon task nobody reads stderr.
+                // Nowhere else to say it: under the logon startup nobody reads stderr.
             }
         },
     };
@@ -1298,8 +1450,9 @@ async function superviseCommand(paths, failFast) {
     }
     return code;
 }
-function uninstall() {
-    out(removeStartup() ? `removed the "${TASK_NAME}" logon task` : `no "${TASK_NAME}" logon task to remove`);
+async function uninstall() {
+    const task = startup();
+    out((await task.remove()) ? `removed ${task.name}` : `no ${task.name} to remove`);
 }
 // --until: 17:00 (the next one), tomorrow, a day such as monday, or a date and time.
 function untilOf(text) {
@@ -1307,7 +1460,8 @@ function untilOf(text) {
 }
 async function upgradeCommand(paths, tag, allowDowngrade) {
     const cliPath = realpathSync(fileURLToPath(import.meta.url));
-    const release = npmStage({});
+    // npm's own settings, so the tag is read where `npm install --global` installs from (ATK-561).
+    const release = npmStage(sharedNpmReads());
     await upgrade({ allowDowngrade, tag: parseTag(tag) }, {
         ...daemonStarter(paths, cliPath),
         cliPath,