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

package/dist/src/contract.d.ts

@@ -0,0 +1,13 @@
+export { AmbiguousProjectNameError, type ResolvedBbProjectContext, resolveBbProjectContext, } from './bakers-project-context.js';
+export { type AgentFootprint, type AgentRunIdentity, type BbAgent, emptyAgentFootprint, } from './plugins/agent.js';
+export { detectKnownOverrides, type KnownOptionSpec, type KnownOverrides, type KnownScalarKind, resolveAgentCliOptions, validateAgentArgs, validateOptionalBoolean, validateOptionalString, } from './plugins/agent-args.js';
+export type { BbExecutor, ExecutorCapabilities, HookContext, HookListener, HookListenerContext, HookListenerFn, HookName, HookResult, SpawnedSession, SpawnRunInput, WorktreeTeardown, } from './plugins/executor.js';
+export type { DiscoveredInbox, InboxMessageHandler, InboxMessageRequest, InboxMessages, LoadedInbox, } from './plugins/message.js';
+export { loadInbox, validateRequestPayload, } from './plugins/message.js';
+export type { AgentCandidate, AgentPlugin, ExecutorDeps, ExecutorPlugin, RemotePlugin, ResolvedAgent, WorkspacePlugin, } from './plugins/plugins.js';
+export { resolveAgent, selectAgent, selectAgents, selectExecutor, selectRemote, selectWorkspace, } from './plugins/plugins.js';
+export { type ConductorAddonEntry, type ConductorContributions, narrowConductorContributions, type Preset, } from './plugins/preset.js';
+export type { HerdrHost } from './plugins/process-host.js';
+export type { ActiveRun, AddonDefinitionV2, AddonRegistration, BbRemote, ClaimedRun, ClaimOptions, ClaimWithheld, ConductorRegistration, ConductorStatus, FinalizableRun, FrozenTicket, InboxMessage, InboxSnapshot, RunMetrics, RunWriteAttributes, Ticket, TicketMetric, UncleanTicket, } from './plugins/remote.js';
+export type { BbWorkspace, EnsuredWorkspace, } from './plugins/workspace.js';
+export type { ConductorEngineConfig, ConductorFileConfig, ConductorSettings, } from './types.js';

package/dist/src/contract.js

@@ -0,0 +1,19 @@
+// BB-224 (Finding 6): the CONDUCTOR-SURFACE CONTRACT, exposed as the
+// runtime-light subpath `@bakers-build/conductor/contract`.
+//
+// This is the module a conductor-surface addon (`addons/remote-drupal`,
+// `addons/workspace-git`, `addons/herdr`, `addons/claude`, …) imports. It carries
+// ONLY the surface interfaces, the config contract, the preset view, and the two
+// tiny runtime helpers (`emptyAgentFootprint`, the `select*` slot selectors) — it
+// imports NO engine, NO commander, NO dropsh runtime. Importing it therefore
+// costs an addon nothing at boot, unlike the package main (`@bakers-build/conductor`),
+// which pulls the whole run engine + the `conductor` command plugin.
+//
+// The package main re-exports everything here too, so `import type { BbRemote }
+// from '@bakers-build/conductor'` keeps working for type-only consumers.
+export { AmbiguousProjectNameError, resolveBbProjectContext, } from './bakers-project-context.js';
+export { emptyAgentFootprint, } from './plugins/agent.js';
+export { detectKnownOverrides, resolveAgentCliOptions, validateAgentArgs, validateOptionalBoolean, validateOptionalString, } from './plugins/agent-args.js';
+export { loadInbox, validateRequestPayload, } from './plugins/message.js';
+export { resolveAgent, selectAgent, selectAgents, selectExecutor, selectRemote, selectWorkspace, } from './plugins/plugins.js';
+export { narrowConductorContributions, } from './plugins/preset.js';

package/dist/src/core/action-queue.d.ts

@@ -0,0 +1,31 @@
+import type { ConductorLogger } from '@bakers-build/core';
+export interface Action {
+    /** An action whose key is queued or running is not enqueued again. */
+    key: string;
+    /** Actions of one lane run one after another; lanes run in parallel. */
+    lane: string;
+    run: () => Promise<void>;
+}
+export declare class ActionQueue {
+    private readonly logger;
+    private readonly now;
+    private readonly keys;
+    private readonly lanes;
+    /** Running action key → start (ms). */
+    private readonly running;
+    constructor(logger: ConductorLogger, now?: () => number);
+    /** Queued or running actions. */
+    get size(): number;
+    /** Starts the action after its lane's last one; false when its key is pending. */
+    enqueue(action: Action): boolean;
+    /** Resolves once every queued and running action has settled. */
+    drain(): Promise<void>;
+    /**
+     * Warns once per call about each action running longer than `limitMs`: only
+     * addon handlers time out, so a hung hook would otherwise block its ticket's
+     * lane without a trace while the heartbeat keeps the conductor healthy.
+     */
+    warnOverdue(limitMs: number): void;
+    /** Never rejects: a lane's chain must survive a failing action. */
+    private execute;
+}

