@bridge_gpt/mcp-server 0.2.18 → 0.2.20

package/build/executor/process.js

@@ -0,0 +1,81 @@
+/** Default retained stdout/stderr excerpt bound (bytes). */
+export const DEFAULT_EXCERPT_BYTES = 8_000;
+/** Default SIGTERM→SIGKILL grace period (ms). */
+export const DEFAULT_TERM_GRACE_MS = 10_000;
+function byteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+function appendBounded(existing, chunk, limitBytes) {
+    if (byteLength(existing) >= limitBytes)
+        return existing;
+    const combined = existing + chunk;
+    if (byteLength(combined) <= limitBytes)
+        return combined;
+    return Buffer.from(combined, "utf8").subarray(0, limitBytes).toString("utf8");
+}
+async function pump(iterable, onChunk) {
+    if (!iterable)
+        return;
+    try {
+        for await (const chunk of iterable) {
+            onChunk(typeof chunk === "string" ? chunk : String(chunk));
+        }
+    }
+    catch {
+        /* stream errors degrade observability, never correctness */
+    }
+}
+/**
+ * Run an owned child process to completion, enforcing `timeoutSeconds` locally.
+ * On timeout: SIGTERM, then SIGKILL after the grace period if still alive;
+ * classification `timeout`. On normal exit: `clean_exit` (code 0) or `crashed`
+ * (non-zero). Retained stdout/stderr excerpts are bounded.
+ */
+export async function runProcessWithTimeout(proc, timeoutSeconds, deps, options = {}) {
+    const termGraceMs = options.termGraceMs ?? DEFAULT_TERM_GRACE_MS;
+    const limit = options.excerptLimitBytes ?? DEFAULT_EXCERPT_BYTES;
+    let stdoutExcerpt = "";
+    let stderrExcerpt = "";
+    const pumpStdout = pump(proc.stdout, (chunk) => {
+        options.onStdout?.(chunk);
+        stdoutExcerpt = appendBounded(stdoutExcerpt, chunk, limit);
+    });
+    const pumpStderr = pump(proc.stderr, (chunk) => {
+        stderrExcerpt = appendBounded(stderrExcerpt, chunk, limit);
+    });
+    let timedOut = false;
+    let graceTimer;
+    const timeoutTimer = deps.setTimer(() => {
+        timedOut = true;
+        proc.kill("SIGTERM");
+        graceTimer = deps.setTimer(() => {
+            // Still alive after the grace period — escalate.
+            proc.kill("SIGKILL");
+        }, termGraceMs);
+    }, timeoutSeconds * 1000);
+    const { exitCode, signal } = await proc.wait();
+    deps.clearTimer(timeoutTimer);
+    if (graceTimer !== undefined)
+        deps.clearTimer(graceTimer);
+    await pumpStdout;
+    await pumpStderr;
+    let classification;
+    if (timedOut) {
+        classification = "timeout";
+    }
+    else if (exitCode === 0) {
+        classification = "clean_exit";
+    }
+    else {
+        classification = "crashed";
+    }
+    return { classification, exitCode, signal, stdoutExcerpt, stderrExcerpt };
+}
+/**
+ * Immediately SIGKILL an owned process for a stale-claim or dead-man abandonment.
+ * Returns a `killed` classification carrying the abandonment reason.
+ */
+export function killOwnedProcess(proc, reason) {
+    proc.kill("SIGKILL");
+    return { classification: "killed", reason };
+}

package/build/executor/prompt-spec.js

