@bridge4dev/runner 0.13.1 → 0.22.1

package/dist/recipe.js

@@ -0,0 +1,238 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { PROJECT_RECIPE_PATH, canonicalRecipeJson, parseProjectRecipe, recipeSteps, } from './recipe-schema.js';
+import { evaluateRecipeCommand, maskString } from './policy.js';
+/**
+ * `.devbridge/project.json` — read, never executed (session 14).
+ *
+ * The file in a repository is a PROPOSAL. Nothing in this module runs anything:
+ * it reads the file, says whether it parses, and hands back a fingerprint. The
+ * executable copy lives on the DevBridge side and gets there only when a human
+ * with manager rights approves it — because an agent can edit files in its own
+ * branch, and «the runner does what the file says» would be arbitrary command
+ * execution by diff.
+ */
+/** A recipe file bigger than this is not a recipe. */
+const RECIPE_MAX_BYTES = 64 * 1024;
+/**
+ * A stable fingerprint of a recipe.
+ *
+ * `verify_start` carries it and the runner refuses a run whose recipe does not
+ * match: an approval is an approval of specific commands, and «the approved
+ * recipe» has to mean the same bytes on both sides.
+ */
+export function recipeFingerprint(recipe) {
+    return crypto.createHash('sha256').update(canonicalRecipeJson(recipe)).digest('hex').slice(0, 32);
+}
+/**
+ * Read the proposal out of a checkout.
+ *
+ * `lstat` and not `stat`: a symlink at `.devbridge/project.json` pointing at
+ * `~/.aws/credentials` would otherwise be read and shown verbatim on the
+ * approval screen.
+ *
+ * The DIRECTORY is checked the same way, and separately (session 15): `lstat`
+ * on the file follows every symlink above it, so `.devbridge` itself being a
+ * link to somewhere else in the filesystem walked straight past the guard while
+ * the guard's own comment said it did not.
+ */
+export function readRecipeProposal(root) {
+    const file = path.join(root, PROJECT_RECIPE_PATH);
+    const empty = {
+        path: file,
+        present: false,
+        raw: null,
+        recipe: null,
+        error: null,
+        sha: null,
+        steps: [],
+        commands: [],
+        refusals: [],
+    };
+    // Everything read here is shown to a human and hashed into an approval, so
+    // it has to come from inside the checkout — not from wherever a link points.
+    const insideCheckout = (() => {
+        try {
+            const realRoot = fs.realpathSync(root);
+            const realDir = fs.realpathSync(path.dirname(file));
+            const rel = path.relative(realRoot, realDir);
+            return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+        }
+        catch {
+            // No `.devbridge` directory at all — the ordinary case, and the read
+            // below reports it as «no recipe» on its own.
+            return true;
+        }
+    })();
+    if (!insideCheckout) {
+        return {
+            ...empty,
+            present: true,
+            error: `${PROJECT_RECIPE_PATH} points outside the repository`,
+        };
+    }
+    let raw;
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile()) {
+            return { ...empty, present: true, error: `${PROJECT_RECIPE_PATH} is not a regular file` };
+        }
+        if (stat.size > RECIPE_MAX_BYTES) {
+            return {
+                ...empty,
+                present: true,
+                error: `${PROJECT_RECIPE_PATH} is larger than ${Math.round(RECIPE_MAX_BYTES / 1024)} KB`,
+            };
+        }
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return empty;
+    }
+    const masked = maskString(raw).slice(0, RECIPE_MAX_BYTES);
+    let parsedJson;
+    try {
+        // JSONC in the plan's example is illustrative; the file itself is JSON.
+        // Comments are stripped rather than refused — a recipe people hand-write is
+        // exactly the kind of file that grows a `// why` line.
+        parsedJson = JSON.parse(stripJsonComments(raw));
+    }
+    catch (error) {
+        return {
+            ...empty,
+            present: true,
+            raw: masked,
+            error: `${PROJECT_RECIPE_PATH} is not valid JSON: ${String(error instanceof Error ? error.message : error).slice(0, 200)}`,
+        };
+    }
+    const parsed = parseProjectRecipe(parsedJson);
+    if (!parsed.ok) {
+        return { ...empty, present: true, raw: masked, error: parsed.error };
+    }
+    return {
+        path: file,
+        present: true,
+        raw: masked,
+        recipe: parsed.recipe,
+        error: null,
+        sha: recipeFingerprint(parsed.recipe),
+        steps: recipeSteps(parsed.recipe),
+        commands: recipeCommands(parsed.recipe),
+        refusals: recipeRefusals(parsed.recipe),
+    };
+}
+/**
+ * Every command in the recipe, in the order a person should read them —
+ * `preview.run` and `preview.stop` included, exactly as the refusal check
+ * already covers them.
+ */
+export function recipeCommands(recipe) {
+    const entries = [];
+    for (const name of recipeSteps(recipe)) {
+        const run = recipe.steps?.[name]?.run;
+        if (run)
+            entries.push({ step: name, run });
+    }
+    if (recipe.preview?.run)
+        entries.push({ step: 'preview.run', run: recipe.preview.run });
+    if (recipe.preview?.stop)
+        entries.push({ step: 'preview.stop', run: recipe.preview.stop });
+    return entries.map(({ step, run }) => {
+        const masked = maskString(run);
+        return { step, run: masked, redacted: masked !== run };
+    });
+}
+/**
+ * Every command in the recipe that layer 1 would refuse, named by its step.
+ *
+ * Answered at read time, not at run time. A recipe whose `deploy` step contains
+ * `sudo systemctl restart` must fail the person reading the approval screen, not
+ * a build twenty minutes into a release.
+ */
+export function recipeRefusals(recipe) {
+    const refusals = [];
+    // A command a person cannot read is a command they cannot approve. Masking is
+    // a rewrite, and the executed copy is the unmasked one — so a redaction here
+    // is not a cosmetic detail, it is the gap between what was shown and what
+    // will run. Blocking approval closes it, and moving the secret into `env`
+    // (which is never a command) is the way out.
+    for (const command of recipeCommands(recipe)) {
+        if (!command.redacted)
+            continue;
+        refusals.push({
+            step: command.step,
+            reason: 'the command contains something that looks like a secret, so it cannot be shown in full — move it into `env` and approve a command you can read',
+        });
+    }
+    for (const name of recipeSteps(recipe)) {
+        const run = recipe.steps?.[name]?.run;
+        if (!run)
+            continue;
+        const decision = evaluateRecipeCommand(run);
+        if (!decision.allowed)
+            refusals.push({ step: name, reason: decision.reason ?? 'refused' });
+    }
+    if (recipe.preview?.run) {
+        const decision = evaluateRecipeCommand(recipe.preview.run);
+        if (!decision.allowed) {
+            refusals.push({ step: 'preview.run', reason: decision.reason ?? 'refused' });
+        }
+    }
+    if (recipe.preview?.stop) {
+        const decision = evaluateRecipeCommand(recipe.preview.stop, {
+            isPreviewStop: true,
+            ...(recipe.preview.project ? { dockerProject: recipe.preview.project } : {}),
+        });
+        if (!decision.allowed) {
+            refusals.push({ step: 'preview.stop', reason: decision.reason ?? 'refused' });
+        }
+    }
+    return refusals;
+}
+/**
+ * Drop `//` and `/* *\/` comments without touching what is inside strings.
+ *
+ * A hand-rolled scanner rather than a regex: a regex that ignores string
+ * context eats the `//` in a URL, which is exactly what `health.url` is.
+ */
+export function stripJsonComments(text) {
+    let out = '';
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            out += ch;
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '/') {
+            while (i < text.length && text[i] !== '\n')
+                i++;
+            out += '\n';
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '*') {
+            i += 2;
+            while (i < text.length && !(text[i] === '*' && text[i + 1] === '/'))
+                i++;
+            i++;
+            continue;
+        }
+        out += ch;
+    }
+    // A trailing comma is the other thing a hand-written file grows.
+    return out.replace(/,(\s*[}\]])/g, '$1');
+}
+//# sourceMappingURL=recipe.js.map

