@detergent-software/conductor 0.0.0-stage → 1.0.0-dev.1

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+Releases are tagged `conductor-v<version>` and staged on npm by `atk-conductor-release` (`pipelines/release-conductor.yml`), which writes each section below. `scripts/check-changelog.mjs` fails when a tag has no section here.
+
+## 1.0.0-dev.1 (2026-10-10)
+
+### Features
+
+* **conductor:** add the conductor daemon skeleton (ATK-308) ([a33233b](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/a33233bd47c29416bc3f1db85d10a7904954f7de))
+* **conductor:** add the session manager (ATK-309) ([aee8575](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/aee85752ece203463e8ee027459ea26d80a0c689))
+* **conductor:** add the watchers and conduct wait (ATK-310) ([f803cba](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/f803cba1c8de1b31a4282d259b9439a491c28c57))
+
+### Bug Fixes
+
+* **ci:** keep two npm releases from skipping or doubling (ATK-338) ([76703d3](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/76703d3454ba4abc14b30d5b3b5867eb26b399ce))
+* **conductor:** address code review of the session manager (ATK-309) ([724ffba](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/724ffba72e4278b6819636ccad95310921582001))
+* **conductor:** address review of the watchers (ATK-310) ([05cbb88](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/05cbb88c9efc14aad83dd40a668109de77e2a74a))
+* **conductor:** harden the session manager after review (ATK-309) ([9675c0d](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/9675c0d40d6373429a9f99eeaad5ba78ba54eae5))
+* **conductor:** harden the skeleton after review (ATK-308) ([0930b74](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/0930b74edd9fae6dc94dfa7b62aaf4f13526b0d3))
+* **conductor:** read a turn's end from status alone (ATK-309) ([a42b6d3](https://emergentcode.visualstudio.com/Emergent%20Software/_git/Emergent.AgenticToolkit/commit/a42b6d34f45c309c6da3bae7cf2c3c9d7b2d0032))

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# Conductor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@detergent-software/conductor`: the local daemon that runs the work loop for every conducted project on this machine, and its `conduct` CLI. The design, decisions and build order are in the Linear document *Conductor: design note* (project *Conductor daemon*). This package has build step 1, the skeleton (ATK-308), step 2, the session manager (ATK-309), and step 3, the watchers and `conduct wait` (ATK-310).
+
+## Commands
+
+```text
+conduct serve                     run the daemon in this process (one per machine)
+conduct stop                      stop the running daemon
+conduct status [--json]           the daemon's pid, port, projects and workers
+conduct project add <path>        register the project whose checkout holds .claude/conductor.json
+conduct project list [--json]     the registered projects
+conduct launch <item>             start a worker: worktree, background session, tab
+    [--project <name>] [--probe] [--prompt <text>] [--conductor <name>]
+conduct retire <worker> [--force] stop a worker, remove its worktree and session
+conduct attach <worker>           wake a parked worker (no event text) and open it in a tab
+conduct wait <condition>          wait for an outside event (see Waits)
+conduct install-startup           start the daemon at logon (Windows Task Scheduler)
+conduct install-startup --remove  remove that logon task
+```
+
+A `<worker>` is its item (`ATK-309`) or its name (`probe-ATK-309`).
+
+## Workers
+
+The session manager owns the `claude --bg` sessions it launches, and only those:
+
+- **launch:** the worktree comes first, through the project's `.claude/hooks/worktree-hooks.mjs`. In a repo with `.atk-lock.json`, the profile's work and verify skills must match the lockfile (`atk install` fixes them when it can). Then `claude --bg --worktree <name> -n <name> --disallowedTools EnterPlanMode ExitPlanMode --permission-mode auto -- <prompt>` runs from the main checkout. A profile with `"workers": { "tab": true }` also gets a Windows Terminal tab attached to the session.
+- **park:** a worker with a wait (`POST /waits`) is stopped once `claude agents` shows its turn has ended. Its status becomes `parked`, and its tab closes.
+- **resume:** when a wait resolves, the daemon lets the stop settle (`sessions.settleSeconds`). It checks the process has exited, then runs `claude --bg --resume <session> -- "[conductor] event: …"`. The session keeps its name, model, permission mode and disallowed tools. A resume of a session that still runs starts a copy; the daemon stops and removes the copy, then tries again.
+- **retire:** refuses uncommitted or unpushed work, and a worker whose turn still runs, unless `--force`. It never retires a session that is still starting. Then it stops the session, removes the worktree and runs `claude rm`. If the stop fails, nothing is removed.
+- **restarts:** a launch the daemon was stopped in adopts its session if one was started, and otherwise fails and removes its clean worktree.
+- **attach:** a parked worker is resumed with no event text, so it wakes idle and keeps running when its tab closes. An attached worker isn't parked until it registers a new wait, or until its turn has been over `sessions.idleMinutes` (`worker.detached`). The daemon can't see the tab, so this also delivers a wait that resolved while it was attached.
+- **park failures:** a session whose process outlives `claude stop` by 30 s logs one `worker.park-failed` per spell, and the park is tried again every 5 minutes.
+- **stalls:** a permission prompt open `sessions.permissionMinutes` (5), or idle `sessions.idleMinutes` (20) with no wait, logs one `worker.stalled` event per spell.
+- **spend:** tokens from the session's transcript and its subagents' (`~/.claude/projects/*/<session>.jsonl`), each message counted once, go into `spend` per worker and local day. It keeps input, output, cache read and cache write; `tokens` is their sum.
+- **probes:** `--probe` names the worktree and session `probe-<item>` and gives it a prompt that works no issue, so tests stay out of the live fleet.
+
+Worker statuses: `launching`, `running`, `parked`, `stopped-unexpectedly`, `failed`, `exited`. Every step is an event (`worker.launched`, `worker.parked`, `worker.resumed`, …) on `GET /events`.
+
+## Waits
+
+A worker waits by posting its note, running `conduct wait …` and ending the turn (worker protocol v1). The verbs take the repo, host and package from the worktree's `.claude/conductor.json`; the full form is accepted too, and is what the store keeps:
+
+| Verb | Full form | Holds when |
+|---|---|---|
+| `pr 1850 merged` | `pr:ado:Emergent.AgenticToolkit#1850:merged` | the PR is completed (or abandoned: that resolves it too, as a fact) |
+| `pr 1850 checks` | `…#1850:checks` | no blocking build of the PR's current commit is queued or running (passed or failed; a path-filtered build it doesn't touch counts as passed) |
+| `pr 1850 comment` | `…#1850:comment` | a thread is open whose last word isn't a work-skill note |
+| `pr 458 merged --repo <owner>/<repo>` | `pr:github:<owner>/<repo>#458:merged` | the same on GitHub; `comment` there is a person's comment or review after the wait was registered |
+| `run atk-api-deploy 12345 done` | `run:ado:atk-api-deploy#12345:done` | the run completed, with its result |
+| `npm 8.5.0-dev.2 --tag dev` | `npm:@detergent-software/atk@8.5.0-dev.2:dev` | the dist-tag points at the version |
+| `health dev --version 1.2.3` / `--commit <sha>` | `health:dev:version=1.2.3` | the profile's `health.dev` URL answers with that version or commit |
+| `approval` | `approval:linear:ATK-310` | an `approve` / `revise:` comment by the Linear key's owner after the item's newest `<work skill> · Plan` note |
+| `item ATK-271 done` / `label human` / `note Landed` | `item:linear:ATK-271:state=done` | the state (name or type), a label, or a phase note |
+| `time 2026-10-10T09:00` | `time:2026-10-10T14:00:00.000Z` | the time has passed (no zone means local time) |
+
+- **With the daemon**, in a worker's worktree (or with `--worker <worker>`), `conduct wait` registers the wait and returns at once. The daemon parks the session when its turn ends and resumes it with `[conductor] event: <resolution> HH:MM` once the condition holds. The text is a fact, never an approval: the worker reads the source again. The daemon checks waits against the project's profile as registered (`conduct project add`), and refuses one it can't check, such as a `health` environment the profile has no URL for.
+- **Without a daemon**, with `--local`, or when the daemon doesn't answer, it checks the condition itself and blocks. It prints `[conductor] event: …` and exits 0 when the condition holds, or exits 2 after `--timeout` minutes (29: Monitor ends a command at 30) so the caller can run it again. A wait that can't be checked (a PR that doesn't exist, no Linear key, `az` not signed in) exits 1. `--timeout` applies only here.
+
+**Watchers.** One per API: Linear (GraphQL with `LINEAR_API_KEY` or the `atk-conductor-linear` credential, ported from conduct-atk), Azure DevOps (REST with the `az login` token), GitHub (`gh api`), npm (the registry's dist-tags, no cache) and `/health`. Time waits are the session manager's sweep. An API is asked nothing while no wait needs it. Otherwise it's asked once per `watchers.<api>.intervalSeconds`, within `perMinute` requests in any rolling minute shared by every project. Each pass covers all of that API's waits in as few requests as it can; Linear's is one request, filtered on `updatedAt` (with a 2-minute overlap) after the first. A pass that runs out of budget stops, and the next one starts a wait further on. A failing API waits twice as long each time (up to 10 minutes) and logs `watcher.failed` once, then `watcher.recovered`. A wait that can't be checked logs `wait.check-failed` once and stays open. Every `watchers.statsMinutes` (10) in which anything waited, a `watcher.stats` event records each API's passes, requests, budget skips, failures and waits.
+
+## Files
+
+Everything lives in `~/.conductor` (`CONDUCTOR_HOME` overrides it):
+
+| File | Holds |
+|---|---|
+| `config.json` | machine settings, JSONC (comments allowed), validated at startup; `sessions` holds `pollSeconds` (10), `settleSeconds` (5), `permissionMinutes` (5), `idleMinutes` (20); `watchers` holds `ado`, `github`, `health`, `linear` and `npm`, each `{ intervalSeconds, perMinute }` (30/60, 30/30, 30/30, 30/10, 20/30), and `statsMinutes` (10) |
+| `token` | the API token, readable by this user only; every request sends `Authorization: Bearer <token>` |
+| `conductor.pid`, `port` | the single-instance lock and where the API listens (`127.0.0.1`) |
+| `conductor.db` | SQLite state, including the append-only `events` log |
+| `logs/conductor.log` | the rotating log |
+
+## API
+
+- `GET /projects`: the registered projects. `POST /projects` with `{ "path": "<absolute path>" }` registers one.
+- `GET /events`: the event log as server-sent events. Add `?since=<id>` (or send `Last-Event-ID`) to replay from an id. Without either, the stream starts at the live end.
+- `POST /shutdown`: a clean stop (`conduct stop`).
+- `GET /fleet`: the workers in flight, with session activity, waits and spend (today, total).
+- `POST /workers` with `{ "item": "ATK-309", "project"?, "probe"?, "prompt"?, "conductor"? }`: launch; answers 202 with the `launching` worker. `GET /workers/:id` shows it with its latest events.
+- `DELETE /workers/:id` (`?force=true`): retire; 409 with the unfinished work when it refuses.
+- `POST /workers/:id/attach`: wake if parked, mark attached, open the tab.
+- `POST /waits` with `{ "worker": 1, "condition": "pr:ado:Emergent.AgenticToolkit#1850:merged" }`: a wait in its full form (see Waits), stored in its normal form; 201 with the wait. `GET /waits/:id` shows one, with its resolution once it has one.
+- A refusal (a duplicate launch, a bad condition, a busy worker) is a 409 with `error` and `details`.
+
+## On PATH
+
+Install the package globally, next to `atk`. `dev` follows `develop`; `latest` follows `main`:
+
+```bash
+npm install --global @detergent-software/conductor@dev
+conduct install-startup
+conduct project add <path to the project's main checkout>
+```
+
+`conduct project add` walks up from the path it is given to the directory that holds `.claude/conductor.json`, and maps a worktree to its main checkout.
+
+The logon task runs `node` on the `cli.js` that ran `install-startup`. A global install keeps that path across upgrades, so the task needs registering once. To upgrade, stop the daemon, install, and start it again (or sign out and back in):
+
+```bash
+conduct stop
+npm install --global @detergent-software/conductor@dev
+conduct serve
+```
+
+**From a checkout instead (development).** `npm link` puts the main checkout's build on PATH, so every worktree and the logon task run that build. Run it from the main checkout, and upgrade by pulling `develop`, building, then `conduct stop` and `conduct serve`:
+
+```bash
+pnpm install
+pnpm -C apps/conductor build
+(cd apps/conductor && npm link)
+conduct install-startup
+```
+
+To switch from a linked build to the package: `conduct stop`, `npm rm --global @detergent-software/conductor` (removes the link), install the package as above, and run `conduct install-startup` again so the logon task points at the installed `cli.js`.
+
+## Releases
+
+`atk-conductor-release` (`pipelines/release-conductor.yml`) runs semantic-release on each push to `develop` or `main` that touches `apps/conductor/`. It counts only commits that touch this directory, writes `CHANGELOG.md`, tags `conductor-v<version>` (`X.Y.Z-dev.N` on `develop`), and stages the version on npm under `dev` or `latest`. A maintainer publishes it with the `npm stage approve <id> --otp=<code>` line from the run summary.
+
+## Development
+
+```bash
+pnpm -C apps/conductor lint
+pnpm -C apps/conductor typecheck
+pnpm -C apps/conductor test
+pnpm -C apps/conductor build
+cd apps/conductor && node scripts/check-changelog.mjs
+```

package/build/claude.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { ConductorError } from "./errors.js";
+import { outputOf, run } from "./run.js";
+// One row of `claude agents --json --all`. Only the fields the session manager reads; the rest pass.
+export const agentSessionSchema = z.looseObject({
+    cwd: z.string().optional(),
+    id: z.string(),
+    kind: z.string().optional(),
+    name: z.string().optional(),
+    pid: z.number().optional(),
+    sessionId: z.string(),
+    // working | done | blocked: the agent view's label for the work, from the model's last reply.
+    // Not whether a turn runs (that is `status`), except before a new session has its pid.
+    state: z.string().optional(),
+    // idle | busy | waiting; `waiting` comes with `waitingFor` (a permission prompt, input).
+    status: z.string().optional(),
+    waitingFor: z.string().optional(),
+});
+export function claudeCli() {
+    // Resolves to stdout, and stderr after it: the CLI prints its notes (such as a copy started) there.
+    const claude = async (args, cwd, timeoutMs = 120_000) => {
+        const result = await run('claude', args, { cwd, timeoutMs });
+        if (result.code !== 0)
+            throw new ConductorError(`claude ${args[0]} failed`, [outputOf(result, 500)]);
+        return { all: result.stdout + result.stderr, stdout: result.stdout };
+    };
+    return {
+        // Only stdout is JSON; a notice on stderr must not break the listing.
+        agents: async () => parseAgents((await claude(['agents', '--json', '--all'], undefined, 60_000)).stdout),
+        launch: async (request) => {
+            // The create hook (branch, pnpm install, atk install) runs first, so allow it minutes.
+            const output = (await claude(launchArgs(request), request.cwd, 10 * 60_000)).all;
+            const handle = parseHandle(output);
+            if (!handle)
+                throw new ConductorError('claude --bg printed no session id', [output.trim().slice(-500)]);
+            return handle;
+        },
+        resume: async ({ cwd, sessionId, text }) => {
+            const output = await claude(['--bg', '--resume', sessionId, ...(text === null ? [] : ['--', text])], cwd);
+            return { copy: parseCopy(output.all) };
+        },
+        rm: async (handle) => void (await claude(['rm', handle])),
+        stop: async (handle) => void (await claude(['stop', handle])),
+    };
+}
+// The session's process exists. `state: "done"` only means the turn ended.
+export function isLive(session) {
+    return session.pid !== undefined || isStarting(session);
+}
+// Listed as working before it has a pid: `claude --bg` is still creating its worktree.
+export function isStarting(session) {
+    return session.pid === undefined && session.state === 'working';
+}
+// The flags a worker starts with. A resume keeps them: `claude --bg --resume` wakes a session
+// "with its saved options (-n, --permission-mode, --disallowedTools, --model)" (ATK-309's check).
+// Workers get no plan-mode tools: an ExitPlanMode dialog passes on one stray key (ATK-269).
+export function launchArgs(request) {
+    return [
+        '--bg',
+        '--worktree',
+        request.worktree,
+        '-n',
+        request.name,
+        '--disallowedTools',
+        ...request.disallowedTools,
+        '--permission-mode',
+        request.permissionMode,
+        '--',
+        request.prompt,
+    ];
+}
+// The sessions in `claude agents --json --all` that have a short id. Interactive sessions are
+// listed without one; the daemon never manages those, and one odd row mustn't hide the rest.
+export function parseAgents(text) {
+    return z
+        .array(z.unknown())
+        .parse(JSON.parse(text))
+        .flatMap((row) => {
+        const session = agentSessionSchema.safeParse(row);
+        return session.success ? [session.data] : [];
+    });
+}
+// A resume of a session that still runs starts a copy and says so. The copy has no name and
+// doesn't show in `claude agents --json --all`, so this line is the only trace of it.
+export function parseCopy(output) {
+    return /started a copy as ([0-9a-f]{8})\b/.exec(output)?.[1] ?? null;
+}
+// `claude --bg` prints `backgrounded · <id> · <name>`.
+export function parseHandle(output) {
+    return /backgrounded · ([0-9a-f]{8})\b/.exec(output)?.[1] ?? null;
+}
+export function permissionPrompt(session) {
+    return session.status === 'waiting' && /permission/i.test(session.waitingFor ?? '') ? (session.waitingFor ?? null) : null;
+}
+// The turn ended and nothing holds the session: no tool running, no prompt open, no Monitor armed
+// (an armed Monitor reads busy). Only `status` says so. `state` is the agent view's label for how
+// the work is going, taken from the last reply: a probe that answered an event with "I'm still
+// waiting" stayed `state: working` at `status: idle` for minutes (ATK-309).
+export function turnEnded(session) {
+    return session.pid !== undefined && session.status === 'idle';
+}
+//# sourceMappingURL=claude.js.map

package/build/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../src/claude.ts"],"names":[],"mappings":"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"}

package/build/cli.js

@@ -0,0 +1,383 @@
+#!/usr/bin/env node
+import { mkdirSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { z } from 'zod';
+import { callApi, NotRunningError, readEndpoint } from "./client.js";
+import { startDaemon } from "./daemon.js";
+import { ConductorError } from "./errors.js";
+import { readPid } from "./lock.js";
+import { fleetWorkerSchema } from "./manager.js";
+import { conductorPaths } from "./paths.js";
+import { registerProject } from "./registry.js";
+import { installStartup, removeStartup, TASK_NAME } from "./startup.js";
+import { openStore, projectSchema, workerSchema } from "./store.js";
+import { 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
+  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 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>]
+  install-startup           start the daemon at logon (Windows Task Scheduler)
+  install-startup --remove  remove that logon task
+
+A <worker> is its item (ATK-309) or its name (probe-ATK-309).
+Files live in ~/.conductor (CONDUCTOR_HOME overrides it).`;
+const STOP_WAIT_MS = 10_000;
+// A launch makes a worktree (pnpm install) before the session starts.
+const LAUNCH_WAIT_MS = 15 * 60_000;
+// The daemon's worst cases, so the CLI never gives up on an operation that still runs: retire
+// lists sessions (60 s), stops one (120 s + 30 s), removes the worktree (5 min), rms it (120 s);
+// 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;
+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() });
+const fleetBody = z.object({ workers: z.array(fleetWorkerSchema) });
+const workerBody = z.object({ worker: workerSchema });
+const workerDetailBody = z.object({
+    events: z.array(z.object({ data: z.record(z.string(), z.unknown()), kind: z.string() })),
+    worker: workerSchema,
+});
+const retireBody = z.object({
+    outcome: z.enum(['partial', 'refused', 'retired']),
+    reason: z.string().optional(),
+    steps: z.array(z.object({ error: z.string().optional(), ok: z.boolean(), step: z.string() })).optional(),
+    work: z
+        .object({ dirty: z.array(z.string()).optional(), unknown: z.string().optional(), unpushed: z.number().optional() })
+        .optional(),
+    worker: workerSchema,
+});
+const attachBody = z.object({ resumed: z.boolean(), tab: z.string().nullable(), worker: workerSchema });
+async function addProject(paths, path) {
+    const absolute = resolve(path);
+    let result;
+    try {
+        result = addBody.parse(await expectOk(callApi(paths, { body: { path: absolute }, method: 'POST', path: '/projects' })));
+    }
+    catch (error) {
+        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));
+    }
+    out(`${result.created ? 'registered' : 'updated'} ${projectLine(result.project).trim()}`);
+}
+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 })));
+    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}`);
+}
+async function expectOk(call) {
+    const { body, status } = await call;
+    if (status >= 200 && status < 300)
+        return body;
+    const error = errorBody.safeParse(body);
+    throw new ConductorError(error.success ? error.data.error : `the API answered ${status}`, error.data?.details ?? []);
+}
+// A worker in flight by item or name. A probe and a live worker can share an item, so a name match wins.
+async function findWorker(paths, ref) {
+    const { workers } = fleetBody.parse(await expectOk(callApi(paths, { method: 'GET', path: '/fleet' })));
+    const byName = workers.filter((w) => w.name === ref);
+    const matches = byName.length > 0 ? byName : workers.filter((w) => w.item === ref);
+    if (matches.length === 1 && matches[0])
+        return matches[0];
+    if (matches.length === 0)
+        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);
+}
+function install() {
+    const cliPath = realpathSync(fileURLToPath(import.meta.url));
+    installStartup({ cliPath, nodePath: process.execPath });
+    out(`registered the "${TASK_NAME}" logon task: ${process.execPath} ${cliPath} serve`);
+    if (cliPath.includes(`${sep}.claude${sep}worktrees${sep}`)) {
+        out('warning: that build is in a worktree, which goes away; run install-startup from the main checkout');
+    }
+}
+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`);
+    const deadline = Date.now() + LAUNCH_WAIT_MS;
+    while (Date.now() < deadline) {
+        await sleep(2000);
+        const detail = workerDetailBody.parse(await expectOk(callApi(paths, { method: 'GET', path: `/workers/${worker.id}` })));
+        const { status } = detail.worker;
+        if (status === 'launching')
+            continue;
+        if (status === 'failed') {
+            const failure = detail.events.find((e) => e.kind === 'worker.launch-failed')?.data ?? {};
+            throw new ConductorError(`could not launch ${worker.name}`, [
+                `${String(failure.step ?? 'launch')}: ${String(failure.error ?? 'see the log')}`,
+            ]);
+        }
+        out(`launched ${worker.name}: session ${detail.worker.handle ?? '?'}, worktree ${detail.worker.worktree ?? '?'}`);
+        return;
+    }
+    throw new ConductorError(`${worker.name} is still launching after ${LAUNCH_WAIT_MS / 60_000} min`, [
+        '`conduct status` shows it; the daemon carries on',
+    ]);
+}
+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());
+    }
+    if (json)
+        return out(JSON.stringify(projects, null, 2));
+    if (projects.length === 0)
+        return out('no projects; add one with `conduct project add <path>`');
+    projects.forEach((p) => out(projectLine(p)));
+}
+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));
+    const { positionals, values } = parseArgs({
+        allowPositionals: true,
+        args: argv,
+        options: {
+            conductor: { type: 'string' },
+            force: { type: 'boolean' },
+            help: { short: 'h', type: 'boolean' },
+            json: { type: 'boolean' },
+            probe: { type: 'boolean' },
+            project: { type: 'string' },
+            prompt: { type: 'string' },
+            remove: { type: 'boolean' },
+            version: { short: 'v', type: 'boolean' },
+        },
+    });
+    const paths = conductorPaths();
+    const [command, sub, arg] = positionals;
+    if (values.version)
+        return out(version());
+    if (values.help || command === undefined || command === 'help')
+        return out(USAGE);
+    switch (command) {
+        case 'attach':
+            if (sub === undefined)
+                throw new ConductorError('usage: conduct attach <worker>');
+            return attach(paths, sub);
+        case 'install-startup':
+            return values.remove ? uninstall() : install();
+        case 'launch':
+            if (sub === undefined)
+                throw new ConductorError('usage: conduct launch <item> [--project <name>] [--probe]');
+            return launch(paths, sub, {
+                conductor: values.conductor,
+                probe: values.probe,
+                project: values.project,
+                prompt: values.prompt,
+            });
+        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 '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 'status':
+            return status(paths, values.json === true);
+        case 'stop':
+            return stop(paths);
+        default:
+            throw new ConductorError(`unknown command "${command}"`, ['run `conduct help` for the commands']);
+    }
+}
+function out(line) {
+    process.stdout.write(`${line}\n`);
+}
+function projectLine(p) {
+    const state = p.problem ? `${p.problem}; run \`conduct project add\` again` : p.enabled ? 'enabled' : 'disabled';
+    return `  ${p.name}  ${p.root}  (protocol ${p.protocol}, ${state})`;
+}
+async function retire(paths, ref, force) {
+    const worker = await findWorker(paths, ref);
+    const { body, status } = await callApi(paths, {
+        method: 'DELETE',
+        path: `/workers/${worker.id}${force ? '?force=true' : ''}`,
+        timeoutMs: RETIRE_TIMEOUT_MS,
+    });
+    const parsed = retireBody.safeParse(body);
+    if (!parsed.success) {
+        await expectOk(Promise.resolve({ body, status })); // a plain error answer
+        throw new ConductorError(`the API answered ${status} with an unexpected body`);
+    }
+    const result = parsed.data;
+    const steps = (result.steps ?? []).map((s) => `${s.step}: ${s.ok ? 'ok' : `failed (${s.error ?? '?'})`}`);
+    if (result.outcome === 'refused') {
+        const work = [
+            ...(result.work?.unpushed ? [`${result.work.unpushed} unpushed commit(s)`] : []),
+            ...(result.work?.dirty ? [`uncommitted: ${result.work.dirty.join(', ')}`] : []),
+            ...(result.work?.unknown ? [`not checked: ${result.work.unknown}`] : []),
+        ];
+        throw new ConductorError(`refused to retire ${worker.name}: ${result.reason ?? ''}`, work);
+    }
+    if (result.outcome === 'partial')
+        throw new ConductorError(`retired ${worker.name} only in part`, steps);
+    out(`retired ${worker.name}`);
+    steps.forEach((s) => out(`  ${s}`));
+}
+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);
+    });
+    await daemon.closed;
+}
+function sleep(ms) {
+    return new Promise((done) => setTimeout(done, ms));
+}
+async function status(paths, json) {
+    let projects;
+    try {
+        projects = projectsBody.parse(await expectOk(callApi(paths, { method: 'GET', path: '/projects' }))).projects;
+    }
+    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));
+        process.exitCode = 1;
+        return;
+    }
+    const { workers } = fleetBody.parse(await expectOk(callApi(paths, { method: 'GET', path: '/fleet' })));
+    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));
+    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)));
+}
+async function stop(paths) {
+    const pid = readPid(paths.pid);
+    try {
+        await expectOk(callApi(paths, { method: 'POST', path: '/shutdown' }));
+    }
+    catch (error) {
+        if (!(error instanceof NotRunningError))
+            throw error;
+        out('the conductor is not running');
+        return;
+    }
+    const deadline = Date.now() + STOP_WAIT_MS;
+    while (readEndpoint(paths) !== null && Date.now() < deadline)
+        await sleep(100);
+    if (readEndpoint(paths) !== null) {
+        throw new ConductorError(`the conductor (pid ${pid ?? '?'}) did not stop within ${STOP_WAIT_MS / 1000} s`);
+    }
+    out(`stopped the conductor (pid ${pid ?? '?'})`);
+}
+function uninstall() {
+    out(removeStartup() ? `removed the "${TASK_NAME}" logon task` : `no "${TASK_NAME}" logon task to remove`);
+}
+function version() {
+    return z.object({ version: z.string() }).parse(createRequire(import.meta.url)('../package.json')).version;
+}
+async function wait(argv) {
+    const { positionals, values } = parseArgs({
+        allowPositionals: true,
+        args: argv,
+        options: {
+            commit: { type: 'string' },
+            item: { type: 'string' },
+            local: { type: 'boolean' },
+            package: { type: 'string' },
+            repo: { type: 'string' },
+            tag: { type: 'string' },
+            timeout: { type: 'string' },
+            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']);
+    process.exitCode = await waitCommand(conductorPaths(), positionals, { ...values, timeoutMinutes: timeout }, { cwd: process.cwd(), err: (line) => process.stderr.write(`${line}\n`), out });
+}
+function withStore(paths, use) {
+    mkdirSync(paths.home, { recursive: true });
+    const store = openStore(paths.db);
+    try {
+        return use(store);
+    }
+    finally {
+        store.close();
+    }
+}
+// One line per worker: name, project, status and session activity, its 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}`,
+        ...(waits.length > 0 ? [`waits: ${waits.join(', ')}`] : []),
+        `spend ${formatTokens(w.spend.today)} today, ${formatTokens(w.spend.total)} total`,
+    ].join('  ·  ');
+}
+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`);
+    }
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map