@crewhaus/gateway-protocol 0.4.0 → 0.5.0

package/dist/control-codegen.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Codegen for `crewhaus.control.v1` — the ONE place the control-plane wiring
+ * that lands in an emitted daemon is written.
+ *
+ * Five targets emit a daemon (channel, managed, batch, crew, voice). If each
+ * of them spelled the control wiring itself, the five would drift the first
+ * time one of them was touched, and a supervisor would face five subtly
+ * different control planes. So the emitters describe their lanes and
+ * side-channels declaratively and this module renders the text; the runtime
+ * behind it lives in `./control`, which the emitted daemon imports.
+ *
+ * Every renderer takes an `indent` and applies it to every line it produces,
+ * so a caller can splice a block at any nesting depth without reflowing it.
+ */
+/** Package specifier the emitted daemon imports the control runtime from. */
+export declare const CONTROL_RUNTIME_MODULE: "@crewhaus/gateway-protocol/control";
+export type ControlPlaneEmit = {
+    /** Spec name — reported by `/control/v1/healthz` and `/status`. */
+    readonly name: string;
+    /** Target discriminator (`channel` | `managed` | `batch` | `crew` | `voice`). */
+    readonly target: string;
+    /** Identifier the plane is bound to in the emitted daemon. Default `__control`. */
+    readonly varName?: string;
+    /** JS expression evaluating to `string[]` — the channels this daemon serves. */
+    readonly channelsExpr?: string;
+    /** JS expression evaluating to `number | Promise<number>` — parked approvals. */
+    readonly pendingApprovalsExpr?: string;
+    /**
+     * JS expression evaluating to the harness's `AuditLog` (or `undefined`).
+     * Every control call appends a `gateway_request` record through it.
+     */
+    readonly auditLogExpr?: string;
+    readonly indent?: string;
+};
+/**
+ * The import line for the control runtime. Emitted unconditionally by every
+ * daemon-shape target — control.v1 is the lowest common denominator all
+ * daemon shapes share, so a bundle either has it or is a pre-0.5.0 bundle.
+ */
+export declare function renderControlImports(opts?: {
+    readonly pendingApprovals?: boolean;
+    /** Pull in {@link runDrainSweep} — a drain step that sweeps housekeeping. */
+    readonly drainSweep?: boolean;
+    /** Pull in {@link sanitizeControlText} — a daemon that logs untrusted text. */
+    readonly logSafe?: boolean;
+}): string;
+/**
+ * `const __control = createControlPlane({ … });`
+ *
+ * Binding is deferred to {@link renderControlStart} so a daemon can register
+ * its lanes and drain steps (which close over the server/janitor it creates
+ * later) before the socket accepts a single request.
+ */
+export declare function renderControlPlaneBoot(opts: ControlPlaneEmit): string;
+export type ControlLaneEmit = {
+    /** The lane an operator can poke. */
+    readonly lane: "heartbeat" | "schedule";
+    /** Identifier the lane handle binds to (e.g. `__heartbeatLane`). */
+    readonly varName: string;
+    /** Human cadence for `/status` — e.g. `every 60000ms`. */
+    readonly cadence: string;
+    /** Fixed interval, when the lane has one; projects `nextDueAt`. */
+    readonly everyMs?: number;
+    /** JS expression returning `string | undefined` — overrides the projection. */
+    readonly nextDueAtExpr?: string;
+    /**
+     * `false` for a lane whose body does NOT thread `__tick.sessionId` into a
+     * session of its own (the managed fan-out, the batch producer). Such a lane
+     * writes no wake marker and its 202 omits `sessionId` instead of handing the
+     * operator an id that names nothing — see `ControlLaneOptions.ownsSession`.
+     */
+    readonly ownsSession?: boolean;
+    /**
+     * The tick body. Rendered inside `async (__tick) => { … }`, so it can read
+     * `__tick.sessionId` (minted by the lane, identical for timer + operator
+     * fires) and `__tick.synthetic`.
+     */
+    readonly body: string;
+    readonly planeVar?: string;
+    readonly indent?: string;
+};
+/**
+ * Register a pokeable lane. The returned handle's `tick()` is what the timer
+ * calls and `wake()` is what `POST /control/v1/wake` calls — ONE body, so the
+ * operator poke can never diverge from the organic fire, and the lane's
+ * never-overlap guard covers both (a wake during an in-flight tick 409s).
+ */
+export declare function renderControlLane(opts: ControlLaneEmit): string;
+/**
+ * A read-only timer row for `/control/v1/status` (the janitor and dream lanes
+ * are observed, not pokeable). `expr` is a JS expression evaluating to a
+ * `ControlTimerReport`.
+ */
+export declare function renderControlTimer(opts: {
+    readonly expr: string;
+    readonly planeVar?: string;
+    readonly indent?: string;
+}): string;
+/**
+ * Register a drain step. `POST /control/v1/drain` stops intake first (the
+ * public gate starts answering 503 + Retry-After the moment the request lands),
+ * waits out in-flight lane ticks, then runs these steps in order and exits 0.
+ */
+export declare function renderControlDrain(opts: {
+    readonly body: string;
+    readonly planeVar?: string;
+    readonly indent?: string;
+}): string;
+/** `await __control.start();` — binds the dedicated port when one is configured. */
+export declare function renderControlStart(opts: {
+    readonly planeVar?: string;
+    readonly indent?: string;
+}): string;
+/**
+ * The PUBLIC-port wrapper: a bare unauthenticated `GET /healthz` (liveness
+ * only, no state — this is what deployment scaffolds' health checks have been
+ * declaring against nothing) plus the 503 + `Retry-After` intake shed once the
+ * daemon is draining. Everything else falls through to `innerExpr`.
+ *
+ * Renders an inline arrow suitable as a `Bun.serve({ fetch })` value.
+ */
+export declare function renderPublicGateFetch(opts: {
+    readonly innerExpr: string;
+    readonly planeVar?: string;
+}): string;

