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

package/dist/src/plugins/preset.d.ts

@@ -0,0 +1,61 @@
+import type { AddonEntry, BbPreset, DiscoveredContributions } from '@bakers-build/core';
+import type { HookListener } from './executor.js';
+import type { DiscoveredInbox, InboxMessages } from './message.js';
+import type { AgentCandidate, ExecutorPlugin, RemotePlugin, WorkspacePlugin } from './plugins.js';
+import type { HerdrHost } from './process-host.js';
+import type { Ticket } from './remote.js';
+/**
+ * The conductor surface's concrete contributions — the strongly-typed view of
+ * the conductor accumulators `discoverAddons(entries, 'conductor', …)`
+ * fills. Core returns them as opaque `unknown[]`; the engine narrows once, at
+ * the discovery call site (see {@link narrowConductorContributions}).
+ */
+export interface ConductorContributions {
+    remotes: RemotePlugin[];
+    executors: ExecutorPlugin[];
+    workspaces: WorkspacePlugin[];
+    agents: AgentCandidate[];
+    /** Lifecycle hook listeners, in accumulator order (BB-599). */
+    hooks: HookListener[];
+    /** Conductor process hosts (last wins). */
+    processHosts: HerdrHost[];
+    /** Addon `inbox` exports with their package name and version (contract 2, BB-661). */
+    addonInbox: DiscoveredInbox[];
+}
+/**
+ * One `addons[]` entry on the conductor surface: core's surface-agnostic
+ * `AddonEntry` with the agent `priority` narrowed to the real `Ticket`.
+ */
+export type ConductorAddonEntry = string | (Exclude<AddonEntry, string> & {
+    priority?: (ticket: Ticket) => number;
+});
+/**
+ * A preset as a CONDUCTOR-surface addon writes it: core's `BbPreset` with the
+ * conductor accumulators concretely typed.
+ *
+ * It literally `extends BbPreset`, so the compiler — not a comment — enforces
+ * that this view stays a faithful narrowing of the kernel contract. That only
+ * type-checks because core's `OpaqueAccumulator` takes `never[]` on the input
+ * side: `never[]` is assignable to `RemotePlugin[]`, so the concrete member below
+ * satisfies the opaque one contravariantly. If core ever widened that parameter
+ * to `unknown[]`, this `extends` would fail loudly here instead of the two views
+ * silently drifting apart.
+ */
+export interface Preset<O = unknown> extends BbPreset<O> {
+    remotes?: (acc: RemotePlugin[], opts: O) => RemotePlugin[] | Promise<RemotePlugin[]>;
+    executors?: (acc: ExecutorPlugin[], opts: O) => ExecutorPlugin[] | Promise<ExecutorPlugin[]>;
+    workspaces?: (acc: WorkspacePlugin[], opts: O) => WorkspacePlugin[] | Promise<WorkspacePlugin[]>;
+    agents?: (acc: AgentCandidate[], opts: O) => AgentCandidate[] | Promise<AgentCandidate[]>;
+    hooks?: (acc: HookListener[], opts: O) => HookListener[] | Promise<HookListener[]>;
+    processHosts?: (acc: HerdrHost[], opts: O) => HerdrHost[] | Promise<HerdrHost[]>;
+    /** Addon inbox messages: contract 2, BB-661. */
+    inbox?: InboxMessages;
+}
+/**
+ * The single, reviewed narrowing at the engine's discovery seam: reinterpret
+ * core's opaque conductor accumulators as this surface's concrete contribution
+ * lists. Safe because every conductor-surface preset is typed against
+ * {@link Preset}, and `resolveConductorSlots` still runs the runtime `.kind`
+ * guard on whatever actually landed in a singleton slot.
+ */
+export declare function narrowConductorContributions(discovered: Pick<DiscoveredContributions, 'remotes' | 'executors' | 'workspaces' | 'agents' | 'hooks' | 'processHosts' | 'addonInbox'>): ConductorContributions;

package/dist/src/plugins/preset.js

