@bridge_gpt/mcp-server 0.2.18 → 0.2.19

package/build/executor/test-clock.js

@@ -0,0 +1,109 @@
+export class VirtualClock {
+    t = 0;
+    timers = [];
+    id = 0;
+    now = () => this.t;
+    setTimer = (cb, ms) => {
+        const id = ++this.id;
+        this.timers.push({ at: this.t + ms, cb, id });
+        return id;
+    };
+    clearTimer = (h) => {
+        this.timers = this.timers.filter((x) => x.id !== h);
+    };
+    sleep = (ms) => new Promise((res) => {
+        this.setTimer(() => res(), ms);
+    });
+    /** Fire timers in time order until `predicate()` holds or timers run out. */
+    async tickUntil(predicate, maxSteps = 5000) {
+        let steps = 0;
+        await flushMicrotasks();
+        while (!predicate() && this.timers.length > 0 && steps++ < maxSteps) {
+            this.timers.sort((a, b) => a.at - b.at);
+            const next = this.timers.shift();
+            this.t = next.at;
+            next.cb();
+            await flushMicrotasks();
+        }
+    }
+}
+async function flushMicrotasks() {
+    for (let i = 0; i < 12; i++)
+        await Promise.resolve();
+}
+/** A controllable fake owned process for `implement` spawn tests. */
+export function makeControllableProcess(stdout) {
+    let resolveWait;
+    const waitP = new Promise((r) => {
+        resolveWait = r;
+    });
+    const signals = [];
+    let done = false;
+    return {
+        proc: {
+            pid: 4242,
+            stdout: stdout ?? null,
+            stderr: null,
+            wait: () => waitP,
+            kill: (s) => {
+                signals.push(s);
+                if (!done) {
+                    done = true;
+                    resolveWait({ exitCode: null, signal: s });
+                }
+            },
+        },
+        resolve: (v) => {
+            done = true;
+            resolveWait(v);
+        },
+        signals,
+    };
+}
+/** Build a full fake `ExecutorDeps`, driven by a `VirtualClock`. */
+export function makeFakeExecutorDeps(clock, overrides = {}) {
+    const base = {
+        runCommand: async () => ({ stdout: "", stderr: "", exitCode: 0 }),
+        spawnProcess: () => {
+            throw new Error("spawnProcess not configured for this test");
+        },
+        readFile: async () => {
+            throw new Error("ENOENT");
+        },
+        writeFile: async () => { },
+        mkdir: async () => undefined,
+        stat: async () => ({ mode: 0o644 }),
+        statfs: async () => ({ bavail: 1_000_000, bsize: 4096 }),
+        sleep: clock.sleep,
+        now: clock.now,
+        setTimer: clock.setTimer,
+        clearTimer: clock.clearTimer,
+        env: {},
+        cwd: "/repo",
+        platform: "linux",
+        homedir: () => "/home/tester",
+        fetch: async () => ({ status: 204, text: async () => "" }),
+        log: () => { },
+        errorLog: () => { },
+    };
+    return { ...base, ...overrides };
+}
+/** Sensible default executor options for tests. */
+export function makeTestOptions(overrides = {}) {
+    return {
+        executorId: "exec-test",
+        repos: ["repo-a"],
+        repoName: "repo-a",
+        maxConcurrent: 2,
+        pollIntervalMs: 15000,
+        heartbeatIntervalMs: 60000,
+        deadmanMs: 120000,
+        termGraceMs: 10000,
+        once: true,
+        worktrunkBinary: "wt",
+        baseBranch: "main",
+        advisoryParserEnabled: false,
+        defaultJobTimeoutSeconds: 1200,
+        ...overrides,
+    };
+}

package/build/executor/types.js