@@ -0,0 +1,235 @@
+/**
+ * Executor-side structured prompt-spec renderer (BAPI-550, TDD §6/§7).
+ *
+ * The reconciler ships a server-authored prompt template in a `spec_review` job's
+ * `payload.prompt_spec` (from `src/python/llms/agents/conductor_jobs/prompt_specs.py`).
+ * This module validates that spec and renders it into the single `claude -p`
+ * prompt string, substituting each declared `{{PLACEHOLDER}}` marker from real
+ * runtime state (ticket spec, base/work branch, git log, prior revise reasons).
+ *
+ * Rendering happens in the executor's prepared-spawn path (`job-runner.ts`) —
+ * NOT in `worker-command.ts` — because resolving `{{GIT_LOG}}` needs the prepared
+ * worktree. Malformed or absent spec data fails loud with
+ * `ExecutorNamedError("ContractError.Prompt", ...)` so the runner posts `/fail`
+ * rather than spawning a worker with a stale or empty prompt.
+ *
+ * SECRET-FREE: thrown messages carry only safe identifiers (job id/type,
+ * placeholder name). This module NEVER logs prompt text, ticket specs, git logs,
+ * or reasons.
+ */
+import { ExecutorNamedError } from "./job-errors.js";
+/** Stable named-error kind used for every prompt-spec contract failure. */
+const PROMPT_CONTRACT_ERROR = "ContractError.Prompt";
+/** The prompt-spec version this renderer understands. */
+const SUPPORTED_PROMPT_SPEC_VERSION = 1;
+/** Bound on the rendered `{{GIT_LOG}}` text inserted into the prompt. */
+const GIT_LOG_MAX_CHARS = 8_000;
+/** Explicit "no prior revise reasons" value — never an empty string. */
+const REVISE_REASONS_NONE = "(none — this is the first review of the ticket spec)";
+/** The `git log` argv used to resolve `{{GIT_LOG}}` (list-based, never shelled). */
+const GIT_LOG_ARGS = ["log", "--oneline", "--decorate", "--max-count=50"];
+/**
+ * The runtime placeholders this renderer knows how to resolve. A declared
+ * placeholder outside this set is an unsupported-marker contract failure rather
+ * than a silent empty substitution.
+ */
+const SUPPORTED_PLACEHOLDERS = new Set([
+    "TICKET_SPEC",
+    "BASE_BRANCH",
+    "WORK_BRANCH",
+    "GIT_LOG",
+    "REVISE_REASONS",
+]);
+function promptContractError(message) {
+    return new ExecutorNamedError(PROMPT_CONTRACT_ERROR, message);
+}
+function isNonBlankString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Extract the ordered, de-duplicated set of literal `{{PLACEHOLDER}}` markers
+ * from a template. Markers are uppercase `[A-Z0-9_]` names; order is first
+ * appearance. Single braces (e.g. a literal `{"verdict": ...}` JSON snippet) are
+ * never matched.
+ */
+export function extractTemplatePlaceholders(template) {
+    const seen = new Set();
+    const ordered = [];
+    const re = /\{\{([A-Z0-9_]+)\}\}/g;
+    let match;
+    while ((match = re.exec(template)) !== null) {
+        const name = match[1];
+        if (!seen.has(name)) {
+            seen.add(name);
+            ordered.push(name);
+        }
+    }
+    return ordered;
+}
+/**
+ * Validate an untrusted `payload.prompt_spec` value and return a typed spec.
+ * Throws `ContractError.Prompt` for a missing/malformed spec: wrong version,
+ * mismatched job type, blank prompts, a non-array/empty/duplicated placeholder
+ * list, a template marker that is not declared, or a declared placeholder that
+ * appears in neither prompt. Messages carry only safe identifiers.
+ */
+export function readPromptSpecPayload(value, expectedJobType) {
+    if (value === null || typeof value !== "object") {
+        throw promptContractError(`job_type '${expectedJobType}' has no usable payload.prompt_spec`);
+    }
+    const raw = value;
+    if (raw.version !== SUPPORTED_PROMPT_SPEC_VERSION) {
+        throw promptContractError(`prompt_spec for job_type '${expectedJobType}' has unsupported version ` +
+            `(expected ${SUPPORTED_PROMPT_SPEC_VERSION})`);
+    }
+    if (raw.job_type !== expectedJobType) {
+        throw promptContractError(`prompt_spec job_type mismatch: claimed job is '${expectedJobType}'`);
+    }
+    if (!isNonBlankString(raw.system_prompt)) {
+        throw promptContractError(`prompt_spec for job_type '${expectedJobType}' has a blank system_prompt`);
+    }
+    if (!isNonBlankString(raw.user_prompt_template)) {
+        throw promptContractError(`prompt_spec for job_type '${expectedJobType}' has a blank user_prompt_template`);
+    }
+    if (!Array.isArray(raw.placeholders) ||
+        raw.placeholders.length === 0 ||
+        !raw.placeholders.every((p) => isNonBlankString(p))) {
+        throw promptContractError(`prompt_spec for job_type '${expectedJobType}' has an invalid placeholders list`);
+    }
+    const declared = raw.placeholders;
+    const declaredSet = new Set();
+    for (const name of declared) {
+        if (declaredSet.has(name)) {
+            throw promptContractError(`prompt_spec for job_type '${expectedJobType}' declares duplicate placeholder '${name}'`);
+        }
+        declaredSet.add(name);
+    }
+    const systemPrompt = raw.system_prompt;
+    const userPromptTemplate = raw.user_prompt_template;
+    const used = new Set([
+        ...extractTemplatePlaceholders(systemPrompt),
+        ...extractTemplatePlaceholders(userPromptTemplate),
+    ]);
+    // Every template marker must be declared (no undeclared substitution).
+    for (const name of used) {
+        if (!declaredSet.has(name)) {
+            throw promptContractError(`prompt_spec for job_type '${expectedJobType}' uses undeclared placeholder '${name}'`);
+        }
+    }
+    // Every declared placeholder must actually appear (no stale declarations).
+    for (const name of declaredSet) {
+        if (!used.has(name)) {
+            throw promptContractError(`prompt_spec for job_type '${expectedJobType}' declares unused placeholder '${name}'`);
+        }
+    }
+    return {
+        version: SUPPORTED_PROMPT_SPEC_VERSION,
+        job_type: expectedJobType,
+        system_prompt: systemPrompt,
+        user_prompt_template: userPromptTemplate,
+        placeholders: declared,
+    };
+}
+/** Format `payload.reasons` as a deterministic bullet list, or the none value. */
+function formatReviseReasons(reasons) {
+    if (!Array.isArray(reasons))
+        return REVISE_REASONS_NONE;
+    const bullets = reasons
+        .filter((r) => isNonBlankString(r))
+        .map((r) => `- ${r.trim()}`);
+    return bullets.length > 0 ? bullets.join("\n") : REVISE_REASONS_NONE;
+}
+/** Read `git log --oneline --decorate --max-count=50` in the worktree, bounded. */
+async function resolveGitLog(context) {
+    const result = await context.runCommand("git", GIT_LOG_ARGS, {
+        cwd: context.worktreePath,
+    });
+    return result.stdout.slice(0, GIT_LOG_MAX_CHARS);
+}
+/**
+ * Resolve every declared placeholder to a concrete runtime value. Throws
+ * `ContractError.Prompt` for an unsupported placeholder name or a required value
+ * (ticket spec / work branch) that cannot be resolved — never a silent empty
+ * substitution.
+ */
+export async function buildPromptSpecPlaceholderValues(job, spec, context) {
+    const payload = job.payload && typeof job.payload === "object"
+        ? job.payload
+        : {};
+    const values = {};
+    for (const name of spec.placeholders) {
+        if (!SUPPORTED_PLACEHOLDERS.has(name)) {
+            throw promptContractError(`prompt_spec for job ${job.id} declares unsupported placeholder '${name}'`);
+        }
+        switch (name) {
+            case "TICKET_SPEC": {
+                if (!isNonBlankString(payload.ticket_spec)) {
+                    throw promptContractError(`job ${job.id} (${job.job_type}) is missing a usable ticket spec for {{TICKET_SPEC}}`);
+                }
+                values.TICKET_SPEC = payload.ticket_spec.trim();
+                break;
+            }
+            case "BASE_BRANCH": {
+                values.BASE_BRANCH = isNonBlankString(payload.base_branch)
+                    ? payload.base_branch.trim()
+                    : context.baseBranch;
+                break;
+            }
+            case "WORK_BRANCH": {
+                if (!isNonBlankString(context.workBranch)) {
+                    throw promptContractError(`job ${job.id} (${job.job_type}) has no work branch for {{WORK_BRANCH}}`);
+                }
+                values.WORK_BRANCH = context.workBranch.trim();
+                break;
+            }
+            case "GIT_LOG": {
+                values.GIT_LOG = await resolveGitLog(context);
+                break;
+            }
+            case "REVISE_REASONS": {
+                values.REVISE_REASONS = formatReviseReasons(payload.reasons);
+                break;
+            }
+        }
+    }
+    return values;
+}
+/**
+ * Replace every declared `{{PLACEHOLDER}}` marker in a template (pure). A SINGLE
+ * left-to-right pass over the ORIGINAL template: each marker is substituted at
+ * most once, and substituted values are never re-scanned. This is deliberate —
+ * a sequential per-placeholder `.split().join()` would feed each iteration's
+ * output back in, so a `{{...}}`-shaped substring inside an already-substituted
+ * value (e.g. untrusted ticket text quoting `{{BASE_BRANCH}}`) would be
+ * clobbered by a later placeholder's value. A marker not present in `values`
+ * (should never happen — declared placeholders are all resolved) is left intact
+ * rather than replaced with an empty string.
+ */
+function substitutePlaceholders(template, values) {
+    return template.replace(/\{\{([A-Z0-9_]+)\}\}/g, (marker, name) => Object.prototype.hasOwnProperty.call(values, name) ? values[name] : marker);
+}
+/** Render the system prompt by substituting the resolved placeholder values. */
+export function buildPromptSpecSystemPrompt(spec, values) {
+    return substitutePlaceholders(spec.system_prompt, values);
+}
+/** Render the user prompt by substituting the resolved placeholder values. */
+export function buildPromptSpecUserPrompt(spec, values) {
+    return substitutePlaceholders(spec.user_prompt_template, values);
+}
+/**
+ * Render a claimed job's `payload.prompt_spec` into the single `claude -p` prompt
+ * string: validate the spec against the job type, resolve every declared
+ * placeholder from runtime state, substitute the system and user prompts
+ * separately, then concatenate them with a blank-line delimiter. Throws
+ * `ExecutorNamedError("ContractError.Prompt", ...)` on any contract failure.
+ */
+export async function renderPromptSpecPrompt(job, context) {
+    const payload = job.payload && typeof job.payload === "object"
+        ? job.payload
+        : {};
+    const spec = readPromptSpecPayload(payload.prompt_spec, job.job_type);
+    const values = await buildPromptSpecPlaceholderValues(job, spec, context);
+    const systemPrompt = buildPromptSpecSystemPrompt(spec, values);
+    const userPrompt = buildPromptSpecUserPrompt(spec, values);
+    return `${systemPrompt}\n\n${userPrompt}`;
+}