@@ -0,0 +1,23 @@
+// BB-224 (Finding 6, decision 7): the CONDUCTOR-SURFACE view of the preset
+// contract. `@bakers-build/core` owns the surface-AGNOSTIC machinery — it knows the
+// accumulator NAMES (`SURFACE_KEYS`) and threads them (`discoverAddons`), but its
+// per-surface accumulators are OPAQUE (`OpaqueAccumulator`), because the element
+// types of the conductor surface (`RemotePlugin`, `ExecutorPlugin`,
+// `WorkspacePlugin`, `AgentCandidate`) live HERE, in the package that owns the
+// surface. Without that split, `core/src/plugins/preset.ts` would have to import
+// the conductor contract and core would edge `@bakers-build/conductor` — breaking the
+// "core has zero @bakers-build/* edges" rule.
+//
+// A conductor-surface addon therefore types its `./preset` accumulators against
+// THIS `Preset` (e.g. `export const agents: Preset['agents'] = …`) instead of
+// core's `BbPreset`, and stays structurally assignable to it.
+/**
+ * The single, reviewed narrowing at the engine's discovery seam: reinterpret
+ * core's opaque conductor accumulators as this surface's concrete contribution
+ * lists. Safe because every conductor-surface preset is typed against
+ * {@link Preset}, and `resolveConductorSlots` still runs the runtime `.kind`
+ * guard on whatever actually landed in a singleton slot.
+ */
+export function narrowConductorContributions(discovered) {
+    return discovered;
+}

package/dist/src/plugins/process-host.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Process host that starts a detached conductor loop. The conductor package
+ * owns only this contract; `@bakers-build/addon-herdr` implements it.
+ */
+export interface HerdrHost {
+    spawn(label: string, cwd: string, cmd: string): Promise<void>;
+}

package/dist/src/plugins/process-host.js

@@ -0,0 +1 @@
+export {};

package/dist/src/plugins/remote.d.ts