package/dist/src/core/action-queue.js

@@ -0,0 +1,69 @@
+// The conductor's per-item work: the tick only reads what is due and enqueues
+// one action per item. Every action starts at once, fails and logs on its own;
+// actions of one lane (a ticket) run in order, lanes run in parallel.
+export class ActionQueue {
+    logger;
+    now;
+    keys = new Set();
+    lanes = new Map();
+    /** Running action key → start (ms). */
+    running = new Map();
+    constructor(logger, now = Date.now) {
+        this.logger = logger;
+        this.now = now;
+    }
+    /** Queued or running actions. */
+    get size() {
+        return this.keys.size;
+    }
+    /** Starts the action after its lane's last one; false when its key is pending. */
+    enqueue(action) {
+        if (this.keys.has(action.key))
+            return false;
+        this.keys.add(action.key);
+        const tail = (this.lanes.get(action.lane) ?? Promise.resolve()).then(() => this.execute(action));
+        this.lanes.set(action.lane, tail);
+        void tail.then(() => {
+            if (this.lanes.get(action.lane) === tail)
+                this.lanes.delete(action.lane);
+        });
+        return true;
+    }
+    /** Resolves once every queued and running action has settled. */
+    async drain() {
+        while (this.lanes.size > 0)
+            await Promise.all(this.lanes.values());
+    }
+    /**
+     * Warns once per call about each action running longer than `limitMs`: only
+     * addon handlers time out, so a hung hook would otherwise block its ticket's
+     * lane without a trace while the heartbeat keeps the conductor healthy.
+     */
+    warnOverdue(limitMs) {
+        const now = this.now();
+        for (const [key, started] of this.running) {
+            const ms = now - started;
+            if (ms > limitMs) {
+                this.logger.warn({ action: key, ms }, `action ${key} running for ${ms}ms`);
+            }
+        }
+    }
+    /** Never rejects: a lane's chain must survive a failing action. */
+    async execute(action) {
+        const started = this.now();
+        this.running.set(action.key, started);
+        try {
+            await action.run();
+            const ms = this.now() - started;
+            this.logger.debug({ action: action.key, ms }, `action ${action.key} done in ${ms}ms`);
+        }
+        catch (err) {
+            const ms = this.now() - started;
+            this.logger.warn({ action: action.key, ms, err: String(err) }, `action ${action.key} failed after ${ms}ms`);
+        }
+        finally {
+            this.running.delete(action.key);
+            this.keys.delete(action.key);
+        }
+    }
+}

package/dist/src/core/attempt.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Deterministic per-attempt session id family for a run (BB-473 review
+ * round 4, Critical 2). A re-dispatch of the same run needs its own
+ * collision-free session id — `claude`/`grok --session-id` refuse to start
+ * when the id already names a transcript from a prior attempt — but the
+ * previous fix (a `startedAt` time window) selects by *when*, not by *which
+ * attempt*, and a worktree-keyed transcript directory can hold a sibling
+ * run's session newer than that bound. An attempt family gives finalise an
+ * IDENTITY to select by instead: attempt 0 is the run's own UUID (unchanged,
+ * so every caller that only knows a single `sessionId` keeps working);
+ * attempt n>0 is a stable UUID-shaped id derived from `${runUuid}:${n}`, so
+ * both dispatch (which candidate to pin) and finalise (which candidate's
+ * file exists) derive the SAME sequence from nothing but the run's own UUID
+ * — no new persisted field, no schema change.
+ */
+export declare function attemptSessionId(runUuid: string, attempt: number): string;
+/** Bound on how many re-dispatches of one run this family covers. */
+export declare const MAX_ATTEMPTS = 25;
+/**
+ * The full candidate sequence for a run, attempt 0 first. Both the dispatch
+ * pin-selection loop and finalise's selection loop derive this from nothing
+ * but the run's own UUID, so the two sides never need to agree through any
+ * channel but the UUID itself.
+ */
+export declare function attemptFamily(runUuid: string, max?: number): string[];