package/dist/control-codegen.js

@@ -0,0 +1,135 @@
+/**
+ * Codegen for `crewhaus.control.v1` — the ONE place the control-plane wiring
+ * that lands in an emitted daemon is written.
+ *
+ * Five targets emit a daemon (channel, managed, batch, crew, voice). If each
+ * of them spelled the control wiring itself, the five would drift the first
+ * time one of them was touched, and a supervisor would face five subtly
+ * different control planes. So the emitters describe their lanes and
+ * side-channels declaratively and this module renders the text; the runtime
+ * behind it lives in `./control`, which the emitted daemon imports.
+ *
+ * Every renderer takes an `indent` and applies it to every line it produces,
+ * so a caller can splice a block at any nesting depth without reflowing it.
+ */
+/** Package specifier the emitted daemon imports the control runtime from. */
+export const CONTROL_RUNTIME_MODULE = "@crewhaus/gateway-protocol/control";
+function indentBlock(text, indent) {
+    if (indent === "")
+        return text;
+    return text
+        .split("\n")
+        .map((line) => (line === "" ? "" : `${indent}${line}`))
+        .join("\n");
+}
+/** JSON-quote a string for embedding in emitted source. */
+function q(value) {
+    return JSON.stringify(value);
+}
+/**
+ * The import line for the control runtime. Emitted unconditionally by every
+ * daemon-shape target — control.v1 is the lowest common denominator all
+ * daemon shapes share, so a bundle either has it or is a pre-0.5.0 bundle.
+ */
+export function renderControlImports(opts = {}) {
+    const names = [
+        ...(opts.pendingApprovals === true ? ["countPendingApprovals"] : []),
+        "createControlPlane",
+        ...(opts.drainSweep === true ? ["runDrainSweep"] : []),
+        ...(opts.logSafe === true ? ["sanitizeControlText"] : []),
+    ].join(", ");
+    return `import { ${names} } from ${q(CONTROL_RUNTIME_MODULE)};\n`;
+}
+/**
+ * `const __control = createControlPlane({ … });`
+ *
+ * Binding is deferred to {@link renderControlStart} so a daemon can register
+ * its lanes and drain steps (which close over the server/janitor it creates
+ * later) before the socket accepts a single request.
+ */
+export function renderControlPlaneBoot(opts) {
+    const v = opts.varName ?? "__control";
+    const fields = [
+        `name: ${q(opts.name)},`,
+        `target: ${q(opts.target)},`,
+        ...(opts.channelsExpr !== undefined ? [`channels: () => ${opts.channelsExpr},`] : []),
+        ...(opts.pendingApprovalsExpr !== undefined
+            ? [`pendingApprovals: async () => ${opts.pendingApprovalsExpr},`]
+            : []),
+        ...(opts.auditLogExpr !== undefined
+            ? [
+                "audit: async (__rec) => {",
+                `  const __log = ${opts.auditLogExpr};`,
+                "  if (__log !== undefined) await __log.append(__rec);",
+                "},",
+            ]
+            : []),
+    ];
+    const body = [
+        "// crewhaus.control.v1 — the supervisor-facing control plane (§ dedicated",
+        "// port from CREWHAUS_CONTROL_PORT, bearer from CREWHAUS_CONTROL_TOKEN or a",
+        "// boot-minted .crewhaus/run/control-token). Unset port ⇒ no socket opens.",
+        `const ${v} = createControlPlane({`,
+        ...fields.map((f) => `  ${f}`),
+        "});",
+    ].join("\n");
+    return `${indentBlock(body, opts.indent ?? "")}\n`;
+}
+/**
+ * Register a pokeable lane. The returned handle's `tick()` is what the timer
+ * calls and `wake()` is what `POST /control/v1/wake` calls — ONE body, so the
+ * operator poke can never diverge from the organic fire, and the lane's
+ * never-overlap guard covers both (a wake during an in-flight tick 409s).
+ */
+export function renderControlLane(opts) {
+    const plane = opts.planeVar ?? "__control";
+    const body = [
+        `const ${opts.varName} = ${plane}.lane({`,
+        `  lane: ${q(opts.lane)},`,
+        `  cadence: ${q(opts.cadence)},`,
+        ...(opts.everyMs !== undefined ? [`  everyMs: ${opts.everyMs},`] : []),
+        ...(opts.nextDueAtExpr !== undefined ? [`  nextDueAt: () => ${opts.nextDueAtExpr},`] : []),
+        ...(opts.ownsSession === false ? ["  ownsSession: false,"] : []),
+        "  run: async (__tick) => {",
+        indentBlock(opts.body, "    "),
+        "  },",
+        "});",
+    ].join("\n");
+    return `${indentBlock(body, opts.indent ?? "")}\n`;
+}
+/**
+ * A read-only timer row for `/control/v1/status` (the janitor and dream lanes
+ * are observed, not pokeable). `expr` is a JS expression evaluating to a
+ * `ControlTimerReport`.
+ */
+export function renderControlTimer(opts) {
+    const plane = opts.planeVar ?? "__control";
+    return `${indentBlock(`${plane}.timer(() => (${opts.expr}));`, opts.indent ?? "")}\n`;
+}
+/**
+ * Register a drain step. `POST /control/v1/drain` stops intake first (the
+ * public gate starts answering 503 + Retry-After the moment the request lands),
+ * waits out in-flight lane ticks, then runs these steps in order and exits 0.
+ */
+export function renderControlDrain(opts) {
+    const plane = opts.planeVar ?? "__control";
+    const body = [`${plane}.onDrain(async () => {`, indentBlock(opts.body, "  "), "});"].join("\n");
+    return `${indentBlock(body, opts.indent ?? "")}\n`;
+}
+/** `await __control.start();` — binds the dedicated port when one is configured. */
+export function renderControlStart(opts) {
+    const plane = opts.planeVar ?? "__control";
+    return `${indentBlock(`await ${plane}.start();`, opts.indent ?? "")}\n`;
+}
+/**
+ * The PUBLIC-port wrapper: a bare unauthenticated `GET /healthz` (liveness
+ * only, no state — this is what deployment scaffolds' health checks have been
+ * declaring against nothing) plus the 503 + `Retry-After` intake shed once the
+ * daemon is draining. Everything else falls through to `innerExpr`.
+ *
+ * Renders an inline arrow suitable as a `Bun.serve({ fetch })` value.
+ */
+export function renderPublicGateFetch(opts) {
+    const plane = opts.planeVar ?? "__control";
+    return `(__req) => ${plane}.publicGate(__req) ?? (${opts.innerExpr})(__req)`;
+}