package/build/executor/results.js

@@ -0,0 +1,134 @@
+/**
+ * Executor completion result + artifact helpers (BAPI-534, TDD §7 / §13).
+ *
+ * Result envelopes are size-bounded server-side (T6: smoke evidence ≤ 8000 bytes,
+ * whole envelope ≤ 64000 bytes), so evidence is truncated client-side rather than
+ * posting unbounded output. Full verdict-artifact behavior (`result.json`) is
+ * delegated to T3b — this ticket only reads the human-readable critique.
+ */
+import path from "node:path";
+/** Smoke evidence byte cap (mirrors server `SMOKE_EVIDENCE_MAX_BYTES`). */
+export const SMOKE_EVIDENCE_MAX_BYTES = 8_000;
+/** Whole-envelope byte cap (mirrors server `RESULT_JSONB_MAX_BYTES`). */
+export const RESULT_JSONB_MAX_BYTES = 64_000;
+/** Max bytes of a completion artifact (e.g. the critique) posted to the server. */
+export const ARTIFACT_MAX_BYTES = 32_000;
+/** Bounded generic-success `summary` length. */
+export const SUMMARY_MAX_CHARS = 500;
+function byteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+/** Slice a string to at most `maxBytes` UTF-8 bytes (never mid-splitting fatally). */
+function sliceToBytes(value, maxBytes) {
+    if (maxBytes <= 0)
+        return "";
+    if (byteLength(value) <= maxBytes)
+        return value;
+    return Buffer.from(value, "utf8").subarray(0, maxBytes).toString("utf8");
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? "null";
+    }
+    catch {
+        return '"[unserializable]"';
+    }
+}
+/**
+ * Bound a JSON value to `maxBytes`. When the serialized value already fits it is
+ * returned unchanged; otherwise a bounded, clearly-truncated surrogate object is
+ * returned (the original is never posted unbounded).
+ */
+export function truncateJsonValueToBytes(value, maxBytes) {
+    const serialized = safeStringify(value);
+    if (byteLength(serialized) <= maxBytes)
+        return value;
+    // Reserve headroom for the surrogate object's own JSON overhead.
+    const previewBudget = Math.max(0, maxBytes - 128);
+    return {
+        truncated: true,
+        original_bytes: byteLength(serialized),
+        preview: sliceToBytes(serialized, previewBudget),
+    };
+}
+/**
+ * Build the smoke (no-op acceptance) result envelope: `{ result: "pass", evidence }`
+ * — the T6 registry shape, NOT the legacy `{ pass: true }`. Evidence is bounded.
+ */
+export function buildSmokeResult(evidence, result = "pass") {
+    return { result, evidence: truncateJsonValueToBytes(evidence, SMOKE_EVIDENCE_MAX_BYTES) };
+}
+/** Build a minimal, bounded generic success result for a real spawn job. */
+export function buildGenericSuccessResult(input) {
+    const result = {};
+    if (typeof input.summary === "string") {
+        result.summary = input.summary.slice(0, SUMMARY_MAX_CHARS);
+    }
+    if (typeof input.branch === "string")
+        result.branch = input.branch;
+    if (typeof input.headSha === "string")
+        result.head_sha = input.headSha;
+    if (typeof input.localCommitCount === "number") {
+        result.local_commit_count = input.localCommitCount;
+    }
+    return result;
+}
+/**
+ * Fail-open read of `<worktree>/.conductor/critique.md`, mapped to the
+ * `ticket-quality-critique.md` artifact key the server persists to `tickets_links`.
+ * Missing/unreadable → no artifacts (never throws). `result.json` is NOT parsed
+ * here (delegated to T3b).
+ */
+export async function readCompletionArtifacts(worktreePath, deps) {
+    if (!worktreePath)
+        return undefined;
+    const critiquePath = path.join(worktreePath, ".conductor", "critique.md");
+    let content;
+    try {
+        content = await deps.readFile(critiquePath);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof content !== "string" || content.length === 0)
+        return undefined;
+    const bounded = sliceToBytes(content, ARTIFACT_MAX_BYTES);
+    return { "ticket-quality-critique.md": bounded };
+}
+function positiveInt(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+}
+/**
+ * Resolve a positive timeout in seconds. Prefers the job's local `timeout_seconds`,
+ * then `payload.timeout_seconds`, then the injected `fallbackSeconds` (from
+ * `ExecutorOptions.defaultJobTimeoutSeconds`). Returns a structured contract
+ * failure — never spawns — when no positive timeout can be resolved.
+ */
+export function resolveJobTimeoutSeconds(job, fallbackSeconds) {
+    const topLevel = positiveInt(job.timeout_seconds);
+    if (topLevel !== null)
+        return { ok: true, timeoutSeconds: topLevel };
+    const payloadTimeout = positiveInt(job.payload && typeof job.payload === "object"
+        ? job.payload.timeout_seconds
+        : undefined);
+    if (payloadTimeout !== null)
+        return { ok: true, timeoutSeconds: payloadTimeout };
+    const fallback = positiveInt(fallbackSeconds);
+    if (fallback !== null)
+        return { ok: true, timeoutSeconds: fallback };
+    return {
+        ok: false,
+        error: "no positive timeout_seconds could be resolved for the job",
+    };
+}
+/** Build the top-level + telemetry residue commit fields from git telemetry. */
+export function commitResidue(telemetry) {
+    const out = {};
+    if (typeof telemetry.local_commit_count === "number") {
+        out.local_commit_count = telemetry.local_commit_count;
+    }
+    if (typeof telemetry.last_commit_sha === "string") {
+        out.last_commit_sha = telemetry.last_commit_sha;
+    }
+    return out;
+}

