@bridge_gpt/mcp-server 0.2.62 → 0.2.66

package/build/executor/job-log-registry.js

@@ -1,17 +1,34 @@
 /**
- * Local executor job-log registry (BAPI-535, TDD §8).
+ * Local executor job-log registry (BAPI-535, TDD §8; BAPI-1330).
  *
- * Persists a small, SECRET-FREE mapping from an executor job id to its worker-log
- * path so a SEPARATE CLI process (`executor watch <job>`) can attach read-only to
- * the log. Records carry only routing metadata (ids, repo, job type, paths,
- * timestamps) — never job payloads, API tokens, or auth material. All filesystem
- * / env access is injected so the registry is unit-testable with no real I/O.
+ * Persists a small, SECRET-FREE mapping from an executor job id to the worker-log
+ * file of EACH of its attempts, so a SEPARATE CLI process (`executor watch <job>`)
+ * can attach read-only to the right transcript. Records carry only routing
+ * metadata (ids, repo, job type, the stable attempt path, timestamps,
+ * availability) — never job payloads, API tokens, auth material, or transcript
+ * text. The paths stay LOCAL: nothing here is ever sent to the server. All
+ * filesystem / env access is injected so the registry is unit-testable with no
+ * real I/O.
+ *
+ * BAPI-1330 made the registry attempt-aware. One file per job holds a bounded
+ * list of attempt records keyed by the opaque per-claim identity; a later claim
+ * APPENDS rather than overwriting, the file is replaced atomically (temporary
+ * file + rename) under a per-job serialization, and a reader validates the
+ * record's job id, attempt, claim identity and stable filename before returning
+ * a pointer. A legacy record that names the retired fixed `worker.log` — whose
+ * contents may belong to any later attempt — is reported unavailable, never
+ * followed.
  */
+import { CONDUCTOR_WORKER_LOG_FILE, isValidWorkerLogAttemptIdentity, WORKER_LOG_ATTEMPT_FILE_RE, workerLogAttemptFileName, } from "./worker-log.js";
 import { pathApiForExecutorPlatform } from "./worktree-inspection.js";
 /** Default state-dir basename under the system temp dir. */
 const DEFAULT_STATE_DIR_NAME = "bridge-executor-job-logs";
 /** Env var that overrides the executor state directory. */
 export const EXECUTOR_STATE_DIR_ENV = "BAPI_EXECUTOR_STATE_DIR";