@@ -0,0 +1,420 @@
+import type { MessageDefinition, MessageResult } from '@bakers-build/message';
+/** A contract-2 addon's wire registration shape (BB-661). */
+export interface AddonDefinitionV2 {
+    name: string;
+    version: string;
+    contract: 2;
+    label?: string;
+    icon?: string;
+    messages: Record<string, MessageDefinition>;
+}
+export interface ConductorRegistration {
+    /** Conductor process registration key (bb_conductor.conductor_id). */
+    id: string;
+    /** Host identity stem (bb_machine.host_key / MachineContext.machine_id). */
+    host_key?: string;
+    project: string;
+    /** Empty = serve all claimable states in the project (BB-207). */
+    states: string[];
+    workspace: string;
+    label: string;
+    max_parallel: number;
+    /**
+     * The pid of the serve-loop process, when this conductor *is* that process.
+     *
+     * Absent from a registration sent by `poll` or `reap`, which build a
+     * Conductor and exit within seconds — reporting their pid would overwrite a
+     * running conductor's with a short-lived one. Absent likewise means "leave
+     * whatever is stored alone", never "clear it".
+     */
+    last_pid?: number;
+    /**
+     * The stem of the config file this conductor was started from (`conductor`
+     * for the default, `shop` for `shop.conductor.config.js`) — what
+     * `--conductor <name>` selects. Together with `workspace` it identifies one
+     * conductor in a repo that holds several.
+     */
+    conductor_name?: string;
+}
+export interface ClaimOptions {
+    leaseSeconds: number;
+    conductorId: string;
+}
+export interface ClaimedRun {
+    runUuid: string;
+    runId: number;
+    ticketUuid: string;
+    stateAtStart: string;
+    handler: string;
+}
+export interface Ticket {
+    uuid: string;
+    identifier: string;
+    title: string;
+    state: string;
+    branchName: string;
+    /** Branch the ticket's work is based on (computed server-side): parent branch, project default, or 'main'. */
+    baseBranch?: string;
+    /**
+     * Effective environment variables (BB-99), resolved server-side along the
+     * parent_id chain (child wins) as canonical `.env`-style `KEY=value` lines.
+     * The conductor parses this, strips reserved keys, overlays the core BB_*
+     * vars, and injects the result into the agent run env AND the workspace hooks.
+     * Omitted when the ticket (and its ancestors) set none. Values may be secret.
+     */
+    effectiveEnvVars?: string;
+    issueUrl?: string;
+    /** BB-495: the ticket's project, so a dispatched agent can name it on its own calls. */
+    projectId?: string;
+    projectName?: string;
+    /**
+     * BB-495: the project's workspace, resolved through `bb_project.group_id.workspace_id`.
+     * Omitted when the project or its group carries no resolvable workspace.
+     */
+    workspaceId?: string;
+    workspaceName?: string;
+    /** Ticket label term names (bb_labels vocab), sideloaded for agent selection. Empty when none. */
+    labels: string[];
+    /** Ticket environments (bb_environment refs), each as name + tier, sideloaded for agent selection. Empty when none. */
+    environments: {
+        name: string;
+        tier: string;
+    }[];
+}
+export interface ActiveRun {
+    runUuid: string;
+    ticketUuid: string;
+    ticketIdentifier: string;
+    branchName: string;
+    state: string;
+    stateAtStart: string;
+    /** Absolute path of the per-run git worktree, or '' when unset. */
+    worktreePath: string;
+}
+export interface ConductorStatus {
+    id: string;
+    project: string;
+    label: string;
+    status: string;
+    lastSeen: number;
+    load: number;
+    /**
+     * The checkout root the conductor last registered from (BB-450 D3) — the
+     * top of the working tree, not its `.bakers` config directory. Empty when
+     * never reported. A record written before BB-450 still carries the
+     * legacy `.bakers` value until its next heartbeat rewrites it.
+     */
+    workspaceRoot: string;
+    /** Lease expiry (unix seconds); with lastSeen it derives liveness. 0 = unset. */
+    leaseExpiresAt: number;
+    maxParallel: number;
+    /** The last pid the conductor's serve loop reported, if any (BB-232). */
+    lastPid?: number;
+    /** The config stem it was started from, as `--conductor <name>` takes it. */
+    conductorName?: string;
+    /**
+     * The MachineContext host stem (bb_machine.host_key) this record last
+     * heartbeat with (BB-450 AC-4) — `signalVerifiedProcess()` compares it
+     * against this machine's own, so lifecycle commands can never signal a
+     * conductor on another host. Empty when never reported.
+     */
+    hostKey?: string;
+}
+export interface FinalizableRun {
+    runUuid: string;
+    /** Numeric run id (the `#<runId>` tab-label token); scopes the run's tab-close at finalise (BB-183). */
+    runId: number;
+    /**
+     * The run's ticket and the state it started in, read from the run record so
+     * a restarted conductor can rebuild the `after_run` context (BB-599).
+     * '' / undefined when unset.
+     */
+    ticketUuid?: string;
+    stateAtStart?: string;
+    /** Absolute path of the per-run git worktree, or '' when unset. */
+    worktreePath: string;
+    /** Id of the agent that ran (BB-144); routes footprint parsing at finalize. '' / undefined when unset. */
+    agent?: string;
+    /**
+     * When the run started (bb_run.started_at), read back purely as a lower
+     * bound for transcript selection (BB-473) — an agent with no session-id
+     * mechanism (codex, opencode) discards any transcript older than this so a
+     * prior run's leftover transcript in the same worktree can never be
+     * finalised onto this run. NOT used to (re)compute `duration_s`, which
+     * stays transcript-derived (BB-151). '' / undefined when unset.
+     */
+    startedAt?: string;
+}
+/**
+ * The attributes the conductor writes in the single PATCH that closes a run:
+ * the effort footprint parsed from the transcript, and the runtime that
+ * produced it. The runtime members are optional because a value that cannot be
+ * resolved is omitted from the payload entirely rather than sent as a
+ * placeholder — an absent key leaves the field NULL on the server, which is a
+ * readable "not resolved", where an empty string would read as an answer.
+ */
+export interface RunMetrics {
+    tokens: number;
+    duration_s: number;
+    agent_turns: number;
+    tool_calls: number;
+    user_prompts: number;
+    user_prompt_words: number;
+    /** Active agent time in seconds; the human wait is `duration_s - active_s`. */
+    active_s: number;
+    /** The harness package id that drove the session, e.g. `claude`. */
+    harness?: string;
+    /** The model the chosen candidate pins, when configured; otherwise the raw
+     * model id the transcript records, e.g. `claude-opus-5`. */
+    model?: string;
+    /** The candidate's configured exact model version, when configured;
+     * otherwise the raw model id the transcript records for the turn that
+     * ran. */
+    model_version?: string;
+}
+/** One `bb_metric` row of a ticket's `metrics` field, in the fixed output format. */
+export interface TicketMetric {
+    name: string;
+    /** The number as a string with exactly 4 decimals, e.g. `"71.0000"`. */
+    value: string;
+    unit: string | null;
+    /**
+     * Unix seconds, shared by every row of one measurement; rows read back from
+     * the server may carry it as an RFC 3339 string.
+     */
+    recorded: number | string;
+}
+/**
+ * A closed ticket whose worktree has not yet been torn down — the
+ * conductor's teardown work list, driven by the durable `cleaned_up` flag
+ * (BB-89). Since BB-451 the server closes every terminal ticket on its own
+ * save, so "finished" collapses to `closed = 1`; `cleaned_up=0` (or never
+ * written at all) means the herdr worktree still needs reclaiming. The
+ * reconciliation is NOT scoped to a conductor's machine_id, so it also
+ * surfaces tickets whose conductor was down at close or whose `conductor_id`
+ * was reassigned.
+ */
+export interface UncleanTicket {
+    ticketUuid: string;
+    /** The ticket's git branch — the key herdr resolves the worktree by. */
+    branchName: string;
+    /** The ticket's workflow state (`done`, `cancelled`, …), '' when unset. */
+    state: string;
+    /** The branch the ticket's merge request targets, '' when unset. */
+    baseBranch: string;
+    /** Whether the ticket's `links` hold a merge request (title `MR`). */
+    hasMr: boolean;
+    /**
+     * Absolute path of the ticket's worktree (from its latest run's
+     * `worktree_path`), or '' when unresolved. The cwd the teardown runs in.
+     */
+    worktreePath: string;
+    /**
+     * UUID of the ticket's latest run — the one {@link worktreePath} came from —
+     * or '' when the ticket has no run with a path. The record teardown notes are
+     * written to (BB-293). Resolved by the same query that resolves the path,
+     * so it costs no extra round-trip.
+     */
+    runUuid: string;
+}
+/** An open, frozen ticket of this conductor and where its worktree is. */
+export interface FrozenTicket {
+    ticketUuid: string;
+    identifier: string;
+    /** Latest run's worktree path, or '' when unresolved. */
+    worktreePath: string;
+}
+/** Extra conductor-writable bb_run attributes (besides state/lease). */
+export interface RunWriteAttributes {
+    /** Absolute path of the per-run git worktree (set by the conductor). */
+    worktree_path?: string;
+    /** Id of the agent the conductor chose for this run (BB-144), for footprint routing. */
+    agent?: string;
+    /**
+     * Timestamp of THIS dispatch attempt (BB-473 round 4), re-stamped on
+     * every `markRunning` call — including a re-dispatch of an already-run
+     * ticket. Read back as `FinalizableRun.startedAt` and used as a lower
+     * bound at finalise for agents with no session mechanism at all.
+     *
+     * Whole seconds since the epoch (`Math.floor(Date.now() / 1000)`),
+     * matching every other timestamp this method's caller writes (`heartbeat`,
+     * `closed_date`) — NOT a fractional-second ISO string. `bb_run.started_at`
+     * is a Drupal `timestamp` field, whose normalizer accepts `U` (epoch
+     * seconds), ISO 8601 or RFC 3339, none of which carries a fractional
+     * component; a fractional string is silently rejected by the JSON:API
+     * write (review round 4, Critical 1) and takes `worktree_path`/`agent` down
+     * with it, since all three are on the same PATCH.
+     */
+    startedAt?: string | number;
+}
+/** Eligible work withheld by the authoritative machine admission budget. */
+export interface ClaimWithheld {
+    reason: 'machine_capacity';
+    occupancy: number;
+    capacity: number;
+    /** Running runs have no fixed release deadline. */
+    retryAt: null;
+}
+/** One pending inbox message for this conductor. */
+export interface InboxMessage {
+    /** The message entity's UUID. */
+    id: string;
+    /** `<addon>.<message key>`, e.g. `ports.tunnel`. */
+    messageId: string;
+    /** The responsible handler's version at send time (recorded only). */
+    version: string;
+    ticketUuid: string;
+    payload: Record<string, unknown>;
+    /** The ticket's newest worktree on this conductor, null when none. */
+    worktreePath: string | null;
+    /** The sender's user UUID; absent when the server sends none. */
+    requestedBy?: string;
+}
+/** The inbox poll: this conductor's pending messages. */
+export interface InboxSnapshot {
+    messages: InboxMessage[];
+}
+/** The server's answer to an addon registration. */
+export interface AddonRegistration {
+    accepted: Array<{
+        name: string;
+        version: string;
+        id: string;
+    }>;
+    rejected: Array<{
+        name: string;
+        version: string;
+        error: string;
+    }>;
+}
+export interface BbRemote {
+    /** POSTs heartbeat registration; returns the Drupal entity uuid. */
+    registerConductor(reg: ConductorRegistration): Promise<string>;
+    /**
+     * Records a heartbeat server-side: POSTs the heartbeat resource
+     * (recreating a vanished registration), refreshes last_seen/lease/load,
+     * and brings the conductor online. Keyed on conductor_id, so it never
+     * 404s — the self-heal lives on the server, not the client. Returns the
+     * resulting status (`online` | `offline`).
+     */
+    heartbeat(reg: ConductorRegistration, currentLoad: number, leaseSeconds?: number): Promise<string>;
+    getConductorStatus(conductorId: string): Promise<string | null>;
+    setConductorStatus(conductorId: string, status: 'offline'): Promise<void>;
+    listConductors(owner?: 'me'): Promise<ConductorStatus[]>;
+    activeRunCount(conductorId: string): Promise<number>;
+    /**
+     * Shared host capacity for this `host_key` (bb_machine, BB-353 D5).
+     * After a heartbeat that reported this process's load, `currentLoad` is the
+     * sum of online conductors on the machine (peers + self). Null when the
+     * control plane has no machine row yet — callers fall back to local count.
+     */
+    machineCapacity(hostKey: string): Promise<{
+        maxParallel: number;
+        currentLoad: number;
+    } | null>;
+    fetchActiveRuns(conductorId: string): Promise<ActiveRun[]>;
+    claimNext(claim: ClaimOptions): Promise<ClaimedRun | ClaimWithheld | null>;
+    getTicket(ticketUuid: string): Promise<Ticket>;
+    /**
+     * BB-495: every `bb_workspace` uuid the dispatching identity can reach —
+     * dispatch exports this as `BB_WORKSPACE_IDS` so the agent knows the full
+     * radius it may name, not only the point it starts standing on.
+     */
+    getReachableWorkspaces(): Promise<string[]>;
+    /** Returns the run's worktree_path, or '' when unset. */
+    getRunWorktree(runUuid: string): Promise<string>;
+    /**
+     * Returns the identifier of the run's ticket, or '' when unresolved. Lets the
+     * release path derive the tab matching ref (the ticket identifier) from a run
+     * uuid alone.
+     */
+    getRunTicketIdentifier(runUuid: string): Promise<string>;
+    /**
+     * Returns the branch_name of the run's ticket, or '' when unresolved. Used
+     * by dispatch for the per-(branch,state) herdr tab model.
+     */
+    getRunTicketBranchName(runUuid: string): Promise<string>;
+    markRunning(runUuid: string, attrs?: RunWriteAttributes): Promise<void>;
+    /**
+     * Terminalise a run to the `failed` state on a dispatch/setup error (BB-149).
+     * PATCHes state=failed, records the failure detail in `error_log`, and closes
+     * the run (closed + closed_date). `failed` is a terminal sibling of `expired`
+     * (dispatch error vs lease lapse), so the run stops counting toward capacity
+     * and its ticket is no longer blocked by the single-active-run gate — instead
+     * of the old "leave it `claimed` to expire after ~300s" silent stall. The
+     * failure is visible immediately and its cause is recorded.
+     */
+    markFailed(runUuid: string, errorLog: string): Promise<void>;
+    /**
+     * Runs this conductor owns that are state in (done, cancelled) but not yet
+     * closed — the conductor's one-shot finalisation work list. Cancelled runs
+     * retain their transcript while their agent tab is stopped and closed.
+     */
+    fetchFinalizableRuns(conductorId: string): Promise<FinalizableRun[]>;
+    /**
+     * Finalise a run: set closed + closed_date, (when non-empty) log, and (when
+     * given) the per-run footprint metrics (BB-132). No state change — the run
+     * is already terminal.
+     */
+    finalizeRun(uuid: string, log: string, metrics?: RunMetrics): Promise<void>;
+    /**
+     * Closed tickets (closed=1) whose worktree is not yet torn down
+     * (cleaned_up=0, or never written at all) — the conductor's teardown work
+     * list (BB-89). Since BB-451 the server closes every terminal ticket on
+     * its own save, so this asks one question — closed but not cleaned up —
+     * with no workflow-state reasoning left in it. Driven by the durable
+     * `cleaned_up` flag AND scoped to the reaping conductor (BB-121): only
+     * tickets assigned to `conductorId` are loaded, so every ticket on the list
+     * is unambiguously this conductor's — a missing worktree means "already torn
+     * down on this host", not "belongs to another host". The same query backs
+     * the live tick and the standalone `bakers oven clean`. Empty once every
+     * closed ticket this conductor owns is cleaned.
+     */
+    fetchUncleanedTickets(conductorId: string): Promise<UncleanTicket[]>;
+    /**
+     * Mark a ticket's worktree torn down: set cleaned_up=true so it drops off the
+     * {@link fetchUncleanedTickets} work list. Written ONLY after a verified
+     * teardown, so a teardown miss leaves cleaned_up=0 and the next reconciliation
+     * retries — one miss never orphans the workspace, and a re-run on an
+     * already-cleaned ticket is a no-op (it is no longer on the list).
+     */
+    markTicketCleanedUp(uuid: string): Promise<void>;
+    /**
+     * Replace the ticket's `metrics` rows whose name starts with `namespace`
+     * by `rows`, keeping every other row: one read and one PATCH of `metrics`
+     * alone. The server keeps `metrics` writable on a closed ticket until it is
+     * cleaned up, so the reaper calls this before teardown.
+     */
+    replaceTicketMetrics(uuid: string, namespace: string, rows: TicketMetric[]): Promise<void>;
+    /**
+     * Open tickets assigned to this conductor that are frozen, each with its
+     * latest run's worktree path ('' when none). Drives `on_freeze`/`on_resume`.
+     */
+    fetchFrozenTickets(conductorId: string): Promise<FrozenTicket[]>;
+    /**
+     * Append one diagnostic line to a run's log (BB-293) — how the reaper
+     * records what it found on the run record itself, not only in this machine's
+     * process log. Touches `log` alone: the run is already closed, and its
+     * lifecycle fields are not this call's business. An empty `runUuid` writes
+     * nothing.
+     */
+    appendRunNote(runUuid: string, note: string): Promise<void>;
+    /**
+     * Resolve a ticket identifier (e.g. "BB-134") to its uuid+title within a
+     * project, or null when no such ticket exists. Used by the
+     * `bakers deployment tickets` helper to turn commit-message identifiers into tickets.
+     */
+    resolveTicketByIdentifier(project: string, identifier: string): Promise<{
+        uuid: string;
+        title: string;
+    } | null>;
+    /**
+     * Registers this conductor's addon definitions: each is upserted by name and
+     * version and lists this conductor; rejected ones carry the server's reason.
+     */
+    registerAddons(conductorId: string, definitions: Array<AddonDefinitionV2>): Promise<AddonRegistration>;
+    /** The conductor's pending inbox messages. */
+    fetchInbox(conductorId: string): Promise<InboxSnapshot>;
+    /** Answers an inbox message (by message UUID). */
+    writeInboxResult(messageUuid: string, status: 'running' | 'done' | 'failed', result?: MessageResult): Promise<void>;
+}