package/dist/src/core/attempt.js

@@ -0,0 +1,41 @@
+import { createHash } from 'node:crypto';
+/**
+ * Deterministic per-attempt session id family for a run (BB-473 review
+ * round 4, Critical 2). A re-dispatch of the same run needs its own
+ * collision-free session id — `claude`/`grok --session-id` refuse to start
+ * when the id already names a transcript from a prior attempt — but the
+ * previous fix (a `startedAt` time window) selects by *when*, not by *which
+ * attempt*, and a worktree-keyed transcript directory can hold a sibling
+ * run's session newer than that bound. An attempt family gives finalise an
+ * IDENTITY to select by instead: attempt 0 is the run's own UUID (unchanged,
+ * so every caller that only knows a single `sessionId` keeps working);
+ * attempt n>0 is a stable UUID-shaped id derived from `${runUuid}:${n}`, so
+ * both dispatch (which candidate to pin) and finalise (which candidate's
+ * file exists) derive the SAME sequence from nothing but the run's own UUID
+ * — no new persisted field, no schema change.
+ */
+export function attemptSessionId(runUuid, attempt) {
+    if (attempt <= 0) {
+        return runUuid;
+    }
+    const hex = createHash('sha256')
+        .update(`${runUuid}:${attempt}`)
+        .digest('hex')
+        .slice(0, 32)
+        .split('');
+    hex[12] = '5'; // version nibble — cosmetic, just keeps the shape UUID-like.
+    hex[16] = ((Number.parseInt(hex[16] ?? '0', 16) & 0x3) | 0x8).toString(16); // variant nibble.
+    const h = hex.join('');
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+}
+/** Bound on how many re-dispatches of one run this family covers. */
+export const MAX_ATTEMPTS = 25;
+/**
+ * The full candidate sequence for a run, attempt 0 first. Both the dispatch
+ * pin-selection loop and finalise's selection loop derive this from nothing
+ * but the run's own UUID, so the two sides never need to agree through any
+ * channel but the UUID itself.
+ */
+export function attemptFamily(runUuid, max = MAX_ATTEMPTS) {
+    return Array.from({ length: max }, (_, i) => attemptSessionId(runUuid, i));
+}

package/dist/src/core/conductor.d.ts