package/dist/self-update.d.ts

@@ -45,6 +45,13 @@ export interface SelfUpdateOptions {
     packageDir?: string | null;
     /** Test seam: is this process supervised (defaults to autodetect). */
     supervised?: boolean;
+    /**
+     * Test seam for the resource-limits drop-in. Injected rather than called
+     * directly because the real one writes into `$HOME` — a test that exercised
+     * the update path would otherwise reconfigure the developer's own service.
+     * Returns true when it wrote something (and therefore needs a daemon-reload).
+     */
+    writeLimits?: () => boolean;
 }
 /**
  * Directory of the installed runner package, or null when it is running from a

package/dist/self-update.js

@@ -5,7 +5,7 @@ import { promisify } from 'node:util';
 import { log } from './log.js';
 import { stateDir } from './paths.js';
 import { RUNNER_VERSION } from './version.js';
-import { buildUnit, unitIsBroken, unitPath } from './service-unit.js';
+import { buildUnit, limitsOverridePath, unitIsBroken, unitPath, writeLimitsOverride, LIMITS_VERSION, } from './service-unit.js';
 const execFileAsync = promisify(execFile);
 const NPM_TIMEOUT_MS = 180_000;
 const VERIFY_TIMEOUT_MS = 30_000;
@@ -303,6 +303,33 @@ export async function selfUpdate(options) {
                 `could not be repaired (${describe(error)}). Run \`devbridge-runner install-service\` on the server.`, { rollbackTarball, ...(toVersion ? { toVersion } : {}) });
         }
     }
+    // The resource policy is versioned separately from the code, because the unit
+    // is written once at install time and the numbers baked into it before 0.21.0
+    // are what killed live sessions (QA-112 BLOCKER-1). An update is the only
+    // moment we are guaranteed to be running on the server with the right to fix
+    // that, so it happens here — and the restart below is what makes it effective.
+    //
+    // Deliberately NOT fatal: a runner that refuses to update because it could not
+    // improve its own limits is strictly worse than one that updates without the
+    // improvement. It is logged loudly and `doctor` reports it.
+    try {
+        if ((options.writeLimits ?? writeLimitsOverride)()) {
+            await exec('systemctl', ['--user', 'daemon-reload'], {
+                timeout: VERIFY_TIMEOUT_MS,
+                env: npmEnv(),
+            });
+            log.warn('self-update: resource limits drop-in written', {
+                path: limitsOverridePath(),
+                version: LIMITS_VERSION,
+            });
+        }
+    }
+    catch (error) {
+        log.error('self-update: could not write the resource limits drop-in', {
+            error: describe(error),
+            hint: 'run `devbridge-runner doctor --fix` on the server',
+        });
+    }
     log.info('self-update: installed', { fromVersion, toVersion });
     return {
         ok: true,

package/dist/service-unit.d.ts

@@ -19,8 +19,55 @@ export declare function unitExecTarget(argv1?: string): {
     execStart: string;
     viaCommand: boolean;
 };
-export declare function unitPath(): string;
+export declare function unitPath(home?: string): string;
 export declare function buildUnit(execStart?: string): string;
+/**
+ * Resource policy for the service, and why it does not live in the unit above.
+ *
+ * The unit is written ONCE, at install time. Until 0.21.0 it carried
+ * `CPUQuota=80%` and `MemoryMax=2G` — and those two lines cost a production
+ * server every session it was running (QA-112 BLOCKER-1, 2026-07-30):
+ *
+ *  - every agent the runner starts, and every `pnpm build`/`tsc`/`vitest` that
+ *    agent runs, is a CHILD of this service and therefore inside this cgroup.
+ *    Three measured `claude` processes are 512/577/646 MB and one workspace
+ *    `pnpm -r typecheck` peaks at 1571 MB, against a ceiling of 2048 MB;
+ *  - `OOMPolicy` defaults to `stop`, so the kernel killing ONE of those children
+ *    tore down the whole service — and with it every other session on the
+ *    machine. `Restart=always` then brought the daemon back with an empty
+ *    session map, which is what the user sees as
+ *    «Runner reconnected. The session was resumed»;
+ *  - `CPUQuota=80%` is 0.8 of ONE core for all of the above, which is separately
+ *    what starves the event loop until the gateway's heartbeat gives up on it.
+ *
+ * So the policy is versioned and shipped as a drop-in instead. A drop-in can
+ * RESET a directive the main unit set (`MemoryMax=` with no value clears it),
+ * which is the only way to fix the servers that already have the bad numbers
+ * baked in — and it never overwrites a unit the operator edited by hand.
+ */
+export declare const LIMITS_VERSION = 2;
+export declare function limitsOverridePath(home?: string): string;
+/**
+ * `CPUQuota` worth keeping: enough headroom that a runaway build cannot make the
+ * box unreachable, but never so little that ordinary work is throttled.
+ *
+ * One core is reserved for the system (sshd, journald, the runner's own event
+ * loop). Below four cores there is nothing to reserve without crippling the
+ * agents, so no quota is set at all — an unusable dev server is a worse failure
+ * than a busy one.
+ */
+export declare function cpuQuotaPercent(cpuCount?: number): number | null;
+export declare function buildLimitsOverride(cpuCount?: number): string;
+/**
+ * Is the shipped resource policy missing or from an older runner?
+ *
+ * Deliberately version-based rather than content-based: an operator may add
+ * their own directives to our file, and re-writing on every start would fight
+ * them. Only the version number decides.
+ */
+export declare function limitsOverrideIsOutdated(readFile?: (p: string) => string, home?: string): boolean;
+/** Write the drop-in. Returns false when nothing needed doing. */
+export declare function writeLimitsOverride(force?: boolean, home?: string): boolean;
 /**
  * Does the installed unit point at something that no longer exists?
  *

package/dist/service-unit.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { systemdUserHome } from './paths.js';
 /**
  * The systemd user unit, and the one decision inside it that matters: what to
  * exec.
@@ -52,8 +53,8 @@ export function unitExecTarget(argv1 = process.argv[1] ?? '') {
     }
     return { execStart: script, viaCommand: false };
 }
-export function unitPath() {
-    return path.join(os.homedir(), '.config', 'systemd', 'user', `${SERVICE_NAME}.service`);
+export function unitPath(home = systemdUserHome()) {
+    return path.join(home, '.config', 'systemd', 'user', `${SERVICE_NAME}.service`);
 }
 export function buildUnit(execStart) {
     const target = execStart ?? unitExecTarget().execStart;
@@ -71,13 +72,117 @@ export function buildUnit(execStart) {
         `ExecStart=${command}`,
         'Restart=always',
         'RestartSec=5',
-        'CPUQuota=80%',
-        'MemoryMax=2G',
         '',
         '[Install]',
         'WantedBy=default.target',
     ].join('\n') + '\n');
 }
+/**
+ * Resource policy for the service, and why it does not live in the unit above.
+ *
+ * The unit is written ONCE, at install time. Until 0.21.0 it carried
+ * `CPUQuota=80%` and `MemoryMax=2G` — and those two lines cost a production
+ * server every session it was running (QA-112 BLOCKER-1, 2026-07-30):
+ *
+ *  - every agent the runner starts, and every `pnpm build`/`tsc`/`vitest` that
+ *    agent runs, is a CHILD of this service and therefore inside this cgroup.
+ *    Three measured `claude` processes are 512/577/646 MB and one workspace
+ *    `pnpm -r typecheck` peaks at 1571 MB, against a ceiling of 2048 MB;
+ *  - `OOMPolicy` defaults to `stop`, so the kernel killing ONE of those children
+ *    tore down the whole service — and with it every other session on the
+ *    machine. `Restart=always` then brought the daemon back with an empty
+ *    session map, which is what the user sees as
+ *    «Runner reconnected. The session was resumed»;
+ *  - `CPUQuota=80%` is 0.8 of ONE core for all of the above, which is separately
+ *    what starves the event loop until the gateway's heartbeat gives up on it.
+ *
+ * So the policy is versioned and shipped as a drop-in instead. A drop-in can
+ * RESET a directive the main unit set (`MemoryMax=` with no value clears it),
+ * which is the only way to fix the servers that already have the bad numbers
+ * baked in — and it never overwrites a unit the operator edited by hand.
+ */
+export const LIMITS_VERSION = 2;
+const LIMITS_MARKER = '# devbridge-limits-version:';
+/** `zz-` so it sorts last: an operator's own drop-in should still win. */
+const LIMITS_FILE = 'zz-devbridge-limits.conf';
+export function limitsOverridePath(home = systemdUserHome()) {
+    return path.join(home, '.config', 'systemd', 'user', `${SERVICE_NAME}.service.d`, LIMITS_FILE);
+}
+/**
+ * `CPUQuota` worth keeping: enough headroom that a runaway build cannot make the
+ * box unreachable, but never so little that ordinary work is throttled.
+ *
+ * One core is reserved for the system (sshd, journald, the runner's own event
+ * loop). Below four cores there is nothing to reserve without crippling the
+ * agents, so no quota is set at all — an unusable dev server is a worse failure
+ * than a busy one.
+ */
+export function cpuQuotaPercent(cpuCount = os.cpus().length) {
+    return cpuCount >= 4 ? (cpuCount - 1) * 100 : null;
+}
+export function buildLimitsOverride(cpuCount = os.cpus().length) {
+    const quota = cpuQuotaPercent(cpuCount);
+    return ([
+        `${LIMITS_MARKER} ${LIMITS_VERSION}`,
+        '# Managed by devbridge-runner. Put your own overrides in a file that sorts',
+        '# after this one, or edit the unit itself — neither is touched by updates.',
+        '',
+        '[Unit]',
+        // Five fast failures used to leave the service in `failed` and the server
+        // offline until someone logged in. A dev runner must always come back;
+        // crash loops are surfaced through `lastExit` in hello, not by giving up.
+        'StartLimitIntervalSec=0',
+        'StartLimitBurst=0',
+        '',
+        '[Service]',
+        // The whole point of the change: one child's OOM must not take the fleet.
+        'OOMPolicy=continue',
+        // Clears `MemoryMax=2G` from units written before 0.21.0.
+        'MemoryMax=',
+        // Soft pressure instead of a hard ceiling: the kernel reclaims and
+        // throttles rather than killing, and the machine keeps a fifth of its
+        // memory for everything that is not this service.
+        'MemoryHigh=80%',
+        // Either a computed quota, or an explicit reset — both of which clear the
+        // `CPUQuota=80%` baked into units written before 0.21.0.
+        quota === null ? 'CPUQuota=' : `CPUQuota=${quota}%`,
+        // Needed for `doctor` and for the memory/CPU figures the runner reports.
+        'MemoryAccounting=yes',
+        'CPUAccounting=yes',
+        // An agent running a monorepo build forks a lot; the default is per-user.
+        'TasksMax=8192',
+    ].join('\n') + '\n');
+}
+/**
+ * Is the shipped resource policy missing or from an older runner?
+ *
+ * Deliberately version-based rather than content-based: an operator may add
+ * their own directives to our file, and re-writing on every start would fight
+ * them. Only the version number decides.
+ */
+export function limitsOverrideIsOutdated(readFile = (p) => fs.readFileSync(p, 'utf8'), home = systemdUserHome()) {
+    let contents;
+    try {
+        contents = readFile(limitsOverridePath(home));
+    }
+    catch {
+        return true; // never written — every server that predates 0.21.0
+    }
+    const line = contents.split('\n').find((l) => l.startsWith(LIMITS_MARKER));
+    if (!line)
+        return true;
+    const version = Number.parseInt(line.slice(LIMITS_MARKER.length).trim(), 10);
+    return !Number.isFinite(version) || version < LIMITS_VERSION;
+}
+/** Write the drop-in. Returns false when nothing needed doing. */
+export function writeLimitsOverride(force = false, home = systemdUserHome()) {
+    if (!force && !limitsOverrideIsOutdated(undefined, home))
+        return false;
+    const target = limitsOverridePath(home);
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(target, buildLimitsOverride(), { mode: 0o644 });
+    return true;
+}
 /**
  * Does the installed unit point at something that no longer exists?
  *

package/dist/supervisor.d.ts

@@ -1,4 +1,5 @@
 import { JournalStore } from './journal.js';
+import { proposeCommitMessage } from './commit-message.js';
 import { selfUpdate, type SelfUpdateOutcome } from './self-update.js';
 import type { RunnerWsClient } from './ws-client.js';
 import type { SessionDescriptor } from './protocol.js';
@@ -30,6 +31,14 @@ export interface SupervisorOptions {
      * machine's owner decides how much of their machine an agent fleet may take.
      */
     maxSessionsLimit?: number;