package/dist/src/plugins/remote.js

@@ -0,0 +1 @@
+export {};

package/dist/src/plugins/workspace.d.ts

@@ -0,0 +1,69 @@
+export interface EnsuredWorkspace {
+    path: string;
+    instructions: {
+        path: string;
+        sha256: string;
+        text: string;
+    } | null;
+    /**
+     * Whether this call CREATED the worktree (true) or reused an existing one
+     * (false). The core runs the `after_create` lifecycle hook on a fresh
+     * worktree, or on a reused one with no recorded successful `after_create`
+     * (BB-663), so it needs to know which happened. Lifecycle hooks themselves
+     * are no longer a workspace concern (BB-84): the executor owns and runs
+     * them best-effort.
+     */
+    created: boolean;
+}
+export interface BbWorkspace {
+    /**
+     * Ensure a per-ticket worktree exists. `branch`, when given, is the branch
+     * name the dispatcher computed for the ticket. The git plugin treats it as a
+     * readable title to slug into its branch template; the herdr plugin uses it
+     * verbatim as the worktree branch. The worktree directory key/path stays
+     * identifier- or branch-derived so reuse is stable across runs.
+     *
+     * `baseRef`, when given, overrides the base the new branch is created from
+     * (e.g. `origin/<base_branch>` so a sub-ticket stacks on its parent); if it
+     * does not resolve on the remote the implementation falls back to its default
+     * base — never a hard error.
+     *
+     * Reports `created` so the caller can decide whether `after_create` needs to
+     * run (fresh worktree, or no recorded success for this one — BB-663).
+     * Lifecycle-hook invocation is NOT a workspace responsibility
+     * anymore — the executor owns all hooks (BB-84).
+     */
+    ensure(identifier: string, branch?: string, baseRef?: string): Promise<EnsuredWorkspace>;
+    /**
+     * Apply the workspace's "open" layout — for a hosted workspace, the startup
+     * command(s) of the freshly created workspace's initial pane.
+     *
+     * OPTIONAL: a workspace with no layout concept (git, fake) simply omits it and
+     * the conductor calls it with `?.`.
+     *
+     * BB-237 — why this is a SEPARATE call and not part of `ensure()`. The
+     * layout's startup command typically names the bakers CLI, which the
+     * `after_create` lifecycle hook builds. Applied inside `ensure()` it
+     * necessarily ran BEFORE that hook, so in a self-hosting checkout the command
+     * fired minutes before the binary it names existed. The only remedy available
+     * to a config author was a cross-process handshake — a sentinel wait loop
+     * inside the pane command itself. Splitting the call lets the conductor order
+     * the two correctly (`after_create` → `applyOpenLayout`), which removes the
+     * need for any handshake.
+     *
+     * The conductor calls this ONLY on a freshly created workspace
+     * ({@link EnsuredWorkspace.created}), because only a fresh create has an
+     * initial pane to lay out; re-applying on reuse would start a duplicate editor
+     * process on every reattach. Deliberately a NARROWER gate than the one on
+     * `after_create`, which runs again on a reuse with no recorded success
+     * (BB-663), not on every dispatch.
+     *
+     * Best-effort by contract: implementations log and swallow a failing layout so
+     * it can never wedge dispatch.
+     */
+    applyOpenLayout?(path: string, ctx: {
+        identifier: string;
+        branch: string;
+        title: string;
+    }): Promise<void>;
+}

package/dist/src/plugins/workspace.js

@@ -0,0 +1 @@
+export {};

package/dist/src/preset.d.ts

@@ -0,0 +1,2 @@
+import type { Preset } from './plugins/preset.js';
+export declare const commands: Preset['commands'];

package/dist/src/preset.js

@@ -0,0 +1,8 @@
+export const commands = (acc) => [
+    ...acc,
+    {
+        name: 'oven',
+        plugin: '@bakers-build/conductor/commands/conductor',
+        describe: 'node-agent lifecycle + local registry',
+    },
+];