@@ -0,0 +1,18 @@
+/**
+ * Epic Conductor v2 executor — core type/boundary definitions (BAPI-534, TDD §7).
+ *
+ * ARCHITECTURE BOUNDARY (TDD §12, Req 1): files under `mcp_server/src/executor/`
+ * are a dumb, pull-based local worker. They MUST NOT import from the v1
+ * conductor event/ledger graph — `conductor/store.ts`, `conductor/taxonomy.ts`,
+ * `conductor/event-accessors.ts`, `conductor/epic-runtime.ts`,
+ * `conductor/epic-reconcile.ts`, `conductor/epic-state.ts`, or any conductor
+ * producer / supervisor-runtime module. Allowed conductor reuse is limited to
+ * read-only / deterministic helpers — the deny-enforcement preflight
+ * (`conductor/deny-enforcement-preflight.ts`), and (BAPI-535 T3b) the local merge
+ * executor (`conductor/local-merge.ts`) plus the read-only Bridge API access +
+ * merge request/response types (`conductor/bridge-api-client.ts`) for the
+ * deterministic `merge` job.
+ * All subprocess / HTTP / filesystem / clock access is behind injected deps so
+ * every requirement is unit-testable on Linux CI with no real I/O.
+ */
+export {};

package/build/executor/verdict-artifact.js

