@bakers-build/conductor 0.0.0-stage → 0.1.0-next.38

package/dist/src/commands/conductor.js

@@ -0,0 +1,843 @@
+import { spawnSync } from 'node:child_process';
+import { basename, dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { CommandRunner, checkForUpdate, createBbConnectionClient, createLogger, declineUpdate, defaultProcProbe, deriveCheckoutRoot, deriveConductorLiveness, loadReadyBbConnection, printVersionLine, resolveConfigPath, setDefaultCommandRunner, signalVerifiedProcess, stemForConfigFile, updateNotice, verifyConductorProcess, } from '@bakers-build/core';
+import { Command } from 'commander';
+import { authStatus } from 'dropsh';
+import { resolveBbProjectContext } from '../bakers-project-context.js';
+import { composeConductorConfig, loadConductorConfig } from '../config.js';
+import { Conductor } from '../core/conductor.js';
+import { hostKeyOf } from '../core/host-key.js';
+import { selectAgents, selectExecutor, selectRemote, selectWorkspace, } from '../plugins/plugins.js';
+/** Default host bases for connection/plugin resolution when none is injected. */
+function defaultHost() {
+    return { resolveBases: [import.meta.url, `${process.cwd()}/`] };
+}
+/**
+ * Resolve + compose the full conductor config: the engine half
+ * (`conductor.config.js` via `loadConductorConfig`) plus the connection half
+ * (`bakers.config.js` via `loadBbConfig`, walk-up → home → shipped fallback).
+ * `--config` / `$BB_CONDUCTOR_CONFIG` selects the engine file; the connection
+ * is resolved from cwd.
+ */
+async function resolveConfig(deps, configPathOverride, resolveProject = false) {
+    if (deps.config) {
+        return deps.config;
+    }
+    const host = deps.host ?? defaultHost();
+    const engine = await loadConductorConfig(resolveConfigPath(configPathOverride));
+    if (!resolveProject) {
+        const connection = await loadReadyBbConnection(host, {
+            ...(engine.bakers.workspace
+                ? { workspaceSelector: engine.bakers.workspace }
+                : {}),
+        });
+        return composeConductorConfig(engine, connection);
+    }
+    const unscoped = await loadReadyBbConnection(host, {
+        workspaceIdOverride: '',
+    });
+    const client = await createBbConnectionClient(unscoped);
+    const context = await resolveBbProjectContext(client, engine.bakers);
+    const connection = await loadReadyBbConnection(host, {
+        workspaceIdOverride: '',
+        workspaceSelector: context.workspaceId,
+    });
+    return {
+        ...composeConductorConfig(engine, connection),
+        resolved_bakers: context,
+    };
+}
+async function resolveRemote(deps, config) {
+    return deps.remote ?? (await selectRemote(config));
+}
+/**
+ * The checkout root this conductor serves — the top of the working tree, not
+ * its `.bakers` config directory (BB-450 D3). Resolved through the one shared
+ * helper `deriveHerdrRoot()` already implemented, now `@bakers-build/core`'s
+ * `deriveCheckoutRoot()`, so this call site cannot regress to a bare
+ * `dirname(config_path)`.
+ */
+function checkoutRootOf(config) {
+    return deriveCheckoutRoot(config.config_path);
+}
+/**
+ * The conductor's stable identity (bb_conductor.conductor_id). Required —
+ * the loader throws without it — so lifecycle commands read it here, never
+ * re-derive. Soft-reads legacy machine_id during the BB-353 cutover.
+ */
+function conductorIdOf(config) {
+    const id = config.conductor_id ?? config.machine_id;
+    if (id === undefined || id.trim() === '') {
+        throw new Error('conductor config has no conductor_id');
+    }
+    return id;
+}
+/**
+ * Where a conductor keeps the frozen tickets it has observed, beside its
+ * config file, so freeze hooks survive a restart and a one-shot poll.
+ */
+function frozenStateFileOf(config) {
+    const file = config.config_path;
+    return join(dirname(file), `${basename(file, '.js')}.frozen.json`);
+}
+/** Read the `conductor`-level --log-level / --log-sink flags from a subcommand. */
+function logOptsOf(cmd) {
+    const opts = cmd.optsWithGlobals();
+    return {
+        ...(opts.logLevel !== undefined ? { level: opts.logLevel } : {}),
+        ...(opts.logSink !== undefined ? { sink: opts.logSink } : {}),
+    };
+}
+/** Create the conductor logger (with CLI log overrides) and route all exec logging through it. */
+function loggerFor(checkoutRoot, log = {}) {
+    const logger = createLogger({ checkoutRoot, ...log });
+    setDefaultCommandRunner(new CommandRunner(logger));
+    return logger;
+}
+function herdrHostOf(deps, config) {
+    const host = deps.herdr ?? config.processHost;
+    if (!host) {
+        throw new Error('no herdr process host — add @bakers-build/addon-herdr to conductor addons');
+    }
+    return host;
+}
+/**
+ * The liveness words this CLI prints.
+ *
+ * Delegated to core so `bakers oven ls`, the cockpit and the server-side
+ * deriver describe one conductor identically. The previous CLI-only vocabulary
+ * (`wedged`, `stopped`, `host-missing`, `registry-only`) went with the registry
+ * that made those distinctions expressible.
+ *
+ * BB-473: `deriveConductorLiveness` MUST NOT change — it also classifies
+ * REMOTE conductors this machine cannot probe. This function additionally
+ * probes the LOCAL pid, when both `thisHostKey` is given and it is this
+ * conductor's own host (`hub.hostKey === thisHostKey`) with a positive
+ * `lastPid` on record. `verifyConductorProcess` (the read-only half of the
+ * pid-signal proof; BB-450 D1) either leaves the record's word alone
+ * (host-mismatch / no-pid / an unverifiable platform, or a genuinely live,
+ * verified pid) or, on `stale-pid` — the process is provably gone or was
+ * recycled by something else — overrides it to `offline`: positive proof the
+ * process is gone beats a lease-derived guess. The printed word always stays
+ * one of `online | stale | offline` — no fourth word is invented.
+ */
+function classify(hub, thisHostKey, probe) {
+    const recordDerived = deriveConductorLiveness(hub, Math.floor(Date.now() / 1000));
+    if (!thisHostKey ||
+        hub.hostKey !== thisHostKey ||
+        !Number.isInteger(hub.lastPid) ||
+        (hub.lastPid ?? 0) <= 0) {
+        return recordDerived;
+    }
+    const verified = verifyConductorProcess({
+        pid: hub.lastPid,
+        hostKey: hub.hostKey,
+        thisHostKey,
+        ...(probe ? { probe } : {}),
+    });
+    return !verified.ok && verified.reason === 'stale-pid'
+        ? 'offline'
+        : recordDerived;
+}
+async function buildLsRows(remote, config, onlyId, probe) {
+    let hub = [];
+    try {
+        hub = await remote.listConductors('me');
+    }
+    catch {
+        hub = [];
+    }
+    // BB-473: the local-pid probe in `classify` needs to know THIS machine's
+    // host_key (to gate it to rows that are this machine's own conductor) —
+    // `config` used to be ignored here, which is why `ls`/`status` never probed
+    // the local pid at all and relied purely on the record.
+    const thisHostKey = config ? hostKeyOf(config) : undefined;
+    return hub
+        .filter((c) => !onlyId || c.id === onlyId)
+        .map((c) => ({
+        id: c.id,
+        project: c.project,
+        label: c.label,
+        workspaceRoot: c.workspaceRoot,
+        status: classify(c, thisHostKey, probe),
+    }));
+}
+function printRows(rows) {
+    if (rows.length === 0) {
+        console.log('no conductors on the control plane');
+        return;
+    }
+    for (const r of rows) {
+        console.log(`${r.id}\t${r.status}\t${r.project}\t${r.label}\t${r.workspaceRoot}`);
+    }
+}
+// --- command handlers -------------------------------------------------------
+/**
+ * Start-time auth gate. Returns true if authenticated (session or session-less
+ * provider); otherwise logs a single clear line and returns false.
+ */
+export async function ensureAuthenticated(config, logger) {
+    const st = await authStatus({
+        baseUrl: config.site.base_url,
+        plugins: config.plugins ?? [],
+    });
+    if (!st.loggedIn) {
+        logger.error({ baseUrl: config.site.base_url }, `not logged in against ${config.site.base_url} — run 'bakers dropsh auth login'`);
+        return false;
+    }
+    return true;
+}
+async function cmdPoll(deps, log = {}) {
+    const config = await resolveConfig(deps, undefined, true);
+    const checkoutRoot = await checkoutRootOf(config);
+    const logger = loggerFor(checkoutRoot, log);
+    if (!(await ensureAuthenticated(config, logger)))
+        return;
+    const remote = await resolveRemote(deps, config);
+    const executor = deps.executor ?? (await selectExecutor(config, logger));
+    const workspace = deps.workspace ?? (await selectWorkspace(config, logger));
+    const agents = deps.agents ?? (await selectAgents(config));
+    const conductor = new Conductor(config, remote, executor, workspace, agents, logger, checkoutRoot, frozenStateFileOf(config));
+    await conductor.start();
+    await conductor.tick();
+}
+async function cmdReap(deps, log = {}) {
+    const config = await resolveConfig(deps, undefined, true);
+    const checkoutRoot = await checkoutRootOf(config);
+    const logger = loggerFor(checkoutRoot, log);
+    if (!(await ensureAuthenticated(config, logger)))
+        return;
+    const remote = await resolveRemote(deps, config);
+    const executor = deps.executor ?? (await selectExecutor(config, logger));
+    const workspace = deps.workspace ?? (await selectWorkspace(config, logger));
+    const agents = deps.agents ?? (await selectAgents(config));
+    const conductor = new Conductor(config, remote, executor, workspace, agents, logger, checkoutRoot);
+    await conductor.reap();
+}
+/**
+ * BB-474: `--foreground`'s one-per-project guard. Unlike `cmdStartBody`'s
+ * entity-derived check (`classify(existing) === 'online'`), liveness here is
+ * proven by an actual pid probe (`verifyConductorProcess`) of the recorded
+ * `last_pid` — a stale record whose process is dead never blocks a fresh
+ * start, and a record whose `host_key` differs from this host's never blocks
+ * one either, since `verifyConductorProcess` refuses to confirm a pid it
+ * cannot attribute to this host. Returns `true` when the caller must stop
+ * (this process refused, or a `--force` restart failed) — never a signal:
+ * `verifyConductorProcess` observes, it does not touch, the process it checks.
+ */
+async function refuseIfAlreadyRunning(remote, id, thisHostKey, force, deps) {
+    const existing = (await remote.listConductors('me')).find((c) => c.id === id);
+    if (!existing)
+        return false;
+    const probe = deps.procProbe ?? defaultProcProbe();
+    const verified = verifyConductorProcess({
+        pid: existing.lastPid,
+        hostKey: existing.hostKey,
+        thisHostKey,
+        probe,
+    });
+    if (!verified.ok)
+        return false;
+    if (!force) {
+        const age = heartbeatAgeSeconds(existing);
+        console.log(`conductor ${id} already running (pid ${existing.lastPid ?? 'unknown'}, ` +
+            `heartbeat ${age === undefined ? 'age unknown' : `${age}s old`})`);
+        return true;
+    }
+    const stopOutcome = signalVerifiedProcess({
+        pid: existing.lastPid,
+        hostKey: existing.hostKey,
+        thisHostKey,
+        signal: 'SIGTERM',
+        probe,
+    });
+    if (!stopOutcome.ok) {
+        console.log(`failed to restart conductor ${id}: could not stop the running conductor — ${stopOutcome.message}`);
+        process.exitCode = 1;
+        return true;
+    }
+    if (!(await waitForNotRunning(probe, stopOutcome.pid, deps))) {
+        const killOutcome = signalVerifiedProcess({
+            pid: existing.lastPid,
+            hostKey: existing.hostKey,
+            thisHostKey,
+            signal: 'SIGKILL',
+            probe,
+        });
+        if (!killOutcome.ok) {
+            console.log(`failed to restart conductor ${id}: still running after the grace period, and could not force-stop it — ${killOutcome.message}`);
+            process.exitCode = 1;
+            return true;
+        }
+        if (!(await waitForNotRunning(probe, killOutcome.pid, deps))) {
+            console.log(`failed to restart conductor ${id}: sent SIGKILL but it is still reported running — refusing a second spawn`);
+            process.exitCode = 1;
+            return true;
+        }
+    }
+    console.log(`stopped conductor ${id} for restart (--force)`);
+    return false;
+}
+async function cmdStartForeground(deps, log = {}, force = false) {
+    const config = await resolveConfig(deps, undefined, true);
+    const checkoutRoot = await checkoutRootOf(config);
+    const logger = loggerFor(checkoutRoot, log);
+    if (!(await ensureAuthenticated(config, logger)))
+        return;
+    const remote = await resolveRemote(deps, config);
+    const id = conductorIdOf(config);
+    const thisHostKey = hostKeyOf(config);
+    if (await refuseIfAlreadyRunning(remote, id, thisHostKey, force, deps))
+        return;
+    const executor = deps.executor ?? (await selectExecutor(config, logger));
+    const workspace = deps.workspace ?? (await selectWorkspace(config, logger));
+    const agents = deps.agents ?? (await selectAgents(config));
+    const conductor = new Conductor(config, remote, executor, workspace, agents, logger, checkoutRoot, frozenStateFileOf(config));
+    // This process IS the conductor, so it may report its own pid and config
+    // name — the two values a cockpit needs to stop it later. poll/reap build a
+    // Conductor too but never claim, so they cannot overwrite this pid.
+    conductor.claimServeProcess();
+    await conductor.start();
+    const controller = new AbortController();
+    const onSignal = () => controller.abort();
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    try {
+        await conductor.serve(controller.signal);
+    }
+    finally {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+        // The exiting process writes its own `offline`. It has to be this process:
+        // a heartbeat sets `online` unconditionally (ConductorRegistrar), so an
+        // offline written by anyone else is erased by the next tick — the status
+        // is only trustworthy when written after the heartbeats have stopped.
+        // Best-effort: a conductor that cannot reach the control plane on the way
+        // out must still exit, and the reaper flips it on lease expiry anyway.
+        try {
+            await remote.setConductorStatus(conductor.id, 'offline');
+        }
+        catch (err) {
+            logger.warn({ conductorId: conductor.id, err: String(err) }, 'could not write offline status on shutdown; the lease reaper will');
+        }
+    }
+}
+async function defaultAskUpdate(question) {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: true,
+    });
+    let settled = false;
+    try {
+        return await new Promise((resolveAnswer, reject) => {
+            const cancel = () => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(new Error('cancelled'));
+            };
+            rl.once('SIGINT', cancel);
+            rl.once('close', cancel);
+            rl.question(`${question} `, (answer) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolveAnswer(answer);
+            });
+        });
+    }
+    finally {
+        rl.close();
+    }
+}
+async function cmdStart(deps, log = {}, updateCheck = true, body = cmdStartBody, force = false, foreground = false) {
+    const current = printVersionLine();
+    if (updateCheck) {
+        const options = {
+            fetchImpl: deps.fetch ?? globalThis.fetch,
+            ...deps.updateCheckOptions,
+        };
+        if (deps.fetch && options.cachePath === undefined) {
+            options.cachePath = `/tmp/bakers-update-check-${process.pid}-${Math.random()}.json`;
+        }
+        const result = await checkForUpdate(options);
+        const notice = result.latestVersion
+            ? updateNotice(current, result.latestVersion)
+            : null;
+        const env = deps.env ?? process.env;
+        const interactive = !foreground &&
+            (deps.stdinIsTTY ?? Boolean(process.stdin.isTTY)) &&
+            (deps.stdoutIsTTY ?? Boolean(process.stdout.isTTY)) &&
+            !env.CI;
+        if (notice && interactive && result.declined !== true) {
+            console.log('Installing accepts the newer release and runs configuration migration.');
+            console.log('After a successful install this start exits; rerun the start command to use the new release.');
+            const question = `A new bakers version is available (${current} → ${result.latestVersion}). Install it now? [Y/n]`;
+            const ask = deps.askUpdate ?? defaultAskUpdate;
+            let accepted;
+            try {
+                for (;;) {
+                    const answer = (await ask(question)).trim().toLowerCase();
+                    if (answer === '' || answer === 'y' || answer === 'yes') {
+                        accepted = true;
+                        break;
+                    }
+                    if (answer === 'n' || answer === 'no') {
+                        accepted = false;
+                        break;
+                    }
+                }
+            }
+            catch {
+                console.error('Start cancelled.');
+                process.exitCode = 1;
+                return;
+            }
+            const runBb = deps.runBb ??
+                (async (args) => {
+                    const { error, status, signal } = spawnSync('bakers', args, {
+                        stdio: 'inherit',
+                        cwd: process.cwd(),
+                        env,
+                        shell: false,
+                    });
+                    if (error)
+                        throw error;
+                    if (signal)
+                        throw new Error(`bakers ${args[0]} terminated by ${signal}`);
+                    if (status)
+                        throw new Error(`bakers ${args[0]} exited ${status}`);
+                });
+            const prefix = env.BB_CONDUCTOR
+                ? `bakers --conductor ${env.BB_CONDUCTOR}`
+                : 'bakers';
+            const rerun = `${prefix} oven start${force ? ' --force' : ''}`;
+            if (accepted) {
+                try {
+                    await runBb(['update']);
+                }
+                catch (err) {
+                    console.error(`bakers update failed: ${String(err)}`);
+                    console.error('Retry with: bakers update');
+                    process.exitCode = 1;
+                    return;
+                }
+                try {
+                    await runBb(['config', 'upgrade', '--scope', 'all', '--yes']);
+                }
+                catch (err) {
+                    console.error(`bakers config upgrade failed: ${String(err)}`);
+                    console.error(`Retry with: ${prefix} config upgrade --scope all --yes`);
+                    console.error(`Then rerun \`${rerun}\`.`);
+                    process.exitCode = 1;
+                    return;
+                }
+                console.log('bakers update and configuration migration completed.');
+                console.log(`This process still has the previous modules loaded; rerun \`${rerun}\` in a new process.`);
+                console.log('A source checkout or PATH shim may still run the source tree after a global install; use the bakers executable you expect after bakers update.');
+                return;
+            }
+            if (!(await declineUpdate(result, options))) {
+                console.error('Could not remember the decline; you may be asked again on the next start.');
+            }
+        }
+        else if (notice) {
+            console.log(notice);
+        }
+    }
+    deps.onStartLoop?.();
+    await body(deps, log, force);
+}
+/** Default budget: 1s between polls, 20 attempts ≈ 20s total. */
+const START_POLL_INTERVAL_MS = 1000;
+const START_POLL_MAX_ATTEMPTS = 20;
+function realSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Seconds since the row's last heartbeat, or undefined when it never reported one. */
+function heartbeatAgeSeconds(row) {
+    if (!row.lastSeen)
+        return undefined;
+    return Math.max(0, Math.floor(Date.now() / 1000) - row.lastSeen);
+}
+/**
+ * Polls the control plane until this conductor's DERIVED liveness reads
+ * `online`, the record carries a pid different from `priorPid`, AND its
+ * `last_seen` has advanced past `priorLastSeen` — a fresh heartbeat has
+ * arrived from a NEW process, not merely a record that was already fresh —
+ * or the attempt budget runs out.
+ *
+ * BB-450 D9: "started" must mean registered and claiming, not merely that a
+ * spawn call returned. The plain `start` path's premise — refusing to spawn
+ * when a row is already `online` means an `online` row afterwards is this
+ * start's own doing — is false on the `--force` path (BB-450 review B8):
+ * `--force` enters precisely because the existing row WAS `online`, a
+ * `SIGKILL`ed conductor writes no `offline` (nothing survives to write it),
+ * so the record can still read `online` with the OLD pid on attempt 0, before
+ * the new process has registered anything. `priorPid` is the pid on record
+ * before this call (the killed conductor's, under `--force`; a stale or
+ * absent one on a plain start), and a match on it is rejected rather than
+ * accepted as this start's proof.
+ *
+ * BB-450 review B15: the pid check alone is not enough. `last_seen` is
+ * written ONLY by the heartbeat resource, never by `registerConductor()`'s
+ * upsert (`ConductorDeriver.php:47`'s comment records this as deliberate —
+ * D12 does not make registration stamp it, because that would hide the
+ * failed-registration case D9/AC-13 exist to surface). So the instant the new
+ * process registers its OWN pid at boot (D8), the record already satisfies
+ * "online, new pid" while still carrying the KILLED conductor's in-window
+ * `last_seen` — `started` would print for a conductor that has only
+ * registered, never heartbeated. `priorLastSeen` is the value on record
+ * before this call, captured alongside `priorPid`; requiring `last_seen` to
+ * have moved past it, rather than merely being within the freshness window,
+ * is what tells "a heartbeat happened during this call" apart from "a
+ * heartbeat happened at some point before it, possibly by the process this
+ * call just killed".
+ */
+async function waitForFreshHeartbeat(remote, id, priorPid, priorLastSeen, deps) {
+    const intervalMs = deps.startPollIntervalMs ?? START_POLL_INTERVAL_MS;
+    const attempts = deps.startPollAttempts ?? START_POLL_MAX_ATTEMPTS;
+    const sleep = deps.sleep ?? realSleep;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        const row = (await remote.listConductors('me')).find((c) => c.id === id);
+        if (row &&
+            classify(row) === 'online' &&
+            row.lastPid !== undefined &&
+            row.lastPid !== priorPid &&
+            (priorLastSeen === undefined || row.lastSeen > priorLastSeen))
+            return row;
+        await sleep(intervalMs);
+    }
+    return undefined;
+}
+/** Default grace period: 500ms between polls, 10 attempts ≈ 5s total. */
+const FORCE_GRACE_INTERVAL_MS = 500;
+const FORCE_GRACE_MAX_ATTEMPTS = 10;
+/**
+ * Polls the LOCAL process — never the control plane — until the pid this
+ * `--force` just signalled is actually gone, or the grace-period budget runs
+ * out.
+ *
+ * BB-450 review (B4): this used to ask `remote.listConductors('me')` whether
+ * the conductor's DERIVED liveness had left `online`, which is the same
+ * category error D1 removed downstairs — proving a PROCESS fact (did the pid
+ * exit) from a CONTROL-PLANE value (has a heartbeat lapsed). A `SIGKILL`ed
+ * conductor writes no `offline` (nothing survives to write it), so its record
+ * keeps deriving `online` until the stale window or the lease lapses — both
+ * minutes away — while the grace budget is seconds. That mismatch made
+ * `--force` kill the wedged conductor and then refuse to restart it, on the
+ * one case `--force` exists for. `signalVerifiedProcess` already trusts
+ * `probe.cmdlineOf(pid) === undefined` as "gone" (`stale-pid`); this reuses
+ * exactly that authoritative local signal instead of a second, slower, and
+ * sometimes-wrong one.
+ */
+async function waitForNotRunning(probe, pid, deps) {
+    const intervalMs = deps.forceGraceIntervalMs ?? FORCE_GRACE_INTERVAL_MS;
+    const attempts = deps.forceGraceAttempts ?? FORCE_GRACE_MAX_ATTEMPTS;
+    const sleep = deps.sleep ?? realSleep;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        if (probe.cmdlineOf(pid) === undefined)
+            return true;
+        await sleep(intervalMs);
+    }
+    return false;
+}
+/**
+ * `bakers oven start` reports exactly one of three outcomes (BB-450
+ * AC-12): **started**, naming the pid and `host_key`; **already running**,
+ * naming the live pid and its heartbeat age; **failed**, naming the reason.
+ * `failed` sets a non-zero exit status so a script can tell the three apart.
+ *
+ * `--force` (D10) turns "already running" into a restart: a verified
+ * `SIGTERM`, a bounded grace period, an escalation to `SIGKILL`, then the
+ * normal spawn+verify below. Any failure in that sequence — including the
+ * `no-pid` refusal `signalVerifiedProcess` already gives — is **failed** and
+ * never falls through to a second spawn (AC-14/AC-20's two-conductors risk).
+ */
+async function cmdStartBody(deps, log, force = false) {
+    const config = await resolveConfig(deps, undefined, true);
+    const checkoutRoot = await checkoutRootOf(config);
+    const logger = loggerFor(checkoutRoot, log);
+    if (!(await ensureAuthenticated(config, logger)))
+        return;
+    const remote = await resolveRemote(deps, config);
+    const id = conductorIdOf(config);
+    const thisHostKey = hostKeyOf(config);
+    // Block on the DERIVED status, not the raw one. A crashed conductor keeps
+    // `status: online` on its record until the cron reaper notices the lapsed
+    // lease, and those are precisely the minutes in which someone wants to
+    // restart it. Only a conductor that is actually alive refuses a second start.
+    const existing = (await remote.listConductors('me')).find((c) => c.id === id);
+    // Captured before any stop/kill below: the pid this start must NOT report
+    // as its own (BB-450 review B8) — the killed conductor's under `--force`,
+    // a stale or absent one on a plain start.
+    const priorPid = existing?.lastPid;
+    // BB-450 review B15: the heartbeat this start must NOT accept as its own
+    // — a registration writes a new pid without touching `last_seen`, so this
+    // is what tells a genuine new heartbeat apart from the killed conductor's
+    // stale-but-still-in-window one.
+    const priorLastSeen = existing?.lastSeen;
+    if (existing && classify(existing) === 'online') {
+        if (!force) {
+            const age = heartbeatAgeSeconds(existing);
+            console.log(`conductor ${id} already running (pid ${existing.lastPid ?? 'unknown'}, ` +
+                `heartbeat ${age === undefined ? 'age unknown' : `${age}s old`})`);
+            return;
+        }
+        const probe = deps.procProbe ?? defaultProcProbe();
+        const stopOutcome = signalVerifiedProcess({
+            pid: existing.lastPid,
+            hostKey: existing.hostKey,
+            thisHostKey,
+            signal: 'SIGTERM',
+            probe,
+        });
+        if (!stopOutcome.ok) {
+            console.log(`failed to restart conductor ${id}: could not stop the running conductor — ${stopOutcome.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        if (!(await waitForNotRunning(probe, stopOutcome.pid, deps))) {
+            const killOutcome = signalVerifiedProcess({
+                pid: existing.lastPid,
+                hostKey: existing.hostKey,
+                thisHostKey,
+                signal: 'SIGKILL',
+                probe,
+            });
+            if (!killOutcome.ok) {
+                console.log(`failed to restart conductor ${id}: still running after the grace period, and could not force-stop it — ${killOutcome.message}`);
+                process.exitCode = 1;
+                return;
+            }
+            if (!(await waitForNotRunning(probe, killOutcome.pid, deps))) {
+                console.log(`failed to restart conductor ${id}: sent SIGKILL but it is still reported running — refusing a second spawn`);
+                process.exitCode = 1;
+                return;
+            }
+        }
+        console.log(`stopped conductor ${id} for restart (--force)`);
+    }
+    // The conductor registers itself with the control plane on start(); there is
+    // no local file to write, and nothing left that a second list could add.
+    const handle = `bakers-conductor:${id}`;
+    const fgFlags = [
+        log.level ? `--log-level ${log.level}` : '',
+        log.sink ? `--log-sink ${log.sink}` : '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    // BB-477: a herdr pane is a child of the herdr server, not of this
+    // process, so it inherits the server's environment rather than the
+    // BB_CONDUCTOR this process resolved. Carry the selector on the command
+    // string itself, derived the same way the conductor reports its own
+    // `conductor_name`, so the pane cannot re-resolve to a different config.
+    const stem = stemForConfigFile(basename(config.config_path));
+    const selectorFlag = stem && stem !== 'conductor' ? `--conductor ${stem} ` : '';
+    const fgCmd = `BB_CONDUCTOR_LOG=file bakers ${selectorFlag}oven ${fgFlags} start --foreground --no-update-check`.replace(/\s+/g, ' ');
+    try {
+        await herdrHostOf(deps, config).spawn(handle, checkoutRoot, fgCmd);
+        logger.info({ id, handle }, 'started conductor via herdr');
+    }
+    catch (err) {
+        logger.error({ id, err: err.message }, 'could not start via herdr');
+        logger.warn({}, 'Hint: run `bakers oven start --foreground` under a service manager (systemd-user / docker) on hosts without herdr.');
+        console.log(`failed to start conductor ${id}: could not launch via herdr — ${err.message}`);
+        process.exitCode = 1;
+        return;
+    }
+    const started = await waitForFreshHeartbeat(remote, id, priorPid, priorLastSeen, deps);
+    if (!started) {
+        console.log(`failed to start conductor ${id}: spawned, but no fresh heartbeat arrived — ` +
+            'the herdr pane closes when the conductor exits, so a missing bakers on PATH or a crash before logging leaves no file; ' +
+            'check the conductor registered (a refused registration never heartbeats) and its own log');
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`started conductor ${id} (pid ${started.lastPid ?? 'unknown'}, host ${started.hostKey ?? thisHostKey})`);
+}
+/**
+ * Other conductor records that name the SAME checkout as `own` (BB-450 D6,
+ * AC-19) — the exact ambiguity BB-281 recorded in the field: one checkout,
+ * two `bb_conductor` rows under different ids. Reported so the operator can
+ * see the stray; never signalled and never cleaned up here.
+ */
+export function strayConductorsOf(rows, own) {
+    if (!own.workspaceRoot)
+        return [];
+    const target = resolve(own.workspaceRoot);
+    return rows.filter((c) => c.id !== own.id &&
+        c.workspaceRoot !== '' &&
+        resolve(c.workspaceRoot) === target);
+}
+/**
+ * Stops this checkout's conductor with a verified signal.
+ *
+ * Two things this deliberately no longer does. It does not kill a herdr tab:
+ * that killed the pane the conductor happened to be shown in, which is neither
+ * necessary (a signal reaches the process wherever it lives) nor sufficient (a
+ * conductor started by systemd or a bare --foreground has no tab). And it does
+ * not write `offline` — a heartbeat sets `online` unconditionally, so a status
+ * written from here is erased by the next tick unless it happens to land after
+ * the process died. The exiting process writes its own, which is correct by
+ * construction rather than by ordering luck.
+ *
+ * `--now` differs only in the signal. It runs through the same verification
+ * gate, because a hard kill aimed at a recycled pid is the most damaging
+ * version of the same mistake.
+ */
+async function cmdStop(deps, now) {
+    const config = await resolveConfig(deps);
+    const remote = await resolveRemote(deps, config);
+    const id = conductorIdOf(config);
+    const thisHostKey = hostKeyOf(config);
+    const rows = await remote.listConductors('me');
+    const row = rows.find((c) => c.id === id);
+    if (!row) {
+        console.log(`no conductor ${id} on the control plane — nothing to stop (it may never have started)`);
+        return;
+    }
+    // BB-450 D6: report a stray record naming this checkout, never touch it.
+    for (const stray of strayConductorsOf(rows, row)) {
+        console.log(`note: conductor ${stray.id} also names this checkout (${stray.workspaceRoot}) — left untouched`);
+    }
+    const signal = now ? 'SIGKILL' : 'SIGTERM';
+    const outcome = signalVerifiedProcess({
+        pid: row.lastPid,
+        hostKey: row.hostKey,
+        thisHostKey,
+        signal,
+        ...(deps.procProbe ? { probe: deps.procProbe } : {}),
+    });
+    if (!outcome.ok) {
+        console.log(`could not stop conductor ${id}: ${outcome.message}`);
+        return;
+    }
+    console.log(now
+        ? `hard-stopped conductor ${id} (SIGKILL to pid ${outcome.pid}); a killed process writes no offline, so the status follows on lease expiry`
+        : `stopped conductor ${id} (SIGTERM to pid ${outcome.pid}); it writes its own offline as it exits`);
+}
+async function cmdLs(deps) {
+    const config = deps.config ?? (await tryConfig(deps));
+    const remote = await resolveRemote(deps, config ?? (await resolveConfig(deps)));
+    const rows = await buildLsRows(remote, config, undefined, deps.procProbe);
+    printRows(rows);
+}
+async function cmdStatus(deps) {
+    const config = await resolveConfig(deps);
+    const remote = await resolveRemote(deps, config);
+    const id = conductorIdOf(config);
+    const rows = await buildLsRows(remote, config, id, deps.procProbe);
+    printRows(rows);
+}
+/** ls may run without a config file; best-effort load. */
+async function tryConfig(deps) {
+    if (deps.config) {
+        return deps.config;
+    }
+    try {
+        return await resolveConfig(deps);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Prompt for the developer Kürzel / user id on an interactive terminal. */
+// --- the conductor command tree --------------------------------------------
+/** Build the `oven` subcommand tree (lifecycle + registry). */
+export function createConductorCommand(deps) {
+    const conductor = new Command('oven')
+        .description('node-agent lifecycle + local registry')
+        .option('--log-level <level>', 'log verbosity: debug | info | warn | error (overrides BB_LOG_LEVEL)')
+        .option('--log-sink <sink>', 'log sink: stdout | file | both (overrides BB_CONDUCTOR_LOG)')
+        .addHelpText('after', `
+Logging (precedence: CLI flag > env var > default):
+  --log-level <level>  debug | info (default) | warn | error.
+                       Set debug to see per-poll ticks, claims, and idle cycles.
+  --log-sink <sink>    stdout | file | both (file/both write <checkoutRoot>/.bakers/log.txt).
+                       Default: both on a TTY, file otherwise (BB-237 — a run in a
+                       herdr pane is on a TTY, and its diagnostics must outlive the pane).
+  BB_LOG_LEVEL       env fallback for --log-level.
+  BB_CONDUCTOR_LOG   env fallback for --log-sink.
+
+Examples:
+  bakers oven --log-level debug start --foreground
+  bakers oven --log-level debug once
+  BB_LOG_LEVEL=debug bakers oven once`);
+    conductor
+        .command('start')
+        .description('start the conductor loop (herdr-hosted by default)')
+        .option('--foreground', 'run the loop in this process', false)
+        .option('--no-update-check', 'skip the daily CLI update check')
+        .option('--force', 'restart: verify-stop the already-running conductor (SIGTERM, a grace ' +
+        'period, then SIGKILL) and start a new one. Fails rather than starting ' +
+        'a second conductor if the running one cannot be verified or stopped.', false)
+        .action(async function (opts) {
+        await cmdStart(deps, logOptsOf(this), opts.updateCheck, opts.foreground ? cmdStartForeground : cmdStartBody, opts.force, opts.foreground);
+    });
+    conductor
+        .command('once')
+        .description('run one conductor cycle then exit')
+        .action(async function () {
+        await cmdPoll(deps, logOptsOf(this));
+    });
+    conductor
+        .command('clean')
+        .description('tear down herdr worktrees of finished-but-uncleaned tickets (recovers orphans a live tick missed: conductor was down at done, restarted, or reassigned)')
+        .action(async function () {
+        await cmdReap(deps, logOptsOf(this));
+    });
+    conductor
+        .command('stop')
+        .description('stop the conductor: graceful offline (default) or hard kill (--now)')
+        .option('--now', 'hard-kill via host and let the cron reaper mark it offline', false)
+        .action(async (opts) => {
+        await cmdStop(deps, opts.now);
+    });
+    conductor
+        .command('ls')
+        .description('list conductors on this machine + status')
+        .action(async () => {
+        await cmdLs(deps);
+    });
+    conductor
+        .command('status')
+        .description('status of the conductor for this checkout')
+        .action(async () => {
+        await cmdStatus(deps);
+    });
+    // `bakers conductor rm` is gone (BB-232). Its only job was deleting the local
+    // registry entry; with no registry there is nothing to remove, and deleting
+    // the control-plane record is explicitly not the model — a conductor that
+    // stops is offline, not absent.
+    return conductor;
+}
+/** The `oven` command plugin the host mounts (BB-201). BB-224
+ *  (Finding 7): the `bakers deployment` batch helper is no longer registered here —
+ *  it is its own command addon, `@bakers-build/addon-deployment`. */
+const conductorCommandPlugin = {
+    kind: 'command',
+    name: 'oven',
+    describe: 'node-agent lifecycle + local registry',
+    register(program, host) {
+        program.addCommand(createConductorCommand({ host }));
+    },
+};
+export default conductorCommandPlugin;
+/**
+ * Build a standalone program with the conductor command mounted — the test entry
+ * (mirrors what the host does for `bakers oven …`). `deps` inject fakes.
+ */
+export function buildConductorProgram(deps = {}) {
+    const program = new Command();
+    program.name('bakers').description('bakers.build conductor + client CLI');
+    program.addCommand(createConductorCommand(deps));
+    return program;
+}
+/** Parse argv against the conductor program (test entry). */
+export async function runConductorCli(argv, deps = {}) {
+    const program = buildConductorProgram(deps);
+    await program.parseAsync(argv, { from: 'user' });
+}