package/dist/control.d.ts

@@ -0,0 +1,329 @@
+/**
+ * `crewhaus.control.v1` — the daemon control plane every daemon-shape bundle
+ * serves.
+ *
+ * WHY THIS EXISTS. A compiled daemon's schedulers are in-process
+ * (`setInterval` for `heartbeat:`, `armSchedule` for `schedule:`), so from
+ * the outside there is no way to ask "when does the next heartbeat fire?" and
+ * no way to make one fire now: the phase of a heartbeat is knowable ONLY
+ * inside the process that armed it. A supervisor that wants to drive — not
+ * just watch — a fleet of daemons needs a uniform, signal-free surface. This
+ * module is that surface, written ONCE and consumed by every daemon-emitting
+ * target (channel, managed, batch, crew, voice) so the five shapes can never
+ * drift apart.
+ *
+ * SHAPE OF THE CONTRACT.
+ *   - A DEDICATED control port, separate from any public webhook/gateway
+ *     port. Default bind `127.0.0.1`; the port comes from
+ *     `CREWHAUS_CONTROL_PORT` (`0` asks the kernel for an ephemeral port,
+ *     which is then reported on stdout). Unset ⇒ no control socket at all,
+ *     so upgrading a bundle never opens a listener nobody asked for.
+ *     Exposing it on a PaaS is an explicit opt-in: set the bind + token as
+ *     provider secrets at deploy time.
+ *   - Bearer auth against `CREWHAUS_CONTROL_TOKEN`, or a token minted at boot
+ *     into `<cwd>/.crewhaus/run/control-token` (0600) so a local manager can
+ *     read it off disk. Compared in constant time; never logged, never
+ *     echoed, never written to an audit payload.
+ *   - `GET  /control/v1/healthz` → `{ok, name, target}`
+ *   - `GET  /control/v1/status`  → counters + per-lane timers + channels +
+ *                                  pending approvals
+ *   - `POST /control/v1/wake`    → one synthetic tick down the IDENTICAL code
+ *                                  path as the timer fire
+ *   - `POST /control/v1/drain`   → stop intake, finish in-flight work, exit 0
+ *   - Every call appends a `gateway_request` record to the harness's
+ *     hash-chained audit log when one is wired.
+ *
+ * Separately — and INDEPENDENT of whether the control port is bound — a bare,
+ * unauthenticated `GET /healthz` is served on the daemon's PUBLIC port when it
+ * has one ({@link ControlPlane.publicGate}). Deployment scaffolds declare that
+ * health check but no daemon served it; the liveness answer carries no state,
+ * so closing that gap never exposes control.
+ *
+ * TESTABILITY. `fetch` is a plain `Request → Response` function, so the whole
+ * router (auth, wake, 409-while-in-flight, drain) is exercisable with no
+ * socket, no timers and no daemon. `start()` is the only part that touches
+ * `Bun.serve`.
+ */
+/** Wire identifier for this control protocol. Bumping it is a breaking change. */
+export declare const CONTROL_PROTOCOL: "crewhaus.control.v1";
+/** Every control route lives under this prefix. */
+export declare const CONTROL_PATH_PREFIX: "/control/v1";
+/** Harness-local ops directory. All daemon-written control state lives here. */
+export declare const CONTROL_RUN_DIR: ".crewhaus/run";
+/** File the boot-minted bearer token lands in, mode 0600. */
+export declare const CONTROL_TOKEN_FILENAME: "control-token";
+export declare const CONTROL_BIND_ENV: "CREWHAUS_CONTROL_BIND";
+export declare const CONTROL_PORT_ENV: "CREWHAUS_CONTROL_PORT";
+export declare const CONTROL_TOKEN_ENV: "CREWHAUS_CONTROL_TOKEN";
+/** Loopback-only unless the operator explicitly widens it. */
+export declare const DEFAULT_CONTROL_BIND: "127.0.0.1";
+/**
+ * Longest free-text a control-plane field (`reason`, `by`) may carry into a
+ * daemon's prose log, and the default cap {@link sanitizeControlText} applies.
+ */
+export declare const CONTROL_TEXT_MAX = 200;
+/**
+ * Budget (ms) for a best-effort housekeeping step run during a drain, and the
+ * env var that widens it. `0` skips the step entirely.
+ */
+export declare const DRAIN_SWEEP_BUDGET_ENV: "CREWHAUS_DRAIN_SWEEP_MS";
+export declare const DEFAULT_DRAIN_SWEEP_MS = 5000;
+/** `Retry-After` (seconds) on the 503 a draining daemon answers intake with. */
+export declare const DRAIN_RETRY_AFTER_SECONDS = 15;
+/** The two lanes an operator can poke. Both are in-process timers. */
+export type ControlLane = "heartbeat" | "schedule";
+export type ControlOutcome = "ok" | "error";
+/** Counters `/control/v1/status` reports. Mutated in place by the daemon. */
+export type ControlCounters = {
+    turns: number;
+    heartbeatTicks: number;
+    scheduleWakes: number;
+    janitorRuns: number;
+};
+export type ControlTimerReport = {
+    readonly lane: string;
+    /** Human cadence, e.g. `every 60000ms` or `cron "0 * * * *" UTC`. */
+    readonly cadence: string;
+    readonly lastFiredAt?: string;
+    readonly lastOutcome?: ControlOutcome;
+    readonly nextDueAt?: string;
+};
+/** What a lane's tick body receives. `synthetic` is set only for operator pokes. */
+export type ControlTickContext = {
+    readonly sessionId: string;
+    readonly synthetic?: {
+        readonly reason: string;
+        readonly by: string;
+    };
+};
+export type ControlLaneOptions = {
+    readonly lane: ControlLane;
+    readonly cadence: string;
+    /**
+     * Interval in ms, when the lane has a fixed one. Used to project
+     * `nextDueAt` from the last fire — the number no offline reader can
+     * compute for a heartbeat, which is the entire reason `/status` exists.
+     */
+    readonly everyMs?: number;
+    /** Overrides the `everyMs` projection (cron lanes supply their own). */
+    readonly nextDueAt?: () => string | undefined;
+    /**
+     * Does this lane's body actually THREAD `ctx.sessionId` into a session?
+     *
+     * On the channel shape it does — the tick calls `agent.runTurn({sessionId})`,
+     * so the id the 202 hands back names a transcript the operator can open, and
+     * writing the poke marker into that session's event log is what attributes
+     * the turn to the operator who asked for it.
+     *
+     * On the multi-tenant (managed) and producer (batch) shapes it does NOT: one
+     * tick fans out to a turn per tenant, each in its own session, or enqueues a
+     * job whose handler mints its own. Advertising the lane's id there promised a
+     * transcript that never existed, and the marker it left behind was a `.jsonl`
+     * with no `.json` beside it — a file `sweepExpired`, `crewhaus retention` and
+     * the janitor's TTL eviction all skip BY DESIGN, so it outlived every
+     * retention policy the harness has. Such a lane declares `ownsSession: false`:
+     * no marker is written, and the 202 omits `sessionId` rather than lying. The
+     * poke stays evidenced through the control plane's `gateway_request` audit
+     * record, which carries the same `reason`/`by` and IS covered by retention.
+     *
+     * Default `true` (the channel shape's behaviour).
+     */
+    readonly ownsSession?: boolean;
+    /**
+     * The tick body. The SAME function backs the timer fire and the operator
+     * wake — there is deliberately no second code path to drift.
+     */
+    readonly run: (ctx: ControlTickContext) => Promise<unknown>;
+};
+export interface ControlLaneHandle {
+    readonly lane: ControlLane;
+    /** True while a tick for this lane is executing. Ticks never overlap. */
+    busy(): boolean;
+    /**
+     * ORGANIC fire (the timer's own call). Awaits the tick to completion so
+     * `armSchedule`'s re-arm-after-resolve rule keeps holding. A fire while the
+     * previous tick is still running is dropped, not queued.
+     */
+    tick(): Promise<void>;
+    /**
+     * SYNTHETIC fire (an operator poke). Records the marker, starts the tick and
+     * returns immediately — the caller answers 202 without waiting for a model
+     * round-trip. `sessionId` is present only when the lane owns the session it
+     * was minted for (see {@link ControlLaneOptions.ownsSession}); a lane that
+     * does not returns none rather than a dangling id.
+     */
+    wake(args: {
+        readonly reason: string;
+        readonly by: string;
+    }): Promise<{
+        readonly accepted: boolean;
+        readonly sessionId?: string;
+    }>;
+    /** Resolves once no tick is in flight (used by drain). */
+    settled(): Promise<void>;
+    report(): ControlTimerReport;
+}
+export type ControlAuditRecord = {
+    readonly kind: "gateway_request";
+    readonly payload: Record<string, unknown>;
+};
+export type ControlPlaneOptions = {
+    readonly name: string;
+    readonly target: string;
+    /** Harness root. Defaults to `process.cwd()` — never the bundle dir. */
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Channel ids this daemon serves (channel shape); empty elsewhere. */
+    readonly channels?: () => readonly string[];
+    /** Count of parked approvals. Read-only — must never evict or mutate. */
+    readonly pendingApprovals?: () => number | Promise<number>;
+    /**
+     * The harness's existing hash-chained audit log. Every control call appends
+     * a `gateway_request` record through it. Absent ⇒ control still works, just
+     * un-evidenced (a daemon booted with `CREWHAUS_SECURITY_AUDIT=0`).
+     */
+    readonly audit?: (record: ControlAuditRecord) => Promise<unknown> | unknown;
+    /** Session root for the synthetic-wake marker. Defaults to event-log's. */
+    readonly sessionRootDir?: string;
+    readonly now?: () => number;
+    readonly pid?: number;
+    readonly stdout?: (line: string) => void;
+    readonly stderr?: (line: string) => void;
+    /** Injected for tests; defaults to `process.exit`. */
+    readonly exit?: (code: number) => void;
+    /**
+     * Delay between answering a drain request and running the drain sequence,
+     * so the 202 is on the wire before the process starts tearing down.
+     */
+    readonly drainSettleMs?: number;
+};
+export interface ControlPlane {
+    readonly counters: ControlCounters;
+    /** Register a pokeable lane. Returns the handle the timer body fires. */
+    lane(opts: ControlLaneOptions): ControlLaneHandle;
+    /** Register a read-only timer row (janitor, dream) for `/status`. */
+    timer(report: () => ControlTimerReport): void;
+    /** Register a drain step. Steps run in registration order. */
+    onDrain(step: () => Promise<void> | void): void;
+    draining(): boolean;
+    /** The whole router, socket-free. */
+    fetch(req: Request): Promise<Response>;
+    /**
+     * Bind the dedicated control port when `CREWHAUS_CONTROL_PORT` is set.
+     * Returns undefined when control is not configured (the default).
+     */
+    start(): Promise<{
+        readonly port: number;
+        readonly url: string;
+    } | undefined>;
+    stop(): Promise<void>;
+    /**
+     * The PUBLIC-port gate: answers the bare `GET /healthz` liveness check and,
+     * once draining, sheds every other request with `503` + `Retry-After`.
+     * Returns undefined when the request should fall through to the daemon's
+     * real handler.
+     */
+    publicGate(req: Request): Response | undefined;
+    /** Where the bearer came from. Never returns the token itself. */
+    tokenSource(): {
+        readonly source: "env" | "file";
+        readonly path?: string;
+    } | undefined;
+}
+/**
+ * Flatten untrusted text into ONE printable log-safe line.
+ *
+ * WHY THIS EXISTS. A daemon's stdout/stderr is not just for humans: the
+ * manager PARSES it — the `[control] crewhaus.control.v1 listening on
+ * http://host:port` announcement is the only way it learns a kernel-assigned
+ * control port. Every prose line a daemon prints that interpolates text the
+ * daemon did not author is therefore a log-injection surface: an operator's
+ * `reason`, and — strictly worse, because it needs no operator at all — the
+ * AGENT's own turn output, which a channel message can steer. A single
+ * newline in either would let that text START a line, and a forged
+ * announcement line is enough to repoint the manager's control calls (bearer
+ * included) at an attacker-chosen port.
+ *
+ * So: every control character (C0, DEL + C1) and every Unicode line separator
+ * is replaced with a space, whitespace runs collapse, and the result is capped
+ * — one line, bounded, no matter what went in. Anchoring the manager's own
+ * announcement regex to a line start is the other half of the same fix; this
+ * half is what makes the anchor hold, because it guarantees untrusted text can
+ * never begin a line.
+ */
+export declare function sanitizeControlText(value: string, maxLen?: number): string;
+export type DrainSweepOutcome = "done" | "timeout" | "failed" | "skipped";
+/**
+ * Run a BEST-EFFORT housekeeping step during a drain, under its own budget.
+ *
+ * WHY THIS EXISTS. A drain's contract is "stop intake, finish in-flight work,
+ * exit 0", and a supervisor holds it to a deadline. A janitor sweep is not
+ * in-flight work — it is housekeeping the next boot repeats — so letting it
+ * sit inside that deadline spends the operator's whole drain budget on a step
+ * nothing depends on, and the turn the drain existed to finish gets SIGTERM'd
+ * anyway. Emitted drain steps therefore close their listeners FIRST and run
+ * the sweep through here, last and time-boxed: a slow or wedged sweep can
+ * cost at most `budgetMs`, and its failure is reported, never thrown.
+ */
+export declare function runDrainSweep(step: () => Promise<unknown> | unknown, opts?: {
+    readonly budgetMs?: number;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly onOutcome?: (outcome: DrainSweepOutcome, detail?: string) => void;
+}): Promise<DrainSweepOutcome>;
+/**
+ * Constant-time string compare. Both sides are hashed first so the comparison
+ * is over fixed-length buffers — `timingSafeEqual` throws on length mismatch,
+ * and branching on length would itself leak the token's length.
+ */
+export declare function constantTimeEquals(a: string, b: string): boolean;
+export type ResolvedControlToken = {
+    readonly token: string;
+    readonly source: "env" | "file";
+    readonly path?: string;
+};
+/**
+ * Resolve the control bearer. `CREWHAUS_CONTROL_TOKEN` wins; otherwise a fresh
+ * 32-byte token is minted into `<cwd>/.crewhaus/run/control-token` at 0600.
+ *
+ * Minting FRESH each boot is deliberate: a token left behind by a dead daemon
+ * must not authenticate against its replacement, and the manager reads the
+ * file after it spawns the process, so there is nothing to preserve.
+ */
+export declare function resolveControlToken(opts: {
+    readonly cwd: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}): ResolvedControlToken;
+/**
+ * Append the operator-poke marker to the tick's session log.
+ *
+ * It is written as a `user_message` carrying `synthetic: true` — the
+ * established convention for runtime-injected turns. Every turn-deriving
+ * reader in the stack (feedback distill, the eval-judge transcript digest, the
+ * session summarizer, the advise rules) already skips `synthetic: true` user
+ * messages, so an operator poke can never inflate a turn count or land in a
+ * training set as if a human had typed it. The `control` sub-object is what
+ * lets evals and watch-me positively IDENTIFY the poke and tell it apart from
+ * an organic wake.
+ */
+export declare function recordSyntheticWake(args: {
+    readonly sessionId: string;
+    readonly lane: ControlLane;
+    readonly reason: string;
+    readonly by: string;
+    readonly sessionRootDir?: string;
+}): Promise<void>;
+/** Default filename `@crewhaus/session-store`'s approval store writes. */
+export declare const APPROVALS_FILENAME: "approvals.jsonl";
+/**
+ * Count parked approvals WITHOUT calling `PendingApprovalStore.list()`.
+ *
+ * `list()` compacts the backing file as a side-effect (it drops expired and
+ * superseded lines), exactly like `SessionStore.list()`'s TTL eviction. A
+ * status endpoint is a read: polling it must never rewrite an operator's
+ * approvals ledger. So this folds the JSONL itself — last-wins by `id`, the
+ * same upsert rule `persist` documents — and counts the records still awaiting
+ * a human. A missing file, a torn tail line, or an unreadable record counts as
+ * nothing rather than failing the whole status call.
+ */
+export declare function countPendingApprovals(filePath: string): number;
+export declare function createControlPlane(opts: ControlPlaneOptions): ControlPlane;