+/** The registry file format this module writes. Version 1 was the flat BAPI-535 record. */
+export const EXECUTOR_JOB_LOG_REGISTRY_VERSION = 2;
+/** Upper bound on retained attempt records per job; the oldest are dropped first. */
+export const MAX_REGISTERED_ATTEMPTS = 32;
 /**
  * Resolve the executor state directory: the `BAPI_EXECUTOR_STATE_DIR` override
  * when set, else a stable directory under the system temp dir (independent of
@@ -34,92 +51,269 @@ export function jobLogRecordPath(stateDir, jobId, platform = process.platform) {
     const safeId = String(jobId).replace(/[^0-9]/g, "") || "0";
     return pathApi.join(stateDir, `job-${safeId}.json`);
 }
-/** Whitelist the persisted fields so no extra (possibly secret) field leaks in. */
-function normalizeRecord(record) {
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/** Whitelist one attempt entry so no extra (possibly secret) field leaks in. */
+function normalizeAttempt(entry) {
     const out = {
-        job_id: record.job_id,
-        repo_name: record.repo_name,
-        job_type: record.job_type,
-        log_path: record.log_path,
-        started_at: record.started_at,
+        claim_id: entry.claim_id,
+        attempt: entry.attempt,
+        log_path: entry.log_path,
+        log_file: entry.log_file,
+        started_at: entry.started_at,
+        availability: entry.availability === "unavailable" ? "unavailable" : "available",
     };
-    if (record.ticket_key)
-        out.ticket_key = record.ticket_key;
-    if (record.worktree_path)
-        out.worktree_path = record.worktree_path;
-    if (record.finished_at)
-        out.finished_at = record.finished_at;
+    if (entry.finished_at)
+        out.finished_at = entry.finished_at;
+    if (out.availability === "unavailable" && isNonEmptyString(entry.unavailable_reason)) {
+        out.unavailable_reason = entry.unavailable_reason.slice(0, 64);
+    }
     return out;
 }
-function isValidRecord(value) {
-    if (!value || typeof value !== "object")
+function serialize(file) {
+    const out = {
+        version: EXECUTOR_JOB_LOG_REGISTRY_VERSION,
+        job_id: file.job_id,
+        repo_name: file.repo_name,
+        job_type: file.job_type,
+        attempts: file.attempts.slice(-MAX_REGISTERED_ATTEMPTS).map(normalizeAttempt),
+    };
+    if (file.ticket_key)
+        out.ticket_key = file.ticket_key;
+    if (file.worktree_path)
+        out.worktree_path = file.worktree_path;
+    return JSON.stringify(out, null, 2);
+}
+function isAttemptEntry(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
     const v = value;
-    return (typeof v.job_id === "number" &&
-        typeof v.repo_name === "string" &&
-        typeof v.job_type === "string" &&
-        typeof v.log_path === "string" &&
-        typeof v.started_at === "string");
+    return (isNonEmptyString(v.claim_id) &&
+        typeof v.attempt === "number" &&
+        isNonEmptyString(v.log_path) &&
+        isNonEmptyString(v.log_file) &&
+        isNonEmptyString(v.started_at) &&
+        (v.availability === "available" || v.availability === "unavailable"));
+}
+/** Classify a parsed JSON value as a v2 registry file, a legacy record, or neither. */
+function parseRegistry(value, jobId) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return { kind: "invalid" };
+    const v = value;
+    if (v.version === undefined && typeof v.log_path === "string") {
+        // The flat BAPI-535 record. Its `log_path` named the retired fixed alias,
+        // whose contents may belong to any later attempt.
+        return { kind: "legacy" };
+    }
+    if (v.version !== EXECUTOR_JOB_LOG_REGISTRY_VERSION ||
+        v.job_id !== jobId ||
+        !isNonEmptyString(v.repo_name) ||
+        !isNonEmptyString(v.job_type) ||
+        !Array.isArray(v.attempts)) {
+        return { kind: "invalid" };
+    }
+    const file = {
+        version: EXECUTOR_JOB_LOG_REGISTRY_VERSION,
+        job_id: jobId,
+        repo_name: v.repo_name,
+        job_type: v.job_type,
+        // Malformed entries are dropped here and so can never be selected; the
+        // well-formed ones are validated again, individually, before use.
+        attempts: v.attempts.filter(isAttemptEntry),
+    };
+    if (isNonEmptyString(v.ticket_key))
+        file.ticket_key = v.ticket_key;
+    if (isNonEmptyString(v.worktree_path))
+        file.worktree_path = v.worktree_path;
+    return { kind: "v2", file };
+}
+/** Per-job serialization of read/modify/write cycles within this process. */
+const registryLocks = new Map();
+function withJobLock(jobId, fn) {
+    const prior = registryLocks.get(jobId) ?? Promise.resolve();
+    const next = prior.then(fn, fn);
+    const settled = next.then(() => undefined, () => undefined);
+    registryLocks.set(jobId, settled);
+    void settled.then(() => {
+        if (registryLocks.get(jobId) === settled)
+            registryLocks.delete(jobId);
+    });
+    return next;
+}
+let tempCounter = 0;
+/** Replace the record atomically when a rename seam exists. */
+async function writeRegistryFile(filePath, data, deps) {
+    if (!deps.rename) {
+        await deps.writeFile(filePath, data);
+        return;
+    }
+    tempCounter += 1;
+    const tempPath = `${filePath}.${process.pid}.${tempCounter}.tmp`;
+    await deps.writeFile(tempPath, data);
+    await deps.rename(tempPath, filePath);
 }
-/** Write the secret-free registry record when a worker log is initialized. */
+async function readParsed(filePath, jobId, deps) {
+    let raw;
+    try {
+        raw = await deps.readFile(filePath);
+    }
+    catch {
+        return "missing";
+    }
+    try {
+        return parseRegistry(JSON.parse(raw), jobId);
+    }
+    catch {
+        return "unreadable";
+    }
+}
+/**
+ * Record one attempt's log when its tee is initialized.
+ *
+ * Earlier attempts are RETAINED: the new attempt is appended to the job's list
+ * (a re-registration of the same claim identity replaces only its own entry). A
+ * legacy or unreadable prior record is superseded, because it cannot be read
+ * safely anyway. Throws only on an invalid identity or a write failure; callers
+ * treat the registry as a visibility nicety and swallow either.
+ */
 export async function registerExecutorJobLog(record, deps) {
+    const identity = { jobId: record.job_id, attempt: record.attempt, claimId: record.claim_id };
+    const logFile = workerLogAttemptFileName(identity);
+    const platform = deps.platform ?? process.platform;
     const stateDir = resolveExecutorStateDir(deps);
-    await deps.mkdir(stateDir, { recursive: true });
-    const filePath = jobLogRecordPath(stateDir, record.job_id, deps.platform ?? process.platform);
-    await deps.writeFile(filePath, JSON.stringify(normalizeRecord(record), null, 2));
+    const filePath = jobLogRecordPath(stateDir, record.job_id, platform);
+    await withJobLock(record.job_id, async () => {
+        await deps.mkdir(stateDir, { recursive: true });
+        const parsed = await readParsed(filePath, record.job_id, deps);
+        const prior = typeof parsed === "object" && parsed.kind === "v2" ? parsed.file.attempts : [];
+        const entry = {
+            claim_id: record.claim_id,
+            attempt: record.attempt,
+            log_path: record.log_path,
+            log_file: logFile,
+            started_at: record.started_at,
+            availability: record.availability === "unavailable" ? "unavailable" : "available",
+            ...(record.unavailable_reason ? { unavailable_reason: record.unavailable_reason } : {}),
+        };
+        const file = {
+            version: EXECUTOR_JOB_LOG_REGISTRY_VERSION,
+            job_id: record.job_id,
+            repo_name: record.repo_name,
+            job_type: record.job_type,
+            ...(record.ticket_key ? { ticket_key: record.ticket_key } : {}),
+            ...(record.worktree_path ? { worktree_path: record.worktree_path } : {}),
+            attempts: [...prior.filter((a) => a.claim_id !== record.claim_id), entry],
+        };
+        await writeRegistryFile(filePath, serialize(file), deps);
+    });
 }
 /**
- * Stamp `finished_at` on an existing record after terminal completion/failure,
- * preserving all existing fields. A missing/invalid record is a no-op (the watch
- * registry is a visibility nicety, not load-bearing).
+ * Stamp `finished_at` on ONE attempt — the one whose claim identity is given —
+ * after terminal completion/failure, preserving every other attempt. A missing,
+ * legacy, or invalid record, or an unknown claim, is a no-op (the watch registry
+ * is a visibility nicety, not load-bearing).
  */
-export async function markExecutorJobLogFinished(jobId, finishedAt, deps) {
-    const existing = await readExecutorJobLogRecord(jobId, deps);
-    if (!existing.ok)
-        return;
-    const updated = { ...existing.record, finished_at: finishedAt };
+export async function markExecutorJobLogFinished(jobId, claimId, finishedAt, deps, update = {}) {
     const stateDir = resolveExecutorStateDir(deps);
     const filePath = jobLogRecordPath(stateDir, jobId, deps.platform ?? process.platform);
-    await deps.writeFile(filePath, JSON.stringify(normalizeRecord(updated), null, 2));
+    await withJobLock(jobId, async () => {
+        const parsed = await readParsed(filePath, jobId, deps);
+        if (typeof parsed !== "object" || parsed.kind !== "v2")
+            return;
+        const index = parsed.file.attempts.findIndex((a) => a.claim_id === claimId);
+        if (index < 0)
+            return;
+        const current = parsed.file.attempts[index];
+        const next = { ...current, finished_at: finishedAt };
+        if (update.availability === "unavailable") {
+            next.availability = "unavailable";
+            if (update.unavailable_reason)
+                next.unavailable_reason = update.unavailable_reason;
+        }
+        const attempts = [...parsed.file.attempts];
+        attempts[index] = next;
+        await writeRegistryFile(filePath, serialize({ ...parsed.file, attempts }), deps);
+    });
+}
+/**
+ * Validate that an attempt entry's stable reference is really that attempt's own
+ * file: the claim identity is well formed, the filename is exactly the one this
+ * identity allocates, and the path ends in that filename (inside the recorded
+ * worktree's `.conductor`, when a worktree is recorded).
+ */
+function attemptReferenceIsValid(file, entry, platform) {
+    const identity = { jobId: file.job_id, attempt: entry.attempt, claimId: entry.claim_id };
+    if (!isValidWorkerLogAttemptIdentity(identity))
+        return false;
+    if (!WORKER_LOG_ATTEMPT_FILE_RE.test(entry.log_file))
+        return false;
+    if (entry.log_file !== workerLogAttemptFileName(identity))
+        return false;
+    const pathApi = pathApiForExecutorPlatform(platform);
+    if (pathApi.basename(entry.log_path) === CONDUCTOR_WORKER_LOG_FILE)
+        return false;
+    if (pathApi.basename(entry.log_path) !== entry.log_file)
+        return false;
+    if (file.worktree_path) {
+        const expected = pathApi.join(file.worktree_path, ".conductor", entry.log_file);
+        if (pathApi.normalize(entry.log_path) !== pathApi.normalize(expected))
+            return false;
+    }
+    return true;
 }
 // ---------------------------------------------------------------------------
 // Active worker logs (BAPI-828)
 // ---------------------------------------------------------------------------
 /**
- * In-memory map of job id → worker-log path for jobs whose tee is currently open.
+ * In-memory map of (job id, claim identity) → worker-log path for attempts whose
+ * tee is currently open.
  *
  * DELIBERATELY SEPARATE FROM THE PERSISTED RECORD ABOVE, and deliberately not
  * derived from it. The persisted record is a visibility nicety for a SEPARATE
  * `executor watch` process, it is written with best-effort error swallowing, and
- * it keeps its row after `finished_at` is stamped. This map answers a different
+ * it keeps its rows after `finished_at` is stamped. This map answers a different
  * question — "which worker logs can be appended to right now, in THIS process" —
- * and the suspend diagnostic depends on that answer being correct. Deriving it
- * from the persisted record would mean a failed registry write silently disables
- * suspend annotation for a worker whose tee is perfectly healthy.
+ * and the suspend diagnostic depends on that answer being correct.
  *
- * Process-scoped module state rather than runner-scoped, unlike the live worker
- * registry: entries are keyed by server-minted job id, so two concurrent
- * `runExecutor` invocations in one process cannot collide, and each value is a
- * path only its own job ever deactivates.
+ * BAPI-1330: keyed by job AND claim identity, so a late close from an earlier
+ * claim of the same job can never deactivate its replacement's log.
  *
  * SECRET-FREE: a filesystem path inside the job's own worktree, nothing else.
  */
 const activeJobLogPaths = new Map();
+/** Legacy key for callers that do not pass a claim identity. */
+const NO_CLAIM = "-";
+function activeKey(jobId, claimId) {
+    return `${jobId}:${claimId ?? NO_CLAIM}`;
+}
 /**
- * Mark a job's worker log as open and appendable.
+ * Mark an attempt's worker log as open and appendable.
  *
  * Called once the tee EXISTS, before any registry persistence — see the map's
- * docstring for why the two are not chained. Re-activating the same job id simply
- * overwrites the path.
+ * docstring for why the two are not chained. Re-activating the same attempt
+ * simply overwrites its path.
  */
-export function activateJobLog(jobId, logPath) {
+export function activateJobLog(jobId, logPath, claimId) {
     if (typeof logPath !== "string" || logPath.length === 0)
         return;
-    activeJobLogPaths.set(jobId, logPath);
+    activeJobLogPaths.set(activeKey(jobId, claimId), logPath);
 }
-/** Stop appending to a job's worker log. Idempotent. */
-export function deactivateJobLog(jobId) {
-    activeJobLogPaths.delete(jobId);
+/**
+ * Stop appending to an attempt's worker log. Idempotent. With a claim identity
+ * only that attempt is deactivated; without one (legacy callers) every entry of
+ * the job is.
+ */
+export function deactivateJobLog(jobId, claimId) {
+    if (claimId !== undefined) {
+        activeJobLogPaths.delete(activeKey(jobId, claimId));
+        return;
+    }
+    const prefix = `${jobId}:`;
+    for (const key of [...activeJobLogPaths.keys()]) {
+        if (key.startsWith(prefix))
+            activeJobLogPaths.delete(key);
+    }
 }
 /** The distinct currently-appendable log paths (a snapshot, safe to iterate). */
 export function activeJobLogPathsSnapshot() {
@@ -152,28 +346,101 @@ export async function appendToActiveJobLogs(line, deps) {
     }));
 }
 /**
- * Load and validate a record for `executor watch <job>`. Returns a structured
- * missing/invalid result rather than throwing raw filesystem/JSON errors.
+ * Load and validate one attempt's log reference for `executor watch <job>`.
+ *
+ * Defaults to the NEWEST recorded attempt; `selector` picks an earlier one by
+ * attempt number or claim identity. Every failure is a named, secret-free
+ * `code` — a legacy fixed-alias record, a selector that names no attempt, a
+ * reference whose filename does not belong to its identity, or an attempt whose
+ * transcript was never recorded are all `ok: false`. Nothing is guessed: there
+ * is no archive lookup and no fallback to another attempt's file.
  */
-export async function readExecutorJobLogRecord(jobId, deps) {
+export async function readExecutorJobLogRecord(jobId, deps, selector = {}) {
+    const platform = deps.platform ?? process.platform;
     const stateDir = resolveExecutorStateDir(deps);
-    const filePath = jobLogRecordPath(stateDir, jobId, deps.platform ?? process.platform);
-    let raw;
-    try {
-        raw = await deps.readFile(filePath);
+    const filePath = jobLogRecordPath(stateDir, jobId, platform);
+    const parsed = await readParsed(filePath, jobId, deps);
+    if (parsed === "missing") {
+        return {
+            ok: false,
+            code: "no_registry_record",
+            reason: `no registry record for job ${jobId} (expected ${filePath})`,
+        };
     }
-    catch {
-        return { ok: false, reason: `no registry record for job ${jobId} (expected ${filePath})` };
+    if (parsed === "unreadable") {
+        return {
+            ok: false,
+            code: "registry_unreadable",
+            reason: `registry record for job ${jobId} is not valid JSON`,
+        };
     }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
+    if (parsed.kind === "legacy") {
+        return {
+            ok: false,
+            code: "legacy_unstable_log_reference",
+            reason: `registry record for job ${jobId} predates per-attempt logs and names a shared log ` +
+                "file that later attempts may have reused; its transcript cannot be attributed to an attempt",
+        };
     }
-    catch {
-        return { ok: false, reason: `registry record for job ${jobId} is not valid JSON` };
+    if (parsed.kind === "invalid") {
+        return {
+            ok: false,
+            code: "registry_invalid",
+            reason: `registry record for job ${jobId} is missing required fields`,
+        };
+    }
+    const file = parsed.file;
+    const wantsSelection = selector.attempt !== undefined || selector.claimId !== undefined;
+    let entry;
+    if (wantsSelection) {
+        const matches = file.attempts.filter((a) => (selector.attempt === undefined || a.attempt === selector.attempt) &&
+            (selector.claimId === undefined || a.claim_id === selector.claimId));
+        // Two claims of the same attempt number (a reclaim) are ambiguous by number
+        // alone; the most recent registration is the newest of them.
+        entry = matches[matches.length - 1];
+    }
+    else {
+        entry = file.attempts[file.attempts.length - 1];
     }
-    if (!isValidRecord(parsed)) {
-        return { ok: false, reason: `registry record for job ${jobId} is missing required fields` };
+    if (entry === undefined) {
+        return {
+            ok: false,
+            code: "attempt_not_found",
+            reason: wantsSelection
+                ? `job ${jobId} has no recorded attempt matching the selector`
+                : `job ${jobId} has no recorded attempt`,
+        };
     }
-    return { ok: true, record: parsed };
+    if (!attemptReferenceIsValid(file, entry, platform)) {
+        return {
+            ok: false,
+            code: "attempt_identity_invalid",
+            reason: `job ${jobId} attempt ${entry.attempt} has a log reference that does not match its identity`,
+        };
+    }
+    if (entry.availability === "unavailable") {
+        return {
+            ok: false,
+            code: "attempt_log_unavailable",
+            reason: `job ${jobId} attempt ${entry.attempt} has no recorded transcript` +
+                (entry.unavailable_reason ? ` (${entry.unavailable_reason})` : ""),
+        };
+    }
+    const record = {
+        job_id: file.job_id,
+        repo_name: file.repo_name,
+        job_type: file.job_type,
+        log_path: entry.log_path,
+        started_at: entry.started_at,
+        attempt: entry.attempt,
+        claim_id: entry.claim_id,
+        availability: entry.availability,
+    };
+    if (file.ticket_key)
+        record.ticket_key = file.ticket_key;
+    if (file.worktree_path)
+        record.worktree_path = file.worktree_path;
+    if (entry.finished_at)
+        record.finished_at = entry.finished_at;
+    return { ok: true, record };
 }