+    /**
+     * `[verify] enabled` from the runner's own config (session 14). The machine's
+     * owner has the last word on whether project recipes run here at all;
+     * `false` means the capability is not announced and no run can be started.
+     */
+    verifyEnabled?: boolean;
+    /** Test seam for the one-shot commit-message run. */
+    proposeCommitMessage?: typeof proposeCommitMessage;
 }
 export declare class Supervisor {
     private readonly ws;
@@ -54,10 +63,32 @@ export declare class Supervisor {
     private readonly repoLocks;
     /** An update is installing right now — a second one would fight it. */
     private selfUpdateInFlight;
+    /** Session 14: one project-recipe run per machine, and its verdict queue. */
+    private readonly verify;
+    private readonly verifyReports;
     constructor(ws: RunnerWsClient, opts: SupervisorOptions);
+    /**
+     * Push every unacked verdict at the API.
+     *
+     * Called on each reconnect and whenever a run finishes. Sending a report the
+     * API already has is harmless — it is keyed by `runId` and stored idempotently
+     * — while not sending one is a verdict that never existed.
+     */
+    private flushVerifyReports;
     get activeSessionIds(): string[];
     private onFrame;
     private startSession;
+    /**
+     * Where this session is going to work — a worktree of its own, or the project
+     * folder itself (session 16).
+     *
+     * The BRANCH path takes the repo lock because `worktree add` writes into the
+     * shared `.git` (registration + prune), exactly like commit/apply/revert. The
+     * DIRECT path takes none: it only READS which branch a folder is on, and
+     * queueing every session start behind whatever merge happens to be running
+     * would be a lock bought for nothing.
+     */
+    private prepareWorkspace;
     /**
      * Spin the adapter up — for a fresh session, a resume-on-next-message, or a
      * free CHAT session with no prompt at all (the agent boots, reports its
@@ -100,6 +131,23 @@ export declare class Supervisor {
      */
     private pauseForBudget;
     private pumpEvents;
+    /**
+     * "…and N of them are waiting for an answer from you."
+     *
+     * An open question pins its slot deliberately (`isParkable`), so a message
+     * that blames a running turn sends the user to wait for something that will
+     * never happen. Empty when nothing is waiting.
+     */
+    private waitingForAnswerSuffix;
+    /**
+     * Close out every ask this session still has open, with a stated cause.
+     *
+     * Idempotent: the adapter reports its own `question_resolved` when it can, and
+     * `forwardEvent` clears the id — so by the time this runs the set is usually
+     * already empty. What it catches is the path where the adapter never got the
+     * chance, and the alternative there is a card that stays clickable forever.
+     */
+    private withdrawOpenQuestions;
     /**
      * Deliver messages that were held because every slot was taken.
      *
@@ -140,10 +188,27 @@ export declare class Supervisor {
      * returns false and the caller tells the user rather than thrashing.
      */
     private ensureCapacity;
-    /** Idle after a finished turn — safe to kill the process and resume later. */
+    /**
+     * Idle after a finished turn — safe to kill the process and resume later.
+     *
+     * An open question is the exception (session 12): WAITING_INPUT there does
+     * NOT mean "the turn is over", it means the agent's tool call is parked on a
+     * human. Parking such a session killed a live turn — and, worse, killed the
+     * card the user was about to answer — the moment another session wanted a
+     * slot.
+     */
     private isParkable;
     private park;
     private forwardEvent;
+    /**
+     * The dashboard's answer to a parked question (session 12).
+     *
+     * A miss is reported in the feed rather than swallowed: the three cases that
+     * get here — a card from a previous life of the session, a second click, an
+     * ask the runner already withdrew — all look identical to the user unless
+     * somebody says so.
+     */
+    private onQuestionAnswer;
     private onUserMessage;
     /**
      * Run delivery work for one session, strictly after whatever is already
@@ -212,5 +277,47 @@ export declare class Supervisor {
     /** Graceful daemon shutdown: kill agents, keep sessions resumable server-side. */
     shutdown(): void;
 }
+/**
+ * The first message the agent gets.
+ *
+ * Two shapes, and the difference is whether tickets were handed over
+ * (session 16, owner's decision):
+ *
+ *  - **No tickets** — exactly what the human typed, and an empty prompt stays
+ *    empty. That is how you get a session that boots and waits for you to talk
+ *    first; it is a feature, not an oversight.
+ *  - **Tickets handed to a TICKET session** — the assignment is always sent and
+ *    cannot be removed: «Implement ticket #28.» Handing a ticket over IS the
+ *    instruction, so making the human retype it was ceremony. Anything they
+ *    typed follows underneath.
+ *
+ * What is NOT here any more: eight lines about which MCP tools to call and
+ * which statuses to move through. That is a standing convention of the project,
+ * true on the twentieth turn as much as the first, so it moved to the system
+ * prompt beside `CLAUDE.md` — which is read last and therefore overrides ours.
+ */
 export declare function composeInitialPrompt(descriptor: SessionDescriptor): string;
+/**
+ * Extra system-prompt material: where this session is in git, and how tickets
+ * are meant to move (session 13).
+ *
+ * Facts about THIS SESSION, and nothing else. They exist in no file on disk —
+ * which branch the agent is on, that it must not push, where a plan belongs,
+ * what to do with the tickets it was given — so somebody has to say them, and
+ * that somebody is us.
+ *
+ * The project's own documentation is deliberately NOT here. Both agents read
+ * their own file natively, verified live: Claude picks up `CLAUDE.md` through
+ * its memory mechanism (since `settingSources` includes `'project'`), and Codex
+ * picks up `AGENTS.md` even under the runner's isolated `CODEX_HOME`. Pasting a
+ * copy on top of that was work we were doing for no one — and when it was
+ * switched off for Claude alone it briefly left repositories that carry only
+ * `AGENTS.md` with nothing at all, which is precisely the kind of hole a
+ * half-measure digs.
+ *
+ * A repository that wants both agents equipped ships both files, or symlinks
+ * one to the other. That is a repository convention and not something a runner
+ * should paper over.
+ */
+export declare function composeWorkspaceContext(descriptor: SessionDescriptor): string;
 //# sourceMappingURL=supervisor.d.ts.map