@bridge_gpt/mcp-server 0.2.38 → 0.2.41

package/build/conduct-epic/lock.js

@@ -0,0 +1,302 @@
+/**
+ * Per-epic mutual exclusion for the mutating `conduct-epic` verbs (BAPI-803).
+ *
+ * `checkpoint set`, `spawn`, and `finish` all read-modify-write one JSON
+ * document. Two overlapping invocations — an operator running `checkpoint set`
+ * by hand while the loop ticks, a second `/conduct-epic` session started in
+ * another terminal — would otherwise interleave and lose one side's write. This
+ * file is the local backstop for that: one lock file beside the checkpoint,
+ * created with an exclusive `open(..., "wx")`, carrying the owner's identity.
+ *
+ * The design is COPIED from `executor/worktree-lock.ts` rather than imported.
+ * That module's ownership identity is a server-minted claim token for an
+ * `executor_jobs` row, which has no meaning here; conduct-epic's owner is a
+ * `(pid, host, acquired_at)` triple. Sharing the file would mean generalizing a
+ * lock that is load-bearing for a different subsystem.
+ *
+ * Four properties, each with a failure it exists to prevent:
+ *
+ *  - ATOMIC ACQUISITION. `open(..., "wx")` creates or fails `EEXIST` with no
+ *    observable window. An exists-then-write pair would reintroduce the race.
+ *  - FAIL CLOSED. A remote-host owner, a malformed payload, an unreadable file,
+ *    a foreign schema version, or an indeterminate liveness probe all REFUSE.
+ *    Refusing costs one invocation; guessing costs a lost checkpoint write.
+ *  - RECOVERY IS PROVEN, NOT ASSUMED. Only `ESRCH` on the current host proves a
+ *    dead owner, and even then the bytes are re-read and compared before removal
+ *    so a successor's lock cannot be deleted in the gap.
+ *  - RELEASE IS OWNERSHIP-CHECKED. `release()` removes the file only while the
+ *    persisted pid/host/acquired_at still match the handle it was granted.
+ *
+ * No credential, checkpoint content, or file payload is ever logged or returned.
+ */
+/** Lock metadata schema version; a foreign version fails closed. */
+export const CONDUCT_EPIC_LOCK_VERSION = 1;
+/**
+ * Hard bound on a lock file we are willing to parse. A lock is ~150 bytes;
+ * anything larger is not our metadata, and parsing it would let an unrelated
+ * file at that path drive this module's behavior.
+ */
+export const CONDUCT_EPIC_LOCK_MAX_CHARS = 4_096;
+/** How many times acquisition may recover a dead owner's lock and retry. */
+export const CONDUCT_EPIC_LOCK_MAX_ATTEMPTS = 3;
+function errorCode(err) {
+    const code = err?.code;
+    return typeof code === "string" ? code : undefined;
+}
+/**
+ * Parse lock metadata, or `null` when it is not a record this version
+ * understands. Bounded BEFORE parsing, and every field type-checked: a
+ * partially-written or foreign file must never be mistaken for a releasable lock.
+ */
+export function parseConductEpicLock(raw) {
+    if (typeof raw !== "string" || raw.length === 0 || raw.length > CONDUCT_EPIC_LOCK_MAX_CHARS) {
+        return null;
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const record = value;
+    const { version, owner_pid: ownerPid, host, acquired_at: acquiredAt } = record;
+    if (version !== CONDUCT_EPIC_LOCK_VERSION)
+        return null;
+    if (typeof ownerPid !== "number" || !Number.isInteger(ownerPid) || ownerPid <= 0)
+        return null;
+    if (typeof host !== "string" || host.length === 0)
+        return null;
+    if (typeof acquiredAt !== "string" || acquiredAt.length === 0)
+        return null;
+    return { version, owner_pid: ownerPid, host, acquired_at: acquiredAt };
+}
+/**
+ * Real liveness probe. `process.kill(pid, 0)` signals nothing and only reports
+ * reachability. Only an explicit `ESRCH` proves the owner is gone: `EPERM` means
+ * the process exists under another user, and an unrecognized failure means we do
+ * not know — both are ALIVE, so an uncertain probe can never authorize stealing
+ * a lock.
+ */
+export function isConductEpicLockOwnerAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return errorCode(err) !== "ESRCH";
+    }
+}
+/** Serialize ownership metadata. Only the four approved fields are written. */
+function serializeLock(request) {
+    const owner = {
+        version: CONDUCT_EPIC_LOCK_VERSION,
+        owner_pid: request.ownerPid,
+        host: request.host,
+        acquired_at: request.acquiredAt,
+    };
+    return JSON.stringify(owner);
+}
+/**
+ * Classify the lock at `lockPath` WITHOUT mutating it.
+ *
+ * `status` and `doctor` are read-only surfaces and use only this; the mutating
+ * verbs call it first so they can report a precise refusal reason before
+ * attempting acquisition.
+ */
+export async function inspectConductEpicLock(lockPath, request, seams = {}) {
+    const read = seams.readFile ?? defaultReadFile;
+    const isAlive = seams.isProcessAlive ?? isConductEpicLockOwnerAlive;
+    let raw;
+    try {
+        raw = await read(lockPath);
+    }
+    catch (err) {
+        if (errorCode(err) === "ENOENT")
+            return { kind: "missing" };
+        return { kind: "unknown", reason: "the lock file exists but could not be read" };
+    }
+    const owner = parseConductEpicLock(raw);
+    if (owner === null) {
+        return {
+            kind: "unknown",
+            reason: "the lock file is malformed, oversized, or written by an unsupported version",
+        };
+    }
+    if (owner.host !== request.host)
+        return { kind: "remote-host", owner };
+    if (owner.owner_pid === request.ownerPid)
+        return { kind: "owned", owner };
+    if (isAlive(owner.owner_pid))
+        return { kind: "live-foreign", owner };
+    return { kind: "dead-local", owner };
+}
+/* Real filesystem defaults, imported lazily so a test that injects every seam
+ * never loads `node:fs/promises` behavior it does not use. */
+async function defaultReadFile(filePath) {
+    const { readFile } = await import("node:fs/promises");
+    return readFile(filePath, "utf-8");
+}
+async function defaultWriteFileExclusive(filePath, data) {
+    const { open } = await import("node:fs/promises");
+    const handle = await open(filePath, "wx", 0o600);
+    try {
+        await handle.writeFile(data, "utf-8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function defaultRemoveFile(filePath) {
+    const { rm } = await import("node:fs/promises");
+    await rm(filePath, { force: true });
+}
+async function defaultMkdir(dirPath, options) {
+    const { mkdir } = await import("node:fs/promises");
+    return mkdir(dirPath, options);
+}
+/**
+ * Acquire the per-epic lock at `lockPath`.
+ *
+ * Returns an acquired handle, or a refusal naming the sanitized reason. A lock
+ * whose owning pid is provably gone ON THIS HOST is recovered — but only through
+ * a re-read-then-compare sequence, so recovery cannot delete a lock a successor
+ * wrote between our read and our unlink. Recovery and exclusive-create
+ * contention are together bounded to {@link CONDUCT_EPIC_LOCK_MAX_ATTEMPTS}.
+ */
+export async function acquireConductEpicLock(lockPath, request, seams = {}) {
+    const writeExclusive = seams.writeFileExclusive ?? defaultWriteFileExclusive;
+    const read = seams.readFile ?? defaultReadFile;
+    const remove = seams.removeFile ?? defaultRemoveFile;
+    const makeDir = seams.mkdir ?? defaultMkdir;
+    const isAlive = seams.isProcessAlive ?? isConductEpicLockOwnerAlive;
+    const refused = (reason, owner) => ({
+        acquired: false,
+        lockPath,
+        reason,
+        owner,
+    });
+    const { dirname } = await import("node:path");
+    try {
+        await makeDir(dirname(lockPath), { recursive: true });
+    }
+    catch {
+        // An existing directory is the normal case and `recursive: true` makes it a
+        // no-op. Any other failure surfaces below as a failed exclusive create,
+        // which refuses. Never proceed as though the lock were held by us.
+    }
+    const payload = serializeLock(request);
+    for (let attempt = 0; attempt < CONDUCT_EPIC_LOCK_MAX_ATTEMPTS; attempt += 1) {
+        try {
+            await writeExclusive(lockPath, payload);
+            const owner = parseConductEpicLock(payload);
+            // Unreachable in practice — we just serialized it — but typing the handle
+            // on a parsed record keeps the file the single source of truth for what a
+            // lock IS.
+            if (owner === null)
+                return refused("the lock payload could not be re-parsed", null);
+            return {
+                acquired: true,
+                lockPath,
+                owner,
+                release: () => releaseConductEpicLock(lockPath, owner, { readFile: read, removeFile: remove }),
+            };
+        }
+        catch (err) {
+            if (errorCode(err) !== "EEXIST") {
+                // Not contention: a permission problem, a read-only directory, a
+                // vanished parent. We do not hold the lock, so we do not proceed.
+                return refused("the lock file could not be created", null);
+            }
+        }
+        let raw;
+        try {
+            raw = await read(lockPath);
+        }
+        catch (err) {
+            // Released between our failed create and this read: retry the exclusive
+            // create. Anything else is unreadable state — fail closed.
+            if (errorCode(err) === "ENOENT")
+                continue;
+            return refused("the lock file exists but could not be read", null);
+        }
+        const owner = parseConductEpicLock(raw);
+        if (owner === null) {
+            return refused("the lock file is malformed, oversized, or written by an unsupported version", null);
+        }
+        if (owner.host !== request.host) {
+            return refused(`the lock is held by host ${owner.host}; liveness cannot be checked from here`, owner);
+        }
+        if (owner.owner_pid === request.ownerPid) {
+            // Our own lock from earlier in this same process. Adopt it rather than
+            // deadlocking against ourselves.
+            return {
+                acquired: true,
+                lockPath,
+                owner,
+                release: () => releaseConductEpicLock(lockPath, owner, { readFile: read, removeFile: remove }),
+            };
+        }
+        if (isAlive(owner.owner_pid)) {
+            return refused(`the lock is held by live process ${owner.owner_pid} on ${owner.host}`, owner);
+        }
+        // Dead owner. Recover only if the bytes we are about to delete are still the
+        // exact bytes we read and judged stale.
+        let confirmation;
+        try {
+            confirmation = await read(lockPath);
+        }
+        catch (err) {
+            if (errorCode(err) === "ENOENT")
+                continue;
+            return refused("the lock file exists but could not be re-read", null);
+        }
+        if (confirmation !== raw)
+            continue;
+        try {
+            await remove(lockPath);
+        }
+        catch {
+            return refused("a stale lock could not be removed", owner);
+        }
+    }
+    return refused(`the lock could not be acquired after ${CONDUCT_EPIC_LOCK_MAX_ATTEMPTS} attempts`, null);
+}
+/**
+ * Remove the lock only while `owner` is still exactly what the file records.
+ *
+ * Best-effort by design: a failed release leaves a lock whose pid is this
+ * (exiting) process, which the next acquisition recovers as stale. Throwing here
+ * would turn a cleanup hiccup into a command failure after the work succeeded.
+ */
+export async function releaseConductEpicLock(lockPath, owner, seams = {}) {
+    const read = seams.readFile ?? defaultReadFile;
+    const remove = seams.removeFile ?? defaultRemoveFile;
+    let raw;
+    try {
+        raw = await read(lockPath);
+    }
+    catch {
+        return;
+    }
+    const current = parseConductEpicLock(raw);
+    if (current === null)
+        return;
+    if (current.owner_pid !== owner.owner_pid ||
+        current.host !== owner.host ||
+        current.acquired_at !== owner.acquired_at) {
+        // A successor replaced our lock. Removing it here is exactly the bug the
+        // ownership check exists to prevent.
+        return;
+    }
+    try {
+        await remove(lockPath);
+    }
+    catch {
+        /* best-effort */
+    }
+}

package/build/conduct-epic/pr-state.js

@@ -0,0 +1,286 @@
+/**
+ * `gh`-backed PR state parsing and ticket branch/worktree discovery (BAPI-803).
+ *
+ * Two jobs, both deliberately kept out of the frozen v1 runtime:
+ *
+ * **PR state.** The conduct-epic loop must SEE a `MERGED` or `CLOSED` PR — that
+ * is how it detects an externally merged ticket and stops re-driving it.
+ * `conductor/epic-runtime.ts#parsePrBindingFromGhJson` fails closed on any
+ * non-`OPEN` state, which is correct for binding a merge action and exactly
+ * wrong here, and importing it would pull the whole v1 runtime along. So this
+ * module parses `gh` PR records with a different, terminal-state-preserving
+ * contract, while REUSING the shared mergeability normalizer so a conflict is
+ * classified identically everywhere.
+ *
+ * The probe reads `gh pr list --head <branch>`, whose output is an ARRAY, and
+ * selects one record from it. `gh pr view` was replaced because it cannot
+ * express "no pull request" as anything but a non-zero exit (BAPI-825/B1).
+ *
+ * **Worktree discovery.** `/review-and-start` names branches
+ * `feature/<KEY>-<slug>` and the loop cannot know the slug. When
+ * `ticket.branch` is null, `status` and `spawn` scan `git worktree list
+ * --porcelain` and match by precedence: the stored branch, then exactly
+ * `feature/<KEY>`, then a branch beginning `feature/<KEY>-`. The `-` is required
+ * so `feature/BAPI-8010` never matches ticket `BAPI-801`.
+ *
+ * Every probe is NON-THROWING and returns a sanitized reason. Raw `gh`/`git`
+ * stdout and stderr never reach a result, a log line, or an error message.
+ */
+import { isPrMergeConflict, parseGhPrMergeabilityFields } from "../conductor/github-mergeability.js";
+import { runGhCommand } from "../conductor/pr-discovery.js";
+/**
+ * The `--json` field list the status contract fixes.
+ *
+ * Passed to `gh pr list` (BAPI-825/B1), which returns an ARRAY of records with
+ * exactly these keys. The name is retained because it is the published contract
+ * identifier and is asserted by name in the tests; only the subcommand changed.
+ */
+export const CONDUCT_EPIC_GH_PR_VIEW_FIELDS = "number,state,headRefOid,mergeable,mergeStateStatus,baseRefName,updatedAt";
+/**
+ * How many candidate pull requests the probe asks `gh` for.
+ *
+ * More than one, deliberately: a branch routinely carries a closed pull request
+ * plus a reopened one, and `--limit 1` would hand back whichever `gh` ordered
+ * first rather than letting {@link selectConductEpicPrState} prefer the OPEN
+ * one. Bounded so a branch with a long pull-request history cannot turn one
+ * probe into an unbounded read.
+ */
+export const CONDUCT_EPIC_GH_PR_LIST_LIMIT = 20;
+/** The accepted GitHub PR states. Terminal states are RETAINED, not filtered. */
+export const CONDUCT_EPIC_PR_STATES = ["OPEN", "MERGED", "CLOSED"];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A trimmed non-empty string, or `null` for every other shape. */
+function text(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? null : trimmed;
+}
+/**
+ * Normalize an already-parsed `gh pr view` record.
+ *
+ * Never throws and never partially fails: an unknown state, a non-numeric
+ * number, or a missing SHA each become `null` on their own field while the rest
+ * of the record survives. A PR whose `state` we cannot read is still worth
+ * reporting — its head SHA and mergeability are what the loop acts on.
+ */
+export function parseConductEpicPrState(value) {
+    if (!isRecord(value))
+        return null;
+    const rawNumber = value.number;
+    const number = typeof rawNumber === "number" && Number.isInteger(rawNumber) && rawNumber > 0 ? rawNumber : null;
+    const rawState = text(value.state);
+    const upper = rawState === null ? null : rawState.toUpperCase();
+    const state = CONDUCT_EPIC_PR_STATES.includes(upper ?? "")
+        ? upper
+        : null;
+    const mergeability = parseGhPrMergeabilityFields(value);
+    return {
+        number,
+        state,
+        head_sha: text(value.headRefOid),
+        base: text(value.baseRefName),
+        mergeable: mergeability.mergeable,
+        merge_state: mergeability.mergeStateStatus,
+        updated_at: text(value.updatedAt),
+    };
+}
+/**
+ * True for the two authoritative GitHub conflict signals. Delegates to the
+ * shared predicate so PR discovery, the done gate, and this loop agree.
+ */
+export function conductEpicPrHasConflict(pr) {
+    return isPrMergeConflict({ mergeable: pr.mergeable, mergeStateStatus: pr.merge_state });
+}
+/**
+ * Choose the one pull request the loop acts on from `gh`'s candidate list.
+ *
+ * An OPEN pull request always wins: it is the only one any action row can
+ * advance, and a stale closed sibling must never displace it. Among terminal
+ * candidates the most recently updated wins, because that is the one whose
+ * MERGED or CLOSED state describes the branch's current reality.
+ *
+ * Deterministic when timestamps tie or are unavailable: a valid `updated_at`
+ * outranks an absent one, and source order breaks any remaining tie. A probe
+ * that returned a different pull request run-to-run for identical input would
+ * make every downstream row unreproducible.
+ */
+export function selectConductEpicPrState(candidates) {
+    if (candidates.length === 0)
+        return null;
+    const open = candidates.find((pr) => pr.state === "OPEN");
+    if (open)
+        return open;
+    let best = candidates[0];
+    for (const candidate of candidates.slice(1)) {
+        const bestAt = Date.parse(best.updated_at ?? "");
+        const candidateAt = Date.parse(candidate.updated_at ?? "");
+        const bestUsable = Number.isFinite(bestAt);
+        const candidateUsable = Number.isFinite(candidateAt);
+        // Strictly greater, so an equal timestamp keeps the earlier record and
+        // source order remains the final tie-breaker.
+        if (candidateUsable && (!bestUsable || candidateAt > bestAt))
+            best = candidate;
+    }
+    return best;
+}
+/**
+ * Run `gh pr list --head <branch> --state all --json …` and normalize the result.
+ *
+ * Nothing throws. The three outcomes are kept strictly apart:
+ *
+ * - **`ok`** — `gh` succeeded and returned at least one parseable PR record.
+ * - **`none`** — `gh` SUCCEEDED and returned an empty array. Confirmed absence.
+ * - **`error`** — `gh` could not be run, exited non-zero, or returned output
+ *   that is not a valid PR array. Unavailable evidence, not absence.
+ *
+ * **`gh pr list`, not `gh pr view` (BAPI-825/B1).** `gh pr view <branch>` prints
+ * `no pull requests found for branch "…"` to stderr and **exits 1** when the
+ * branch has no pull request, and `runGhCommand` discards stderr, so every
+ * pre-PR tick produced `{ok: false, stdout: ""}`. Under BAPI-814/B2's correct
+ * rule that a non-zero exit is a failed probe, `none` became unreachable in
+ * production: the loop saw `pr: null` PLUS a `probe_errors` entry on every tick
+ * before a worker opened its pull request, so the "no PR yet" rows could never
+ * fire and a worker that died early parked at the three-hour hard deadline
+ * instead of getting its one-hour respawn. `gh pr list` exits 0 with `[]`,
+ * which makes absence expressible without weakening the failure rule.
+ *
+ * Every `error` reason is a fixed bounded string chosen here. The raw output is
+ * never included — a `gh` failure message can echo a URL, a token hint, or the
+ * repository layout, none of which belongs in a status object the loop prints.
+ */
+export async function discoverConductEpicPrState(branch, options = {}) {
+    const runGh = options.runGh ?? runGhCommand;
+    let result;
+    try {
+        result = await runGh([
+            "pr",
+            "list",
+            "--head",
+            branch,
+            "--state",
+            "all",
+            "--json",
+            CONDUCT_EPIC_GH_PR_VIEW_FIELDS,
+            "--limit",
+            String(CONDUCT_EPIC_GH_PR_LIST_LIMIT),
+        ], { cwd: options.cwd });
+    }
+    catch {
+        return { kind: "error", reason: "the gh command could not be run" };
+    }
+    // A non-zero `gh` exit is a FAILED PROBE, never "no PR" (BAPI-814/B2).
+    //
+    // `gh pr list` exits non-zero only when it could not answer — unauthenticated,
+    // rate-limited, offline, not a repository. Absence is now expressed as a
+    // successful `[]`, so nothing legitimate is lost by keeping this strict: the
+    // status contract turns an error into `pr: null` PLUS a `probe_errors` entry,
+    // which the command treats as unavailable evidence rather than a negative
+    // result.
+    //
+    // The reason is a FIXED string. `gh`'s own output can echo a URL, a token
+    // hint, or the repository layout, so none of it is interpolated here.
+    if (!result.ok)
+        return { kind: "error", reason: "the gh command failed" };
+    // Empty stdout from a SUCCESSFUL `--json` run is malformed, not absence: the
+    // documented answer for "no pull requests" is the two bytes `[]`. Silence is
+    // a shape this command should never produce, and reading it as a confirmed
+    // negative is precisely the inference this module refuses to make.
+    const raw = typeof result.stdout === "string" ? result.stdout.trim() : "";
+    if (raw.length === 0) {
+        return { kind: "error", reason: "gh returned no output for a --json query" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "error", reason: "gh returned output that is not valid JSON" };
+    }
+    if (!Array.isArray(parsed)) {
+        return { kind: "error", reason: "gh returned a PR list in an unexpected shape" };
+    }
+    // A successful, well-formed empty list is the ONLY confirmed absence.
+    if (parsed.length === 0)
+        return { kind: "none" };
+    const records = [];
+    for (const entry of parsed) {
+        const pr = parseConductEpicPrState(entry);
+        // An unusable record is a shape error, never silently dropped: discarding
+        // it could empty the list and turn a real pull request into "no PR".
+        if (pr === null) {
+            return { kind: "error", reason: "gh returned a PR record in an unexpected shape" };
+        }
+        records.push(pr);
+    }
+    const pr = selectConductEpicPrState(records);
+    if (pr === null)
+        return { kind: "error", reason: "gh returned a PR record in an unexpected shape" };
+    return { kind: "ok", pr };
+}
+/**
+ * Parse `git worktree list --porcelain` into branch-attached entries.
+ *
+ * Detached worktrees and records without a resolvable `refs/heads/<name>` are
+ * dropped: a worktree with no branch cannot be the ticket's worktree, and
+ * carrying it forward would only make the precedence rules below ambiguous.
+ */
+export function parseGitWorktreePorcelain(output) {
+    const entries = [];
+    let currentPath = null;
+    let currentBranch = null;
+    const flush = () => {
+        if (currentPath !== null && currentBranch !== null) {
+            entries.push({ path: currentPath, branch: currentBranch });
+        }
+        currentPath = null;
+        currentBranch = null;
+    };
+    for (const rawLine of String(output ?? "").split("\n")) {
+        const line = rawLine.replace(/\r$/, "");
+        if (line.startsWith("worktree ")) {
+            flush();
+            const value = line.slice("worktree ".length).trim();
+            currentPath = value.length > 0 ? value : null;
+        }
+        else if (line.startsWith("branch ") && currentPath !== null) {
+            const ref = line.slice("branch ".length).trim();
+            if (ref.startsWith("refs/heads/")) {
+                const name = ref.slice("refs/heads/".length);
+                currentBranch = name.length > 0 ? name : null;
+            }
+        }
+    }
+    flush();
+    return entries;
+}
+/**
+ * Resolve the worktree for `ticketKey`, in strict precedence order:
+ *
+ *  1. the branch already stored on the ticket;
+ *  2. exactly `feature/<KEY>`;
+ *  3. the first branch beginning `feature/<KEY>-` in porcelain order.
+ *
+ * The later rules are a FALLBACK, not an alternative: a stored branch whose
+ * worktree was removed still resolves through the naming convention, which is
+ * what lets the loop survive an operator pruning worktrees mid-run.
+ *
+ * Returns `null` rather than guessing. Persisting a discovered branch is the
+ * CALLER's decision — `status` may write it, and a pure resolver that also wrote
+ * to the checkpoint would make the read-only surface a mutating one.
+ */
+export function discoverTicketWorktree(entries, ticketKey, storedBranch) {
+    if (storedBranch !== null && storedBranch.length > 0) {
+        const stored = entries.find((entry) => entry.branch === storedBranch);
+        if (stored)
+            return { branch: stored.branch, path: stored.path };
+    }
+    const canonical = `feature/${ticketKey}`;
+    const exact = entries.find((entry) => entry.branch === canonical);
+    if (exact)
+        return { branch: exact.branch, path: exact.path };
+    const prefixed = entries.find((entry) => entry.branch.startsWith(`${canonical}-`));
+    return prefixed ? { branch: prefixed.branch, path: prefixed.path } : null;
+}

package/build/conduct-epic/spawn.js

@@ -0,0 +1,101 @@
+/**
+ * Secret-free agent-tab spawning for `conduct-epic spawn` (BAPI-803).
+ *
+ * `spawn` opens exactly ONE terminal tab in a ticket's worktree running the
+ * agent against a prompt the CALLER wrote to a file. The prompt is arbitrary
+ * operator/loop-authored text — it can contain apostrophes, `$(…)`, backticks,
+ * and newlines — so it is placed inside a single-quoted shell literal using the
+ * repository's existing quoting helpers rather than any local escaping. Reusing
+ * `shSquoteInner` / `powershellSquote` is the point: a second escaping
+ * implementation is a second place for a quoting bug to produce shell execution.
+ *
+ * Two invariants this module is responsible for:
+ *
+ * - **Exactly one tab, and only after every check passes.** The spawn seam is
+ *   invoked once, at the end, after the agent is validated and the command is
+ *   built. A partial failure must leave no tab, because the caller increments
+ *   `sessions_spawned` on success and a phantom tab would desynchronize it.
+ * - **No credential reaches the command.** Nothing here resolves, receives, or
+ *   formats Bridge access data. The spawned agent resolves its own credentials
+ *   from the user-scoped store, exactly as `start-tickets` workers do; a key in
+ *   argv would be visible to every process on the machine via `ps`.
+ */
+import { powershellSquote, shSquoteInner, } from "../start-tickets.js";
+/** The agents `conduct-epic spawn` may launch. */
+export const CONDUCT_EPIC_AGENTS = ["claude", "cursor-agent"];
+/** The repository's established default agent. */
+export const CONDUCT_EPIC_DEFAULT_AGENT = "claude";
+/**
+ * Validate an agent value, defaulting to {@link CONDUCT_EPIC_DEFAULT_AGENT}.
+ *
+ * Rejects before any command is built. The agent name becomes the executable in
+ * a shell command, so an unvalidated value is a command-injection surface even
+ * though the surrounding operands are quoted.
+ */
+export function resolveConductEpicAgent(agent) {
+    if (agent === undefined || agent.trim().length === 0) {
+        return { ok: true, agent: CONDUCT_EPIC_DEFAULT_AGENT };
+    }
+    const trimmed = agent.trim();
+    if (!CONDUCT_EPIC_AGENTS.includes(trimmed)) {
+        return {
+            ok: false,
+            error: `Unsupported agent '${trimmed}'. Expected one of: ${CONDUCT_EPIC_AGENTS.join(", ")}`,
+        };
+    }
+    return { ok: true, agent: trimmed };
+}
+/**
+ * Build `cd '<worktree>' && <agent> '<prompt>'` (POSIX) or the PowerShell
+ * equivalent, with both operands quoted by the shared helpers.
+ *
+ * Returns the command as a string rather than an argv array because that is what
+ * every terminal spawner in this repository consumes — a tab is opened by handing
+ * a shell a command line, not by `exec`ing a process.
+ */
+export function buildConductEpicAgentCommand(input) {
+    const resolved = resolveConductEpicAgent(input.agent);
+    if (!resolved.ok)
+        return resolved;
+    if (input.worktreePath.trim().length === 0) {
+        return { ok: false, error: "A worktree path is required to build the agent command." };
+    }
+    if (input.platform === "win32") {
+        return {
+            ok: true,
+            command: `Set-Location -LiteralPath ${powershellSquote(input.worktreePath)}; ` +
+                `${resolved.agent} ${powershellSquote(input.prompt)}`,
+        };
+    }
+    return {
+        ok: true,
+        command: `cd '${shSquoteInner(input.worktreePath)}' && ` +
+            `${resolved.agent} '${shSquoteInner(input.prompt)}'`,
+    };
+}
+/**
+ * Build the command and open exactly one tab through `spawnTab`.
+ *
+ * The seam is invoked once and only after construction succeeds. A spawner
+ * failure is returned as `{ ok: false }` with the spawner's own sanitized
+ * message — never the command, which embeds the full prompt text.
+ */
+export async function spawnConductEpicAgentTab(input, spawnTab) {
+    const built = buildConductEpicAgentCommand(input);
+    if (!built.ok)
+        return built;
+    let result;
+    try {
+        result = await spawnTab(built.command, {
+            key: input.ticketKey,
+            worktreePath: input.worktreePath,
+            title: `conduct-epic ${input.ticketKey}`,
+        });
+    }
+    catch {
+        return { ok: false, error: "The terminal tab could not be opened." };
+    }
+    if (!result.ok)
+        return { ok: false, error: result.error };
+    return { ok: true, command: built.command };
+}