package/build/executor/resume-pre-spawn.js

@@ -0,0 +1,179 @@
+/**
+ * Resume pre-spawn preparation protocol (BAPI-535, TDD §7).
+ *
+ * A `resume` job carries the same `worktree_name` and a server-side prompt
+ * template with `{{GIT_LOG}}` / `{{GIT_DIFF}}` placeholders. Before spawning the
+ * headless worker, the executor — in order — resolves (and, if gone, recreates
+ * ONLY from the pushed branch) the worktree, verifies it is on the expected
+ * branch, auto-commits any dirty state as a WIP checkpoint, reads the branch's
+ * git log/diff, and fills the prompt placeholders.
+ *
+ * PRESERVE WORK BY CONSTRUCTION: this module NEVER emits a destructive Git
+ * operation (`reset --hard`, `checkout --force`, `clean -fd`, forced ref update).
+ * Unpushed local commits are the checkpoint mechanism and must survive (TDD §7,
+ * §16 — the amended proposal explicitly rejected `fetch && reset --hard`).
+ */
+import { createWorktreeForTicket } from "../worktree-core.js";
+import { ExecutorNamedError, WorktreeLostBeforePush } from "./job-errors.js";
+import { assertWorktreeOnBranch, listGitWorktrees, findWorktreeByBranch, remoteBranchExists as remoteBranchExistsDefault, } from "./worktree-inspection.js";
+/** The canonical WIP checkpoint commit message (executor-run, deterministic). */
+export const RESUME_WIP_COMMIT_MESSAGE = "wip: auto-checkpoint before resume";
+function asString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+/** Extract the resume payload fields from a claimed job (pure). */
+export function readResumePayloadFields(job) {
+    const payload = job.payload && typeof job.payload === "object" ? job.payload : {};
+    const promptTemplate = typeof payload.prompt_template === "string" ? payload.prompt_template : null;
+    return {
+        promptTemplate,
+        worktreePath: asString(payload.worktree_path),
+        worktreeName: asString(payload.worktree_name),
+        baseBranch: asString(payload.base_branch),
+        expectedBranch: asString(payload.expected_branch),
+    };
+}
+/**
+ * Resolve the expected branch for a resume job: prefer the top-level
+ * `expected_branch`, then a payload override. Fail with a named validation error
+ * (before any command runs) when neither is available — working on an unknown
+ * branch is never safe.
+ */
+export function resolveResumeExpectedBranch(job, fields) {
+    const top = asString(job.expected_branch);
+    if (top)
+        return top;
+    if (fields.expectedBranch)
+        return fields.expectedBranch;
+    throw new ExecutorNamedError("ResumeMissingExpectedBranch", `resume job ${job.id} has no expected_branch (top-level or payload)`);
+}
+/**
+ * Resolve the server-provided prompt template, failing loud with a contract
+ * error when it is missing/empty. Validated BEFORE any worktree resolution or
+ * WIP-checkpoint work so a malformed `resume` payload never spawns a real
+ * `claude -p "" --dangerously-skip-permissions` worker that would burn the full
+ * job timeout before failing generically (mirrors the `implement`/`spec_review`
+ * `ContractError.Prompt` fail-fast in `resolveExecutorPrompt`).
+ */
+export function resolveResumePromptTemplate(job, fields) {
+    const template = fields.promptTemplate;
+    if (typeof template === "string" && template.trim().length > 0) {
+        return template;
+    }
+    throw new ExecutorNamedError("ContractError.Prompt", `resume job ${job.id} has no usable payload.prompt_template`);
+}
+/** Resolve the base branch: payload `base_branch` wins, else executor options. */
+export function resolveResumeBaseBranch(fields, options) {
+    return fields.baseBranch ?? options.baseBranch;
+}
+/**
+ * Resolve the existing worktree path: use the payload `worktree_path` when it
+ * still exists, otherwise locate a worktree whose branch exactly equals the
+ * expected branch. Returns `null` when the worktree is gone (recreation needed).
+ */
+export async function resolveExistingResumeWorktreePath(fields, expectedBranch, seams) {
+    if (fields.worktreePath && (await seams.pathExists(fields.worktreePath))) {
+        return fields.worktreePath;
+    }
+    const listWorktrees = seams.listWorktrees ?? listGitWorktrees;
+    const entries = await listWorktrees(seams.runCommand, seams.cwd);
+    const found = findWorktreeByBranch(entries, expectedBranch);
+    return found ?? null;
+}
+/**
+ * Recreate a missing worktree ONLY from the pushed branch. Verifies
+ * `origin/<expectedBranch>` exists first; if it does not, fails
+ * {@link WorktreeLostBeforePush} (the reconciler restarts `implement` within
+ * budget — TDD §7). When present, reuses the shared Worktrunk primitive with a
+ * branch override for the ticket key and `origin/<expectedBranch>` as the
+ * recreation start point.
+ */
+export async function recreateResumeWorktreeFromPushedBranch(job, expectedBranch, seams) {
+    const remoteExists = seams.remoteBranchExists ?? remoteBranchExistsDefault;
+    const pushed = await remoteExists(seams.runCommand, seams.cwd, expectedBranch);
+    if (!pushed) {
+        throw new ExecutorNamedError(WorktreeLostBeforePush, `resume worktree for '${expectedBranch}' is gone and origin/${expectedBranch} does not exist`);
+    }
+    const key = asString(job.ticket_key) ?? expectedBranch;
+    const coreDeps = {
+        runCommand: seams.runCommand,
+        platform: seams.platform,
+        env: seams.env,
+        cwd: seams.cwd,
+    };
+    const createWorktree = seams.createWorktree ?? createWorktreeForTicket;
+    const row = await createWorktree(coreDeps, key, { [key]: expectedBranch }, seams.worktrunkBinary, 
+    // Cut/reuse from the pushed branch — never from base — so recreation restores
+    // the pushed work, not a fresh empty branch.
+    `origin/${expectedBranch}`, 
+    // Never guard-refuse here: recreation of the SAME pushed branch is the goal.
+    false);
+    if (row.status === "created" && typeof row.path === "string") {
+        return row.path;
+    }
+    throw new ExecutorNamedError(WorktreeLostBeforePush, row.error ?? `failed to recreate worktree for '${expectedBranch}' from origin`);
+}
+/**
+ * Commit any dirty state as a deterministic WIP checkpoint so the injected diff
+ * is always clean and complete. No-op cleanly when the tree is already clean.
+ * NEVER discards work.
+ */
+export async function autoCheckpointDirtyState(worktreePath, seams) {
+    const status = await seams.runCommand("git", ["status", "--porcelain"], { cwd: worktreePath });
+    if (status.stdout.trim().length === 0) {
+        return { committed: false };
+    }
+    await seams.runCommand("git", ["add", "-A"], { cwd: worktreePath });
+    await seams.runCommand("git", ["commit", "-m", RESUME_WIP_COMMIT_MESSAGE], {
+        cwd: worktreePath,
+    });
+    return { committed: true };
+}
+/** Read `git log --oneline origin/<base>..HEAD` in the worktree. */
+export async function readResumeGitLog(worktreePath, baseBranch, seams) {
+    const result = await seams.runCommand("git", ["log", "--oneline", `origin/${baseBranch}..HEAD`], { cwd: worktreePath });
+    return result.stdout;
+}
+/** Read `git diff origin/<base>...HEAD` in the worktree. */
+export async function readResumeGitDiff(worktreePath, baseBranch, seams) {
+    const result = await seams.runCommand("git", ["diff", `origin/${baseBranch}...HEAD`], { cwd: worktreePath });
+    return result.stdout;
+}
+/** Replace EVERY literal `{{GIT_LOG}}` / `{{GIT_DIFF}}` occurrence (pure). */
+export function fillResumePromptPlaceholders(template, gitLog, gitDiff) {
+    return template.split("{{GIT_LOG}}").join(gitLog).split("{{GIT_DIFF}}").join(gitDiff);
+}
+/**
+ * Orchestrate the resume pre-spawn protocol in the required order:
+ *  1. read payload fields
+ *  2. resolve expected branch (fail-fast validation, before any command)
+ *  3. resolve base branch
+ *  4. resolve existing worktree path; recreate-from-pushed when gone
+ *  5. verify the worktree is on the expected branch (BranchMismatch otherwise)
+ *  6. WIP-checkpoint any dirty state (no-op on a clean tree)
+ *  7. read git log/diff
+ *  8. fill the prompt placeholders
+ *
+ * Throws {@link ExecutorNamedError} (`WorktreeLostBeforePush` / `BranchMismatch`
+ * / validation) on the fail-loud conditions; the runner posts `/fail`.
+ */
+export async function prepareResumeSpawn(job, options, seams) {
+    const fields = readResumePayloadFields(job);
+    const expectedBranch = resolveResumeExpectedBranch(job, fields);
+    const baseBranch = resolveResumeBaseBranch(fields, options);
+    // Fail loud on a missing/empty prompt template BEFORE any worktree resolution
+    // or WIP-checkpoint commit — never spawn an empty-prompt worker.
+    const promptTemplate = resolveResumePromptTemplate(job, fields);
+    let worktreePath = await resolveExistingResumeWorktreePath(fields, expectedBranch, seams);
+    if (worktreePath === null) {
+        worktreePath = await recreateResumeWorktreeFromPushedBranch(job, expectedBranch, seams);
+    }
+    // Branch verification BEFORE any local mutation — never checkpoint/commit on
+    // the wrong branch.
+    await assertWorktreeOnBranch(seams.runCommand, worktreePath, expectedBranch);
+    await autoCheckpointDirtyState(worktreePath, seams);
+    const gitLog = await readResumeGitLog(worktreePath, baseBranch, seams);
+    const gitDiff = await readResumeGitDiff(worktreePath, baseBranch, seams);
+    const prompt = fillResumePromptPlaceholders(promptTemplate, gitLog, gitDiff);
+    return { worktreePath, branch: expectedBranch, prompt };
+}