@@ -0,0 +1,236 @@
+import { type ConductorLogger } from '@bakers-build/core';
+import type { BbExecutor } from '../plugins/executor.js';
+import { type ResolvedAgent } from '../plugins/plugins.js';
+import type { BbRemote } from '../plugins/remote.js';
+import type { BbWorkspace } from '../plugins/workspace.js';
+import type { ConductorFileConfig } from '../types.js';
+/**
+ * Resolve the environment a run executes in (BB-99): parse the ticket's
+ * effective env_vars, drop any reserved key (loud warn — key NAME only, never
+ * the value), then overlay the conductor's core vars so they always win.
+ *
+ * Values are potentially secret (e.g. a DB DSN): this function logs key names
+ * only, never a value. The returned map is injected into BOTH the agent run env
+ * and every workspace hook.
+ */
+export declare function resolveRunEnv(effectiveEnvVars: string | undefined, core: Record<string, string>, logger: ConductorLogger): Record<string, string>;
+export declare class Conductor {
+    private readonly config;
+    private readonly remote;
+    private readonly executor;
+    private readonly workspace;
+    private readonly agents;
+    private readonly logger;
+    private readonly checkoutRoot;
+    private readonly frozenStateFile?;
+    private uuid;
+    /**
+     * Frozen tickets seen on the last poll, by uuid, with the worktree their
+     * hook ran in. Mirrored to `frozenStateFile` when one is given, so an
+     * unfreeze while the conductor is down still gets its `on_resume` and a
+     * restart does not repeat `on_freeze`; loaded on the first observation.
+     */
+    private frozenSeen;
+    /** The addons with contract-2 inbox messages this conductor runs. */
+    private readonly inboxAddons;
+    /** The per-item work each tick enqueues. */
+    private readonly queue;
+    /** Serializes git worktree add/remove: parallel ones fight over git locks. */
+    private gitLock;
+    constructor(config: ConductorFileConfig, remote: BbRemote, executor: BbExecutor, workspace: BbWorkspace, agents: ResolvedAgent[], logger: ConductorLogger, checkoutRoot?: string, frozenStateFile?: string | undefined);
+    private serialGit;
+    /**
+     * `conductor_id` is required and the loader throws without it (BB-353), so
+     * there is no directory-derived fallback here (BB-450 D5) — that fallback
+     * was the mechanism by which one checkout came to be registered under two
+     * different ids.
+     */
+    get id(): string;
+    /**
+     * Host stem for bb_machine.host_key. Prefer config.host_key from
+     * MachineContext.machine_id; fall back to a best-effort parse of the composed
+     * conductor_id only when the loader could not supply the stem.
+     */
+    private get hostKey();
+    /**
+     * Whether this instance is the serve-loop process itself (BB-232).
+     *
+     * Off by default so that only a caller which genuinely owns the process can
+     * report a pid — see {@link claimServeProcess}.
+     */
+    private ownsServeProcess;
+    /**
+     * Declares that this instance runs *as* the conductor process, so its
+     * registrations may carry the process identity a cockpit needs to stop it.
+     *
+     * Only `cmdStartForeground` calls this. `cmdPoll` and `cmdReap` also build a
+     * Conductor and call start() + tick(), then exit; if they reported a pid,
+     * every `bakers oven once` would overwrite the running conductor's pid
+     * with its own short-lived one and the next stop would signal a dead — or
+     * recycled — process. Making the report opt-in means those two commands
+     * cannot do so even by accident.
+     */
+    claimServeProcess(): void;
+    /** This conductor's registration payload, built from config. */
+    private registration;
+    /**
+     * The stem of the config file this conductor was loaded from.
+     *
+     * Derived through core's own mapping rather than by slicing the filename
+     * here, so the CLI and the conductor cannot disagree about which files count
+     * as a conductor config.
+     */
+    private get conductorName();
+    start(): Promise<void>;
+    /** One tick that also waits for its actions: `bakers oven once`, tests. */
+    tick(): Promise<void>;
+    /** A failing list query must not stop the other steps or the claims. */
+    private step;
+    /**
+     * The tick body: heartbeat, the list queries and the claim loop. Every
+     * per-item job becomes an action on the queue, so no slow item can delay
+     * the heartbeat or the claims.
+     */
+    produce(): Promise<void>;
+    /**
+     * One-shot finalisation: for each of this conductor's runs that is state in
+     * (done, cancelled) but not yet closed, read the agent transcript from its
+     * worktree and write it as the final log, then mark the run closed. Keyed off
+     * the durable terminal-state query — no in-memory state, so a restarted
+     * conductor still finalises any unclosed run on its next tick.
+     */
+    private enqueueFinalize;
+    /** Finalises one run; a failure is logged and retried next tick. */
+    private finalizeOne;
+    /** Read the run's transcript and parse its footprint for the close write. */
+    private captureRun;
+    /**
+     * Close one run's tab. Run-scoped (BB-183): only the `#<runId>` tab, never
+     * a sibling run's. Best-effort: a close failure never mislabels the run as
+     * "finalise failed" or replaces a dispatch error.
+     */
+    private closeRunTab;
+    /**
+     * `after_run` for an ended run (BB-599), rebuilt from durable state: the
+     * run record names its ticket and start state, and the env is resolved from
+     * the CURRENT ticket — so a restarted conductor stops the same sidecars.
+     * Like `after_done`, it needs the worktree directory to exist.
+     */
+    private runFinalizeHook;
+    /**
+     * Rebuild a listener context from the ticket's current record, or
+     * `undefined` (logged) when it cannot be read — the caller still runs the
+     * project shell hook, it only loses the addon listeners. Built even with no
+     * listeners: the shell `after_run` takes its env from it.
+     */
+    private listenerContext;
+    private get listeners();
+    /**
+     * Run one lifecycle slot (BB-599): every addon listener in accumulator
+     * order, awaited, then the project shell hook through the executor. Never
+     * throws. A failing listener is logged by slot, listener, ticket and run —
+     * never with its message or the env — and reported in the returned result
+     * the same way a failing shell command is, so the rest of the slot, the
+     * shell hook and dispatch all continue.
+     */
+    private runSlot;
+    /**
+     * Undo a listener's env change the conductor does not accept: a reserved
+     * key keeps the conductor's value, and an invalid name or a non-string value
+     * never reaches a spawn. Key names only are logged.
+     */
+    private guardEnv;
+    /**
+     * Run `on_freeze` once for each newly frozen ticket and `on_resume` once
+     * for each that left the frozen list, in the ticket's worktree on this
+     * machine. A ticket without a worktree here gets no hook. Never throws: an
+     * unreadable list keeps the previous observation for the next poll.
+     */
+    private observeFreezes;
+    private loadFrozenSeen;
+    private saveFrozenSeen;
+    private runFreezeSlot;
+    /**
+     * Reconcile closed tickets against their herdr worktrees and tear down any
+     * whose workspace still lingers (BB-89). Driven by the durable `cleaned_up`
+     * flag via {@link BbRemote.fetchUncleanedTickets}: every ticket the server
+     * has already closed but not yet cleaned. The SAME reconciliation runs on
+     * every tick AND standalone as `bakers oven clean`, and the query is
+     * scoped to THIS conductor (BB-121) — so it catches the orphans a
+     * live-tick-only path structurally cannot (the conductor was down when the
+     * ticket closed, or crashed mid-cleanup) for its OWN tickets. A foreign
+     * (non-bakers) worktree has no bakers ticket, so it is never on the work list; a
+     * ticket assigned to another conductor is filtered out at the query — both are
+     * left untouched with no host enumeration.
+     *
+     * The conductor is structurally UNABLE to close a ticket (BB-451): closing
+     * is a server-side projection of terminality written by
+     * `BbTicket::preSave()` on any save of a terminal, unclosed ticket, so it
+     * holds for every write path and cannot be withheld by a teardown hiccup —
+     * the reap reasons about `cleaned_up` alone. `cleaned_up` is withheld unless
+     * the teardown is ACCOUNTED FOR (BB-141 RC-2), which `removeWorktree`
+     * reports as one of three outcomes (BB-293):
+     *   - `removed` — gone because this host tore it down → flag cleaned;
+     *   - `already_absent` — nothing was there to tear down. A FINISHED teardown,
+     *     not a failure: it is recorded in this log AND on the run record, then
+     *     flagged cleaned. Recording it is the point — swallowing the absence and
+     *     leaving `cleaned_up=0` is what made every later reap repeat the same
+     *     failing teardown;
+     *   - `unverified` — it could not be resolved and may still be on disk (e.g.
+     *     its `worktree_path` was never persisted). Like a THROW, it logs loudly
+     *     and leaves `cleaned_up=0` so the next reconciliation retries.
+     * Flagging cleaned on an unverified teardown was the root cause of the ~28
+     * never-touched leftovers, because the ticket then dropped off the
+     * (cleaned_up=0) work list forever.
+     * Re-running on an already-cleaned ticket is a no-op — it is off the list
+     * (idempotent). Each ticket is isolated in a try/catch so one failure never
+     * aborts the rest.
+     *
+     * The `after_done` hook runs through the executor (BB-84), which owns the
+     * best-effort policy — it logs+swallows a hook failure and never throws, so
+     * the core needs no per-call-site try/catch around it.
+     */
+    reap(): Promise<void>;
+    private enqueueReap;
+    /**
+     * Record the merge request's size on a done ticket while its worktree still
+     * exists. The server keeps `metrics` writable until `cleaned_up`; a failure
+     * is logged and never holds up the teardown. A teardown that keeps failing
+     * re-measures on every reap; the rows are replaced, so they stay correct.
+     */
+    private recordMrChanges;
+    /** Reaps one ticket; isolated, so one failure never aborts the rest. */
+    private reapOne;
+    /**
+     * The env a run executes in: the ticket's effective env_vars under the core
+     * vars. Used at dispatch and, rebuilt from the current ticket, for the
+     * `after_run` / `after_done` listener contexts (BB-599).
+     */
+    private runEnv;
+    /** Dispatches one claimed run; a failure terminalises it (BB-149). */
+    private dispatchOrFail;
+    private dispatch;
+    /**
+     * The part of a dispatch that can leave a sidecar or a worker behind
+     * (BB-599): its caller unwinds it through `after_run` on any failure.
+     */
+    private launch;
+    /**
+     * Stop what a failed dispatch started (BB-599): the worker if it was
+     * launched, then the `after_run` listeners and shell hook. Best-effort — it
+     * never replaces the dispatch error the caller re-throws.
+     */
+    private unwindDispatch;
+    serve(signal?: AbortSignal): Promise<void>;
+    /**
+     * True once this conductor's own checkout has been removed from disk (its
+     * worktree was reaped while the process kept running). Such a conductor is a
+     * pure liability: it still heartbeats and still claims runs, but every
+     * dispatch fails — no git command and no relative path can resolve from a
+     * deleted directory — so each claim burns one attempt and three of them park
+     * the ticket behind the circuit breaker. Observed as 30 orphans claiming and
+     * failing tickets they could never dispatch.
+     */
+    private checkoutGone;
+    private pollLoop;
+}