@@ -0,0 +1,53 @@
+/**
+ * Fixed-path verdict-artifact reading (BAPI-535, TDD §9).
+ *
+ * For verdict job types (`spec_review`, `smoke`) the executor reads exactly
+ * `<worktree>/.conductor/result.json` after the worker exits and posts the parsed
+ * object VERBATIM at `/complete`. A missing/unreadable/invalid artifact is a
+ * fail-loud named failure ({@link MissingVerdictArtifact}) — "a verdict can never
+ * be silently absent". The executor performs NO markdown parsing, NO verdict
+ * judgment, and NO schema-specific interpretation; per-`job_type` schema
+ * validation is server-owned at `/complete` (T2/T6).
+ */
+import { MissingVerdictArtifact, ExecutorNamedError } from "./job-errors.js";
+import { pathApiForExecutorPlatform } from "./worktree-inspection.js";
+/** The fixed `.conductor` result directory (relative to the worktree). */
+export const CONDUCTOR_RESULT_DIR = ".conductor";
+/** The fixed verdict artifact filename. */
+export const CONDUCTOR_RESULT_FILE = "result.json";
+/** True only for verdict job types (`spec_review`, `smoke`). */
+export function isVerdictJobType(jobType) {
+    return jobType === "spec_review" || jobType === "smoke";
+}
+/** Join `<worktree>/.conductor/result.json` with platform-correct separators. */
+export function buildVerdictArtifactPath(worktreePath, platform = process.platform) {
+    const pathApi = pathApiForExecutorPlatform(platform);
+    return pathApi.join(worktreePath, CONDUCTOR_RESULT_DIR, CONDUCTOR_RESULT_FILE);
+}
+/**
+ * Read and parse `<worktree>/.conductor/result.json`. Returns the parsed JSON
+ * OBJECT verbatim. Throws {@link ExecutorNamedError} kind
+ * {@link MissingVerdictArtifact} for a missing/unreadable file, invalid JSON, or
+ * a non-object top-level value (array, `null`, string, number, boolean).
+ */
+export async function readVerdictArtifact(worktreePath, deps) {
+    const artifactPath = buildVerdictArtifactPath(worktreePath, deps.platform ?? process.platform);
+    let raw;
+    try {
+        raw = await deps.readFile(artifactPath);
+    }
+    catch {
+        throw new ExecutorNamedError(MissingVerdictArtifact, `verdict artifact missing or unreadable at ${CONDUCTOR_RESULT_DIR}/${CONDUCTOR_RESULT_FILE}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ExecutorNamedError(MissingVerdictArtifact, `verdict artifact ${CONDUCTOR_RESULT_DIR}/${CONDUCTOR_RESULT_FILE} is not valid JSON`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ExecutorNamedError(MissingVerdictArtifact, `verdict artifact ${CONDUCTOR_RESULT_DIR}/${CONDUCTOR_RESULT_FILE} must be a JSON object`);
+    }
+    return parsed;
+}

package/build/executor/viewer-tabs.js

@@ -0,0 +1,78 @@
+/**
+ * Optional read-only viewer tabs (BAPI-535, TDD §8, G5).
+ *
+ * Opens a NON-OWNING terminal tab that runs `tail -f` against a job's worker log,
+ * visually identical to the v1 per-ticket tabs but strictly read-only: closing
+ * the tab kills nothing, and nothing typed into it affects the job. The tab
+ * command is ALWAYS `tail -f <log>` — never `claude`, Worktrunk, or any
+ * worker-owning process — so the viewing surface is fully decoupled from the
+ * execution surface. Failures are non-fatal: opening a viewer never throws,
+ * never kills the worker, and never changes completion/failure reporting.
+ */
+import { getDefaultSpawnTerminalTabForPlatform, } from "../start-tickets.js";
+/** Env var that force-enables/disables viewer tabs regardless of platform. */
+export const EXECUTOR_VIEWER_TABS_ENV = "BAPI_EXECUTOR_VIEWER_TABS";
+const TRUE_TOKENS = new Set(["1", "true", "on"]);
+const FALSE_TOKENS = new Set(["0", "false", "off"]);
+/**
+ * Whether viewer tabs are enabled: default ON for `darwin`, OFF elsewhere, with
+ * `BAPI_EXECUTOR_VIEWER_TABS=1|true|on` / `0|false|off` overriding either way.
+ */
+export function executorViewerTabsEnabled(platform, env) {
+    const raw = env[EXECUTOR_VIEWER_TABS_ENV];
+    if (typeof raw === "string") {
+        const token = raw.trim().toLowerCase();
+        if (TRUE_TOKENS.has(token))
+            return true;
+        if (FALSE_TOKENS.has(token))
+            return false;
+    }
+    return platform === "darwin";
+}
+/** Single-quote a path for safe embedding in a POSIX shell command. */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Build the read-only tail-follow shell command. The executable action is always
+ * exactly `tail -f <worker-log-path>` — it can never own the worker process.
+ */
+export function buildTailFollowCommand(workerLogPath) {
+    return `tail -f ${shellQuote(workerLogPath)}`;
+}
+/**
+ * Open a read-only viewer tab tailing the worker log. Returns a `skipped` result
+ * when viewer tabs are disabled and a `failed` result (never a throw) when the
+ * spawn boundary reports/raises a failure — the worker lifecycle is untouched.
+ */
+export async function openExecutorViewerTab(options) {
+    if (!executorViewerTabsEnabled(options.platform, options.env)) {
+        return { status: "skipped", reason: "viewer tabs disabled for this platform/config" };
+    }
+    const command = buildTailFollowCommand(options.workerLogPath);
+    const spawnTab = options.spawnTab ?? getDefaultSpawnTerminalTabForPlatform(options.platform);
+    const terminal = options.terminal ?? "terminal";
+    // A minimal StartTicketsDeps for the shared spawner; `spawnTerminalTab` is
+    // self-referential (only used by higher-level orchestration, not the leaf
+    // spawner) and never spawns a worker here.
+    const startTicketsDeps = {
+        runCommand: options.runCommand,
+        platform: options.platform,
+        env: options.env,
+        cwd: options.cwd,
+        spawnTerminalTab: spawnTab,
+    };
+    try {
+        const result = await spawnTab(startTicketsDeps, terminal, command, {
+            key: options.ticketKey ?? "",
+            worktreePath: options.worktreePath,
+        });
+        if (result.ok)
+            return { status: "opened" };
+        return { status: "failed", reason: result.error };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { status: "failed", reason: reason.slice(0, 200) };
+    }
+}

package/build/executor/watch-cli.js

@@ -0,0 +1,113 @@
+/**
+ * `executor watch <job>` subcommand (BAPI-535, TDD §8).
+ *
+ * Ad-hoc, READ-ONLY attachment to a running (or recently-run) job's worker log:
+ * it resolves the local job-log registry record, verifies the log file exists,
+ * and `tail -f`s it with inherited stdio. It NEVER sends a signal to the worker
+ * process and never owns the execution lifecycle — closing the watch leaves the
+ * worker untouched. Missing registry records or missing log files fail loud with
+ * actionable stderr text and a non-zero exit code.
+ */
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import os from "node:os";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { readExecutorJobLogRecord, } from "./job-log-registry.js";
+export function getExecutorWatchUsage() {
+    return [
+        "Usage: mcp-server executor watch <job-id>",
+        "",
+        "Attach read-only to a running (or recently-run) executor job's worker log",
+        "via `tail -f`. Closing the watch never affects the worker process.",
+        "",
+        "Arguments:",
+        "  <job-id>        Numeric executor job id to watch.",
+        "",
+        "Options:",
+        "  -h, --help      Show this help.",
+    ].join("\n");
+}
+/** Accept EXACTLY one numeric job id; reject missing/non-numeric/extra args. */
+export function parseExecutorWatchArgs(argv) {
+    const positionals = [];
+    for (const arg of argv) {
+        if (arg === "-h" || arg === "--help")
+            return { kind: "help" };
+        if (arg.startsWith("-"))
+            return { kind: "error", message: `unknown argument: ${arg}` };
+        positionals.push(arg);
+    }
+    if (positionals.length === 0) {
+        return { kind: "error", message: "a numeric <job-id> is required" };
+    }
+    if (positionals.length > 1) {
+        return { kind: "error", message: "exactly one <job-id> is accepted" };
+    }
+    const raw = positionals[0];
+    if (!/^[0-9]+$/.test(raw)) {
+        return { kind: "error", message: `job id must be numeric: '${raw}'` };
+    }
+    return { kind: "ok", jobId: Number(raw) };
+}
+/**
+ * Spawn `tail -f <log_path>` with inherited stdio for interactive CLI attachment.
+ * Resolves with the tail process's numeric exit code. NEVER signals the worker.
+ */
+export function spawnTailFollow(logPath, spawnImpl = spawn) {
+    return new Promise((resolve) => {
+        const child = spawnImpl("tail", ["-f", logPath], { stdio: "inherit" });
+        child.on("close", (code) => resolve(code ?? 0));
+        child.on("error", () => resolve(1));
+    });
+}
+/** Build the default (production) registry deps from real fs/env/os boundaries. */
+export function createDefaultWatchRegistryDeps() {
+    return {
+        readFile: (p) => readFile(p, "utf-8"),
+        writeFile: (p, data) => writeFile(p, data, "utf-8"),
+        mkdir: (p, opts) => mkdir(p, opts),
+        env: process.env,
+        tmpdir: () => os.tmpdir(),
+        platform: process.platform,
+    };
+}
+async function defaultLogExists(logPath) {
+    try {
+        await access(logPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the job-log record and attach read-only via `tail -f`. Returns a
+ * numeric exit code: `0` on a clean tail exit, non-zero on a missing registry
+ * record or missing log file (with actionable stderr).
+ */
+export async function runExecutorWatchCli(argv, overrides = {}) {
+    const errorLog = overrides.errorLog ?? ((m) => console.error(m));
+    const parsed = parseExecutorWatchArgs(argv);
+    if (parsed.kind === "help") {
+        errorLog(getExecutorWatchUsage());
+        return 0;
+    }
+    if (parsed.kind === "error") {
+        errorLog(`Error: ${parsed.message}\n\n${getExecutorWatchUsage()}`);
+        return 1;
+    }
+    const registryDeps = overrides.registryDeps ?? createDefaultWatchRegistryDeps();
+    const readRecord = overrides.readRecord ?? readExecutorJobLogRecord;
+    const record = await readRecord(parsed.jobId, registryDeps);
+    if (!record.ok) {
+        errorLog(`Error: no worker log registered for job ${parsed.jobId}: ${record.reason}`);
+        return 1;
+    }
+    const logExists = overrides.logExists ?? defaultLogExists;
+    if (!(await logExists(record.record.log_path))) {
+        errorLog(`Error: worker log for job ${parsed.jobId} is missing at ${record.record.log_path}`);
+        return 1;
+    }
+    const spawnTail = overrides.spawnTail ?? ((logPath) => spawnTailFollow(logPath));
+    return spawnTail(record.record.log_path);
+}

package/build/executor/worker-command.js

@@ -0,0 +1,106 @@
+/**
+ * Headless Claude worker command construction (BAPI-534, TDD §7).
+ *
+ * Resolves the exact argv, model alias, and prompt for a spawned worker. Model
+ * aliases resolve through the agent registry (never a raw untrusted string); no
+ * MCP config is ever added. When no safe alias is available, `--model` is omitted.
+ */
+import { resolveAgentSpec, resolveModelAlias, isModelTier, isValidModelAlias, } from "../agent-registry.js";
+import { isRecoveryJobType } from "./job-types.js";
+/**
+ * Resolve the Claude model alias from a job payload. Accepts a direct
+ * `model_alias` only when it passes registry alias validation AND the static
+ * Claude allowlist; otherwise resolves from a valid `model_tier` through the
+ * registry. Returns `null` when no safe alias is available (so `--model` is
+ * omitted) — an unsafe/invalid string is never returned.
+ */
+export function resolveExecutorModelAlias(payload) {
+    const agent = resolveAgentSpec("claude");
+    if (!agent)
+        return null;
+    const p = payload && typeof payload === "object" ? payload : {};
+    const directRaw = p.model_alias;
+    if (typeof directRaw === "string" && directRaw.trim().length > 0) {
+        const direct = directRaw.trim();
+        const allowed = !agent.staticModelAliasAllowlist || agent.staticModelAliasAllowlist.includes(direct);
+        if (isValidModelAlias(direct) && allowed) {
+            return direct;
+        }
+        // An invalid/disallowed direct alias falls through to the tier path — never
+        // returned as-is.
+    }
+    const tier = isModelTier(p.model_tier) ? p.model_tier : null;
+    return resolveModelAlias(agent, tier, null);
+}
+/**
+ * Resolve the worker prompt for the explicit-prompt and legacy synthesis paths.
+ * Uses an explicit non-empty `payload.prompt` verbatim; otherwise, for
+ * `implement` and the recovery jobs, builds the conservative
+ * `/implement-ticket <ticket_key> --auto` prompt.
+ *
+ * Structured `payload.prompt_spec` rendering (the `spec_review` path) is NOT done
+ * here: it needs the prepared worktree/git state, so `job-runner.ts` renders it
+ * in the prepared-spawn path AFTER worktree preparation. `spec_review` therefore
+ * returns `ok:false` from this function by design — that non-ok result is the
+ * signal for the runner to fall through to prompt-spec rendering, not a terminal
+ * failure. A real spawn job with neither an explicit prompt, a synthesis path,
+ * nor a `prompt_spec` is the genuine contract failure.
+ */
+/**
+ * True for the job types that synthesize `/implement-ticket <KEY> --auto` when no
+ * explicit `payload.prompt` is present: the first-pass `implement` plus the
+ * recovery jobs (`remediate`/`ci_fix`/`rebase`), which re-enter the SAME
+ * correction loop on the ticket's existing branch/PR. Recovery classification is
+ * shared with dispatch and worktree reuse via `isRecoveryJobType` (`job-types.ts`)
+ * so eligibility cannot drift. Verdict jobs (`spec_review`/`smoke`) are NOT here —
+ * they carry an explicit `payload.prompt` and write a fixed-path artifact (T6/T5b).
+ */
+function synthesizesImplementPrompt(jobType) {
+    return jobType === "implement" || isRecoveryJobType(jobType);
+}
+export function resolveExecutorPrompt(job) {
+    const payload = job.payload && typeof job.payload === "object"
+        ? job.payload
+        : {};
+    // An explicit prompt wins and is returned VERBATIM (un-trimmed), but a
+    // whitespace-only string is not a usable worker instruction — treat it as
+    // absent so a recovery/implement job still falls back to the synthesized
+    // `/implement-ticket <KEY> --auto` correction prompt below.
+    const explicit = payload.prompt;
+    if (typeof explicit === "string" && explicit.trim().length > 0) {
+        return { ok: true, prompt: explicit };
+    }
+    // `/implement-ticket <KEY> --auto` is the full correction engine, not just a
+    // first-pass implementer: its post-PR loop owns CI-failure correction, review-
+    // change addressing, and merge-conflict resolution (see .claude/commands/
+    // implement-ticket.md "Clean session exit"). So the recovery jobs that operate
+    // on the ticket's existing branch/PR — `remediate`/`ci_fix`/`rebase` — resume
+    // through the same command, which detects the outstanding CI/review/conflict
+    // state and continues rather than restarting. Without this, a code_review
+    // `changes_requested` (near-certain in real runs) enqueues a `remediate` job
+    // that fails `no usable prompt` and strands the run (BAPI-528 Milestone-A gap #3).
+    const ticketKey = typeof job.ticket_key === "string" && job.ticket_key.trim().length > 0
+        ? job.ticket_key.trim()
+        : null;
+    if (synthesizesImplementPrompt(job.job_type) && ticketKey) {
+        return { ok: true, prompt: `/implement-ticket ${ticketKey} --auto` };
+    }
+    return {
+        ok: false,
+        error: `no usable prompt for job_type '${job.job_type}' (no payload.prompt and no ticket_key)`,
+    };
+}
+/**
+ * Build the exact headless Claude argv. `--model <alias>` is included only when
+ * an alias is provided. No MCP config arguments are ever emitted.
+ */
+export function buildClaudeExecutorArgv(prompt, alias) {
+    const argv = ["-p", prompt, "--output-format", "stream-json", "--verbose"];
+    if (alias) {
+        argv.push("--model", alias);
+    }
+    argv.push("--dangerously-skip-permissions");
+    return argv;
+}
+/** The worker executable is always exactly `claude`. */
+export const CLAUDE_EXECUTABLE = "claude";

package/build/executor/worker-finalization.js

@@ -0,0 +1,97 @@
+/**
+ * Fail-loud worker-finalization check (BAPI-551).
+ *
+ * An implementation-style worker (`implement`/`resume`/`remediate`/`ci_fix`/
+ * `rebase`) can exit cleanly yet strand its work if its push never landed on
+ * origin and no PR was opened — e.g. the worker backgrounds a slow push (the
+ * advisory pre-push suite) and returns before it completes. Without this check
+ * the executor still reports `clean_exit`/`succeeded`, and the gap is only ever
+ * caught by the reconciler's 3h watchdog. `validateWorkerFinalization` converts
+ * that condition into an explicit executor failure instead, using a local
+ * `git ls-remote` check (no Bridge API credentials, no conductor identity).
+ *
+ * For `resume`/`remediate`/`ci_fix`/`rebase`, the branch is fetched from origin
+ * BEFORE the worker starts (worktree.ts's recovery reuse path, resume-pre-spawn's
+ * "recreate ONLY from the pushed branch" path) — so the ref existing on origin is
+ * not proof THIS session's commit landed; a stale pre-existing branch would pass
+ * an existence-only check. The check instead compares the origin branch's tip SHA
+ * against the worker's own HEAD commit (`headSha`, from git telemetry) whenever
+ * that comparison is available.
+ */
+import { secretFreeErrorMessage, WorkerFinalizationMissingRemoteBranchAndPr } from "./job-errors.js";
+import { isImplementationStyleJobType } from "./job-types.js";
+function extractPrUrl(result) {
+    const raw = result.pr_url;
+    return typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : undefined;
+}
+/** Normalize to exactly one `refs/heads/` prefix — never `refs/heads/refs/heads/...`. */
+function normalizeBranchRef(branch) {
+    return branch.startsWith("refs/heads/") ? branch : `refs/heads/${branch}`;
+}
+/** Resolve the origin branch's current tip SHA, or `null` if the ref is absent. */
+async function resolveOriginBranchSha(runCommand, worktreePath, branch) {
+    const result = await runCommand("git", ["ls-remote", "--exit-code", "--heads", "origin", normalizeBranchRef(branch)], { cwd: worktreePath });
+    if (result.exitCode !== 0)
+        return null;
+    const sha = result.stdout.trim().split(/\s+/)[0];
+    return sha && sha.length > 0 ? sha : null;
+}
+function missingBranchAndPrFailure(job, detail) {
+    const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
+    return {
+        error_kind: WorkerFinalizationMissingRemoteBranchAndPr,
+        error_message: `${label} exited cleanly but ${detail}`,
+        classification: "crashed",
+    };
+}
+/**
+ * Validate that an implementation-style job's clean exit actually produced a PR
+ * or a pushed origin branch. Non-implementation-style jobs (verdict jobs) and
+ * any result carrying a non-empty `pr_url` bypass the git check entirely.
+ */
+export async function validateWorkerFinalization(input) {
+    const { job, branch, worktreePath, result, runCommand, headSha } = input;
+    if (!isImplementationStyleJobType(job.job_type)) {
+        return { ok: true };
+    }
+    if (extractPrUrl(result)) {
+        return { ok: true };
+    }
+    const trimmedBranch = typeof branch === "string" ? branch.trim() : "";
+    if (!trimmedBranch) {
+        return {
+            ok: false,
+            failure: missingBranchAndPrFailure(job, "produced no PR URL and no expected branch to verify on origin"),
+        };
+    }
+    let remoteSha;
+    try {
+        remoteSha = await resolveOriginBranchSha(runCommand, worktreePath, trimmedBranch);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            failure: missingBranchAndPrFailure(job, `produced no PR URL and branch '${trimmedBranch}' could not be verified on origin: ${secretFreeErrorMessage(err)}`),
+        };
+    }
+    if (remoteSha === null) {
+        return {
+            ok: false,
+            failure: missingBranchAndPrFailure(job, `produced no PR URL and branch '${trimmedBranch}' is not on origin`),
+        };
+    }
+    // Recovery/resume jobs fetch `origin/<branch>` before the worker even starts,
+    // so the ref merely existing is not proof this session's commit landed. When
+    // the worker's own HEAD is known, require the origin tip to match it exactly —
+    // a stale pre-existing branch (this session's push never happened) fails loud
+    // instead of passing. When HEAD is unresolved (degraded telemetry), fall back
+    // to the existence-only check rather than inventing a new failure mode.
+    const trimmedHeadSha = typeof headSha === "string" ? headSha.trim() : "";
+    if (trimmedHeadSha && remoteSha !== trimmedHeadSha) {
+        return {
+            ok: false,
+            failure: missingBranchAndPrFailure(job, `produced no PR URL and origin branch '${trimmedBranch}' is at ${remoteSha.slice(0, 12)}, which does not match this worker's HEAD ${trimmedHeadSha.slice(0, 12)} — the worker's commit was not pushed`),
+        };
+    }
+    return { ok: true };
+}

package/build/executor/worker-log.js

@@ -0,0 +1,92 @@
+/**
+ * Per-job worker log tee primitives (BAPI-535, TDD §8, G5).
+ *
+ * Every worker's output is teed to the fixed path `<worktree>/.conductor/worker.log`
+ * in human-readable form so `tail -f` reproduces the v1 tab experience on demand.
+ * The tee is PURELY a recorder: it never owns, signals, or kills the worker
+ * process — closing/finalizing the log affects the file only. All filesystem
+ * access is behind injected boundaries so this is unit-testable with no real I/O.
+ */
+import { pathApiForExecutorPlatform } from "./worktree-inspection.js";
+/** The fixed `.conductor` worker-log directory (relative to the worktree). */
+export const CONDUCTOR_WORKER_LOG_DIR = ".conductor";
+/** The fixed worker-log filename. */
+export const CONDUCTOR_WORKER_LOG_FILE = "worker.log";
+/** Resolve `<worktree>/.conductor/worker.log` with platform-correct separators. */
+export function buildWorkerLogPath(worktreePath, platform = process.platform) {
+    const pathApi = pathApiForExecutorPlatform(platform);
+    return pathApi.join(worktreePath, CONDUCTOR_WORKER_LOG_DIR, CONDUCTOR_WORKER_LOG_FILE);
+}
+/**
+ * Render one stdout/stderr chunk as human-readable log text. The worker's stream
+ * is already text; this passes it through WITHOUT JSON framing, process metadata,
+ * or secret-bearing envelope fields. `stream` is accepted for future labeling but
+ * the default rendering is a faithful passthrough so `tail -f` shows raw output.
+ */
+export function renderWorkerLogChunk(chunk, _stream = "stdout") {
+    return chunk;
+}
+/**
+ * Create the `.conductor` directory, initialize an empty `worker.log`, and return
+ * a tee handle. When an `appendFile` boundary is supplied, chunks are appended
+ * incrementally; otherwise a buffered fallback re-writes the accumulated content
+ * via `writeFile` so all consumed chunks are preserved in order.
+ */
+export async function createWorkerLogTee(worktreePath, deps) {
+    const platform = deps.platform ?? process.platform;
+    const pathApi = pathApiForExecutorPlatform(platform);
+    const dir = pathApi.join(worktreePath, CONDUCTOR_WORKER_LOG_DIR);
+    const logPath = pathApi.join(dir, CONDUCTOR_WORKER_LOG_FILE);
+    await deps.mkdir(dir, { recursive: true });
+    await deps.writeFile(logPath, "");
+    let buffer = "";
+    let closed = false;
+    return {
+        logPath,
+        async append(chunk) {
+            if (closed)
+                return;
+            try {
+                if (deps.appendFile) {
+                    await deps.appendFile(logPath, chunk);
+                }
+                else {
+                    buffer += chunk;
+                    await deps.writeFile(logPath, buffer);
+                }
+            }
+            catch {
+                /* the log tee is a visibility nicety — a write failure never fails a job */
+            }
+        },
+        async close() {
+            closed = true;
+        },
+    };
+}
+/**
+ * Wrap an `AsyncIterable<string>` so every consumed chunk is rendered and written
+ * to the worker log before being yielded to the existing runner logic. The
+ * original chunks pass through UNCHANGED, so downstream observation/classification
+ * is unaffected.
+ */
+export async function* teeAsyncIterable(source, tee, stream = "stdout") {
+    for await (const chunk of source) {
+        await tee.append(renderWorkerLogChunk(chunk, stream));
+        yield chunk;
+    }
+}
+/**
+ * Safely finalize a tee. Tolerates a `null`/`undefined` tee and repeated calls;
+ * NEVER kills or signals the worker process.
+ */
+export async function closeWorkerLogTee(tee) {
+    if (!tee)
+        return;
+    try {
+        await tee.close();
+    }
+    catch {
+        /* finalization is best-effort */
+    }
+}