@bridge_gpt/mcp-server 0.2.24 → 0.2.26

package/build/conductor-bundle-artifacts.js

@@ -0,0 +1,802 @@
+/**
+ * BAPI-634: deterministic helpers for the `emit-conductor-bundle` standalone
+ * instruction — the post-ticket-creation, pre-approval step that harmonizes an
+ * epic's sibling tickets and emits the artifacts the conductor needs.
+ *
+ * The orchestration (reading siblings, reconciling contradictions, rendering
+ * descriptions) lives in `instructions/emit-conductor-bundle.md`. Only the parts
+ * that must NOT depend on agent judgment live here:
+ *
+ *   - entry validation of identities, the node→ticket mapping, and paths;
+ *   - touched-file normalization;
+ *   - placeholder→real-key sidecar finalization;
+ *   - the Python-compatible no-op comparison and the 16,000-char bound;
+ *   - allowlisted manifest/report serialization and atomic JSON writes.
+ *
+ * Every export is pure or takes an injected filesystem seam — no network, no
+ * subprocess, no MCP server construction.
+ */
+import path from "node:path";
+/** Jira key grammar (mirrors the `/implement-ticket` command's pattern). */
+const JIRA_KEY_RE = /^[A-Z][A-Z0-9]+-\d+$/;
+/**
+ * Sanitized epic-slug grammar. Deliberately identical to the `ticket_key`
+ * grammar enforced by `generate_decision_page` (`decision-page-schema.ts`),
+ * because `emit-conductor-bundle.md` passes `{epic_slug}` as that tool's
+ * `ticket_key`. A slug this rejects could never render its decision page.
+ */
+const EPIC_SLUG_RE = /^[A-Za-z][A-Za-z0-9_-]*$/;
+/** Placeholder node identity written by `decompose-epic.md` before tickets exist. */
+const PLACEHOLDER_RE = /TBD-\d+/;
+/**
+ * The conductor's hard spec bound. `_resolve_spec_review_ticket_spec()` truncates
+ * silently at this many characters (`api/library/epic_conductor/reconciler.py`),
+ * so a description over it loses content with no error. We fail loud instead.
+ */
+export const TICKET_SPEC_MAX_CHARS = 16000;
+/** Schema version stamped into every emitted manifest. */
+export const SIBLING_TICKET_MANIFEST_SCHEMA_VERSION = 1;
+/** Schema version stamped into every emitted harmonization report. */
+export const HARMONIZATION_REPORT_SCHEMA_VERSION = 1;
+/** The seven reconciliation classes from the ticket's taxonomy. */
+export const HARMONIZATION_FINDING_CLASSES = [
+    "interface_drift",
+    "ownership_collision",
+    "orphan_consumer",
+    "order_violation",
+    "scope_overlap",
+    "vocabulary_drift",
+    "nfr_conflict",
+];
+const fail = (error) => ({ ok: false, error });
+const succeed = (value) => ({ ok: true, value });
+// ===========================================================================
+// Touched-file normalization
+// ===========================================================================
+/**
+ * Reject, don't drop. `normalizeDeclaredTouchedFiles` in `conductor/file-scope-guard.ts`
+ * silently drops unusable entries because a warn-only guard must never fail; here
+ * the opposite is required. An entry we cannot normalize means ownership is
+ * *unknown*, and the ticket is explicit that unknown must never be encoded as an
+ * empty array — an empty `touched_files` silently disables overlap protection.
+ *
+ * Concrete files only. `apply_file_overlap_serialization`
+ * (`api/library/db/epic_runs.py`) intersects normalized path *strings* with
+ * `set(a) & set(b)`, so a directory or glob entry never matches a real path — it
+ * would look like a declaration while protecting nothing.
+ */
+export function normalizeTouchedFiles(input) {
+    if (!Array.isArray(input)) {
+        return fail("touched_files must be an array of repository-relative paths.");
+    }
+    const out = new Set();
+    for (const item of input) {
+        const normalized = normalizeTouchedFileEntry(item);
+        if (!normalized.ok)
+            return normalized;
+        out.add(normalized.value);
+    }
+    return succeed(Array.from(out).sort());
+}
+/** Normalize one entry, or explain precisely why it is unusable. */
+function normalizeTouchedFileEntry(item) {
+    if (typeof item !== "string") {
+        return fail(`touched_files entries must be strings, got ${JSON.stringify(item)}.`);
+    }
+    const trimmed = item.trim();
+    if (trimmed.length === 0) {
+        return fail("touched_files entries must not be blank.");
+    }
+    // Prose is the common LLM failure here ("the routes module"). A real path has
+    // no whitespace; catching it explicitly beats emitting a path that can never
+    // intersect anything.
+    if (/\s/.test(trimmed)) {
+        return fail(`touched_files entry ${JSON.stringify(item)} contains whitespace — ` +
+            "declare a concrete repository-relative file path, not prose.");
+    }
+    // Check absolute forms BEFORE separator normalization so both styles are caught.
+    if (trimmed.startsWith("/") ||
+        trimmed.startsWith("\\") ||
+        /^[A-Za-z]:[\\/]/.test(trimmed)) {
+        return fail(`touched_files entry ${JSON.stringify(item)} must be repository-relative, not absolute.`);
+    }
+    if (trimmed.startsWith("./")) {
+        return fail(`touched_files entry ${JSON.stringify(item)} must not start with './' — ` +
+            "the backend does not normalize it away before comparing paths.");
+    }
+    const posix = trimmed.replace(/\\/g, "/");
+    const segments = posix.split("/");
+    if (segments.some((s) => s === "..")) {
+        return fail(`touched_files entry ${JSON.stringify(item)} must not contain '..' traversal.`);
+    }
+    if (posix.endsWith("/")) {
+        return fail(`touched_files entry ${JSON.stringify(item)} looks like a directory. ` +
+            "The backend intersects path strings exactly, so a directory protects nothing — " +
+            "declare each concrete file.");
+    }
+    if (posix.includes("*") || posix.includes("?")) {
+        return fail(`touched_files entry ${JSON.stringify(item)} looks like a glob. ` +
+            "The backend intersects path strings exactly, so a glob never matches — " +
+            "declare each concrete file.");
+    }
+    // Worker worktrees are cut per dispatch; a path through one is never a
+    // repo-relative declaration and would never intersect a sibling's.
+    if (/(^|\/)\.worktrees?(\/|$)/.test(posix) || posix.startsWith("tmp/")) {
+        return fail(`touched_files entry ${JSON.stringify(item)} points into a temporary worktree.`);
+    }
+    const cleaned = segments.filter((s) => s !== "" && s !== ".").join("/");
+    if (cleaned.length === 0) {
+        return fail(`touched_files entry ${JSON.stringify(item)} is not a usable path.`);
+    }
+    return succeed(cleaned);
+}
+/**
+ * Validate identities, mapping cardinality, manifest agreement, and path
+ * containment, returning canonical resolved paths. Fails before any mapped file
+ * is read and before any mutation.
+ *
+ * Node identity is taken ONLY from `plan_node_id` matching a sidecar node. It is
+ * never inferred from mapping order, ticket titles, descriptions, or a Jira
+ * search — inferring it risks attaching one ticket's dependencies to another.
+ */
+export async function validateConductorBundleInputs(args, fs) {
+    const { epic_key, epic_slug, docs_dir, mappings } = args;
+    if (typeof epic_key !== "string" || !JIRA_KEY_RE.test(epic_key)) {
+        return fail(`epic_key must match ${JIRA_KEY_RE.source}, got ${JSON.stringify(epic_key)}.`);
+    }
+    if (typeof epic_slug !== "string" || !EPIC_SLUG_RE.test(epic_slug)) {
+        return fail(`epic_slug must match ${EPIC_SLUG_RE.source}, got ${JSON.stringify(epic_slug)}.`);
+    }
+    if (!Array.isArray(mappings) || mappings.length === 0) {
+        return fail("mappings must be a non-empty array of node→ticket entries.");
+    }
+    const seenNodes = new Set();
+    const seenKeys = new Set();
+    for (const entry of mappings) {
+        if (!entry || typeof entry !== "object") {
+            return fail("Every mapping entry must be an object.");
+        }
+        const { plan_node_id, ticket_key } = entry;
+        if (typeof plan_node_id !== "string" || plan_node_id.trim().length === 0) {
+            return fail("Every mapping entry needs a non-empty plan_node_id.");
+        }
+        if (typeof ticket_key !== "string" || !JIRA_KEY_RE.test(ticket_key)) {
+            return fail(`Mapping for ${plan_node_id} has an invalid ticket_key ${JSON.stringify(ticket_key)}.`);
+        }
+        if (ticket_key === epic_key) {
+            return fail(`Mapping for ${plan_node_id} uses the epic key ${epic_key} as a child ticket.`);
+        }
+        if (seenNodes.has(plan_node_id)) {
+            return fail(`Duplicate plan_node_id ${plan_node_id} in mappings.`);
+        }
+        if (seenKeys.has(ticket_key)) {
+            return fail(`Duplicate ticket_key ${ticket_key} in mappings.`);
+        }
+        seenNodes.add(plan_node_id);
+        seenKeys.add(ticket_key);
+    }
+    const sidecarNodes = readSidecarNodeKeys(args.sidecar);
+    if (!sidecarNodes.ok)
+        return fail(sidecarNodes.error);
+    const planVersion = readSidecarPlanVersion(args.sidecar);
+    if (!planVersion.ok)
+        return fail(planVersion.error);
+    const coverage = checkMappingCoversSidecar(mappings, sidecarNodes.value);
+    if (!coverage.ok)
+        return fail(coverage.error);
+    if (args.existing_manifest !== undefined && args.existing_manifest !== null) {
+        const agreement = checkManifestAgreement(args.existing_manifest, {
+            epic_key,
+            epic_slug,
+            plan_version: planVersion.value,
+            decomposition_fingerprint: args.decomposition_fingerprint,
+            mappings,
+        });
+        if (!agreement.ok)
+            return fail(agreement.error);
+    }
+    const epicDir = path.resolve(docs_dir, "epic-plans", epic_slug);
+    const resolvedEpicDir = await canonicalize(epicDir, fs);
+    if (!resolvedEpicDir.ok)
+        return fail(resolvedEpicDir.error);
+    const resolvedMappings = [];
+    for (const entry of mappings) {
+        const exploration = await resolveInsideEpicDir(entry.exploration_path, resolvedEpicDir.value, fs, `${entry.plan_node_id} exploration_path`);
+        if (!exploration.ok)
+            return fail(exploration.error);
+        const draft = await resolveInsideEpicDir(entry.draft_path, resolvedEpicDir.value, fs, `${entry.plan_node_id} draft_path`);
+        if (!draft.ok)
+            return fail(draft.error);
+        resolvedMappings.push({
+            ...entry,
+            resolved_exploration_path: exploration.value,
+            resolved_draft_path: draft.value,
+        });
+    }
+    return succeed({
+        epic_key,
+        epic_slug,
+        epic_dir: resolvedEpicDir.value,
+        goals_path: path.join(resolvedEpicDir.value, "goals-and-nfrs.md"),
+        epic_plan_path: path.join(resolvedEpicDir.value, "epic-plan.md"),
+        sidecar_path: path.join(resolvedEpicDir.value, "epic-plan.dag.json"),
+        manifest_path: path.join(resolvedEpicDir.value, "sibling-ticket-manifest.json"),
+        report_path: path.join(resolvedEpicDir.value, "harmonization-report.json"),
+        plan_version: planVersion.value,
+        mappings: resolvedMappings,
+    });
+}
+/** Read the sidecar's node identities in order. */
+function readSidecarNodeKeys(sidecar) {
+    if (!sidecar || typeof sidecar !== "object") {
+        return fail("epic-plan.dag.json must parse to an object.");
+    }
+    const nodes = sidecar.nodes;
+    if (!Array.isArray(nodes) || nodes.length === 0) {
+        return fail("epic-plan.dag.json must have a non-empty nodes array.");
+    }
+    const keys = [];
+    for (const node of nodes) {
+        if (!node || typeof node !== "object") {
+            return fail("Every epic-plan.dag.json node must be an object.");
+        }
+        const key = node.ticket_key;
+        if (typeof key !== "string" || key.trim().length === 0) {
+            return fail("Every epic-plan.dag.json node needs a non-empty ticket_key.");
+        }
+        keys.push(key.trim());
+    }
+    const unique = new Set(keys);
+    if (unique.size !== keys.length) {
+        return fail("epic-plan.dag.json has duplicate node ticket_key values.");
+    }
+    return succeed(keys);
+}
+/** Read and range-check `plan_version`. */
+function readSidecarPlanVersion(sidecar) {
+    const version = sidecar.plan_version;
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+        return fail(`epic-plan.dag.json plan_version must be an integer >= 1, got ${JSON.stringify(version)}.`);
+    }
+    return succeed(version);
+}
+/**
+ * Require a complete one-to-one mapping. Each supplied `plan_node_id` must match
+ * exactly one sidecar node — either a placeholder on the initial run, or its
+ * already-mapped `ticket_key` on an idempotent rerun.
+ */
+function checkMappingCoversSidecar(mappings, nodeKeys) {
+    const nodeSet = new Set(nodeKeys);
+    for (const entry of mappings) {
+        const matchesPlaceholder = nodeSet.has(entry.plan_node_id);
+        const matchesFinalized = nodeSet.has(entry.ticket_key);
+        if (!matchesPlaceholder && !matchesFinalized) {
+            return fail(`Mapping plan_node_id ${entry.plan_node_id} matches no node in epic-plan.dag.json.`);
+        }
+    }
+    const covered = new Set();
+    for (const entry of mappings) {
+        if (nodeSet.has(entry.plan_node_id))
+            covered.add(entry.plan_node_id);
+        else
+            covered.add(entry.ticket_key);
+    }
+    const uncovered = nodeKeys.filter((k) => !covered.has(k));
+    if (uncovered.length > 0) {
+        return fail(`epic-plan.dag.json node(s) ${uncovered.join(", ")} have no mapping entry. ` +
+            "Every node must be mapped before any mutation.");
+    }
+    return succeed(true);
+}
+/**
+ * A rerun must agree with the manifest on every identity field. Neither source
+ * silently wins — disagreement halts, because the manifest may belong to another
+ * epic or another decomposition.
+ */
+function checkManifestAgreement(manifest, expected) {
+    if (!manifest || typeof manifest !== "object") {
+        return fail("sibling-ticket-manifest.json must parse to an object.");
+    }
+    const m = manifest;
+    if (m.epic_key !== expected.epic_key) {
+        return fail(`Manifest epic_key ${JSON.stringify(m.epic_key)} disagrees with the supplied ` +
+            `${expected.epic_key}. Refusing to reuse another epic's mapping.`);
+    }
+    if (m.epic_slug !== expected.epic_slug) {
+        return fail(`Manifest epic_slug ${JSON.stringify(m.epic_slug)} disagrees with the supplied ` +
+            `${expected.epic_slug}.`);
+    }
+    if (m.plan_version !== expected.plan_version) {
+        return fail(`Manifest plan_version ${JSON.stringify(m.plan_version)} disagrees with the ` +
+            `sidecar's ${expected.plan_version}.`);
+    }
+    if (m.decomposition_fingerprint !== expected.decomposition_fingerprint) {
+        return fail("Manifest decomposition_fingerprint disagrees with this decomposition. " +
+            "Refusing to reuse another decomposition's mapping.");
+    }
+    if (!Array.isArray(m.mappings)) {
+        return fail("Manifest mappings must be an array.");
+    }
+    const recorded = new Map();
+    for (const entry of m.mappings) {
+        if (!entry || typeof entry !== "object") {
+            return fail("Every manifest mapping entry must be an object.");
+        }
+        recorded.set(entry.plan_node_id, entry.ticket_key);
+    }
+    for (const entry of expected.mappings) {
+        const known = recorded.get(entry.plan_node_id);
+        if (known !== undefined && known !== entry.ticket_key) {
+            return fail(`Manifest maps ${entry.plan_node_id} to ${known}, but this invocation maps it ` +
+                `to ${entry.ticket_key}. Halting rather than preferring either source.`);
+        }
+    }
+    return succeed(true);
+}
+/** Canonicalize a path, surfacing a missing target as a validation failure. */
+async function canonicalize(target, fs) {
+    try {
+        return succeed(await fs.realpath(target));
+    }
+    catch (err) {
+        return fail(`Cannot resolve ${target}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Resolve a mapped path and prove it stays inside the epic directory. Rejects
+ * absolute paths and traversal syntactically, then re-checks containment against
+ * the CANONICAL path so a symlink cannot escape.
+ */
+async function resolveInsideEpicDir(candidate, epicDir, fs, label) {
+    if (typeof candidate !== "string" || candidate.trim().length === 0) {
+        return fail(`${label} must be a non-empty path.`);
+    }
+    const raw = candidate.trim();
+    if (path.isAbsolute(raw) || /^[A-Za-z]:[\\/]/.test(raw)) {
+        return fail(`${label} must be relative to the epic directory, not absolute.`);
+    }
+    if (raw.replace(/\\/g, "/").split("/").some((s) => s === "..")) {
+        return fail(`${label} must not contain '..' traversal.`);
+    }
+    const joined = path.resolve(epicDir, raw);
+    const canonical = await canonicalize(joined, fs);
+    if (!canonical.ok) {
+        return fail(`${label} is missing or unreadable: ${canonical.error}`);
+    }
+    if (!isInside(canonical.value, epicDir)) {
+        return fail(`${label} resolves outside the epic directory (symlink escape): ${canonical.value}`);
+    }
+    return succeed(canonical.value);
+}
+/** True when `target` is `dir` itself or lies beneath it. */
+function isInside(target, dir) {
+    if (target === dir)
+        return true;
+    return target.startsWith(dir.endsWith(path.sep) ? dir : dir + path.sep);
+}
+/**
+ * Apply one validated node→key map across `nodes[].ticket_key`,
+ * `nodes[].depends_on`, and `edges[].from`/`to`, attach per-node `touched_files`,
+ * and reject anything that would make the plan un-runnable. Mutates nothing else
+ * and never touches the input object.
+ *
+ * `plan_version` is preserved, never incremented: these changes finalize version
+ * 1 *before* it is stored.
+ */
+export function finalizeEpicPlanSidecar(args) {
+    const { sidecar, node_key_map, touched_files_by_key } = args;
+    if (!sidecar || typeof sidecar !== "object" || Array.isArray(sidecar)) {
+        return fail("epic-plan.dag.json must parse to an object.");
+    }
+    if (args.plan_version_already_stored) {
+        return fail("This plan_version is already stored. Plan blobs are immutable and " +
+            "post-approval description rewrites are forbidden, so finalizing it now " +
+            "would invalidate the approved hash. This needs an explicit re-plan.");
+    }
+    const plan = structuredClone(sidecar);
+    const versionCheck = readSidecarPlanVersion(plan);
+    if (!versionCheck.ok)
+        return fail(versionCheck.error);
+    const nodes = plan.nodes;
+    if (!Array.isArray(nodes) || nodes.length === 0) {
+        return fail("epic-plan.dag.json must have a non-empty nodes array.");
+    }
+    const edges = plan.edges;
+    if (!Array.isArray(edges)) {
+        return fail("epic-plan.dag.json edges must be an array (use [] for none).");
+    }
+    // `base_lineage` affects the plan hash but has zero consumers in either
+    // conductor. Halt rather than silently deleting it — a sidecar carrying it was
+    // built by something we do not understand, and dropping it would hide that.
+    for (const node of nodes) {
+        if ("base_lineage" in node) {
+            return fail(`Node ${String(node.ticket_key)} declares base_lineage. It has no consumer ` +
+                "and changes the plan hash for no behavioral gain; refusing to emit or " +
+                "silently remove it.");
+        }
+    }
+    const resolve = (value) => node_key_map[value] ?? value;
+    for (const node of nodes) {
+        const originalKey = String(node.ticket_key);
+        const realKey = resolve(originalKey);
+        node.ticket_key = realKey;
+        const dependsOn = node.depends_on;
+        if (dependsOn !== undefined && !Array.isArray(dependsOn)) {
+            return fail(`Node ${realKey} depends_on must be an array.`);
+        }
+        node.depends_on = (Array.isArray(dependsOn) ? dependsOn : []).map((d) => typeof d === "string" ? resolve(d) : d);
+        const touched = touched_files_by_key[realKey];
+        if (touched === undefined) {
+            return fail(`Node ${realKey} has no touched_files entry. Ownership uncertainty must be ` +
+                "escalated, never encoded as an empty array — an empty array silently " +
+                "disables file-overlap protection.");
+        }
+        const normalized = normalizeTouchedFiles(touched);
+        if (!normalized.ok)
+            return fail(`Node ${realKey}: ${normalized.error}`);
+        node.touched_files = normalized.value;
+    }
+    for (const edge of edges) {
+        if (!edge || typeof edge !== "object") {
+            return fail("Every plan edge must be an object.");
+        }
+        if (typeof edge.from === "string")
+            edge.from = resolve(edge.from);
+        if (typeof edge.to === "string")
+            edge.to = resolve(edge.to);
+    }
+    const residual = findResidualPlaceholder(plan);
+    if (residual) {
+        return fail(`Residual placeholder ${residual} survives finalization. Every TBD- reference ` +
+            "must resolve to a real key before the plan is stored.");
+    }
+    return validateFinalizedGraph(plan, nodes, edges);
+}
+/** Find any surviving `TBD-N` anywhere in the finalized plan. */
+function findResidualPlaceholder(plan) {
+    const match = PLACEHOLDER_RE.exec(JSON.stringify(plan));
+    return match ? match[0] : null;
+}
+/**
+ * Prove the finalized graph is runnable: unique keys, known references, no
+ * self-dependency, no cycle, and ordinary `edges` that encode the same graph as
+ * the canonical `depends_on`.
+ */
+function validateFinalizedGraph(plan, nodes, edges) {
+    const keys = nodes.map((n) => String(n.ticket_key));
+    const keySet = new Set(keys);
+    if (keySet.size !== keys.length) {
+        return fail("Finalized plan has duplicate ticket_key values.");
+    }
+    // `depends_on` is canonical; an edge's `from` IS the predecessor, matching
+    // `validateEpicPlanSidecar` in setup-epic.ts and the server's builder.
+    const canonicalEdges = new Set();
+    for (const node of nodes) {
+        const key = String(node.ticket_key);
+        for (const dep of node.depends_on) {
+            if (typeof dep !== "string" || !keySet.has(dep)) {
+                return fail(`Node ${key} depends_on unknown ticket ${JSON.stringify(dep)}.`);
+            }
+            if (dep === key) {
+                return fail(`Node ${key} depends on itself.`);
+            }
+            canonicalEdges.add(`${dep} ${key}`);
+        }
+    }
+    for (const edge of edges) {
+        const from = edge.from;
+        const to = edge.to;
+        if (typeof from !== "string" || !keySet.has(from)) {
+            return fail(`Edge from ${JSON.stringify(from)} references an unknown ticket.`);
+        }
+        if (typeof to !== "string" || !keySet.has(to)) {
+            return fail(`Edge to ${JSON.stringify(to)} references an unknown ticket.`);
+        }
+        // A typed overlap edge is metadata, not a semantic dependency — it carries a
+        // `kind` and is preserved verbatim rather than checked against depends_on.
+        if (typeof edge.kind === "string" && edge.kind.length > 0)
+            continue;
+        if (!canonicalEdges.has(`${from} ${to}`)) {
+            return fail(`Edge ${from} -> ${to} contradicts the canonical depends_on graph. ` +
+                "depends_on is authoritative; ordinary edges must encode the same graph.");
+        }
+    }
+    const cycle = findCycle(keys, canonicalEdges);
+    if (cycle) {
+        return fail(`Finalized plan has a cycle: ${cycle}.`);
+    }
+    return succeed(plan);
+}
+/** Iterative DFS cycle detector over `predecessor\0successor` edge keys. */
+function findCycle(keys, edgeKeys) {
+    const adjacency = new Map();
+    for (const key of keys)
+        adjacency.set(key, []);
+    for (const edgeKey of edgeKeys) {
+        const [from, to] = edgeKey.split(" ");
+        adjacency.get(from).push(to);
+    }
+    const WHITE = 0;
+    const GREY = 1;
+    const BLACK = 2;
+    const color = new Map(keys.map((k) => [k, WHITE]));
+    const stack = [];
+    const visit = (start) => {
+        const frames = [
+            { node: start, index: 0 },
+        ];
+        color.set(start, GREY);
+        stack.push(start);
+        while (frames.length > 0) {
+            const frame = frames[frames.length - 1];
+            const neighbors = adjacency.get(frame.node) ?? [];
+            if (frame.index >= neighbors.length) {
+                color.set(frame.node, BLACK);
+                stack.pop();
+                frames.pop();
+                continue;
+            }
+            const next = neighbors[frame.index++];
+            const state = color.get(next);
+            if (state === GREY) {
+                const from = stack.indexOf(next);
+                return [...stack.slice(from), next].join(" -> ");
+            }
+            if (state === WHITE) {
+                color.set(next, GREY);
+                stack.push(next);
+                frames.push({ node: next, index: 0 });
+            }
+        }
+        return null;
+    };
+    for (const key of keys) {
+        if (color.get(key) !== WHITE)
+            continue;
+        const cycle = visit(key);
+        if (cycle)
+            return cycle;
+    }
+    return null;
+}
+// ===========================================================================
+// Description comparison and bounds
+// ===========================================================================
+/**
+ * Python's `str.split()` whitespace set (`Py_UNICODE_ISSPACE`). Spelled out
+ * explicitly because JS `\s` is NOT the same set: `\s` omits `\x1c`-`\x1f` and
+ * `\x85` while including ``. A Jira description pasted from a rich-text
+ * editor routinely carries NBSP (`\xa0`), so an approximate class here would
+ * produce a different normalization than the server and rewrite tickets that
+ * did not change.
+ */
+const PY_WHITESPACE = /[\t\n\v\f\r \x1c-\x1f\x85\xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+/g;
+/**
+ * Mirror `normalize_ticket_spec()` (`api/library/epic_conductor/spec_hash.py`)
+ * so a cosmetic diff never triggers a Jira rewrite.
+ *
+ * Because whitespace collapses, a pure reflow/indent edit is deliberately NOT a
+ * material change — the server treats it the same way, and diverging here would
+ * false-freeze tickets via `spec_stale`.
+ */
+export function normalizeTicketSpecForComparison(spec) {
+    let text;
+    if (spec === null || spec === undefined) {
+        text = "";
+    }
+    else if (typeof spec === "string") {
+        text = spec;
+    }
+    else {
+        try {
+            text = canonicalJsonStringify(spec);
+        }
+        catch {
+            text = String(spec);
+        }
+    }
+    return text.replace(PY_WHITESPACE, " ").trim();
+}
+/**
+ * `json.dumps(..., sort_keys=True, separators=(",", ":"), ensure_ascii=False)`.
+ * JSON.stringify does not sort keys, so sort recursively.
+ *
+ * Caveat: Python renders a float `1.0` as `1.0` where JS renders `1`. Ticket
+ * descriptions are strings, so this path is defensive only; a numeric spec would
+ * need explicit float handling to stay hash-compatible.
+ */
+function canonicalJsonStringify(value) {
+    const sortDeep = (input) => {
+        if (Array.isArray(input))
+            return input.map(sortDeep);
+        if (input && typeof input === "object") {
+            const sorted = {};
+            for (const key of Object.keys(input).sort()) {
+                sorted[key] = sortDeep(input[key]);
+            }
+            return sorted;
+        }
+        return input;
+    };
+    return JSON.stringify(sortDeep(value));
+}
+/** Count Unicode code points — Python's `len()`, not JS's UTF-16 `.length`. */
+export function countSpecCharacters(text) {
+    let count = 0;
+    for (const _ of text)
+        count++;
+    return count;
+}
+/**
+ * Reject a description the conductor would silently truncate, or one still
+ * carrying an unresolved placeholder.
+ *
+ * The bound counts code points because the server's limit is a Python `len()`.
+ * Using JS `.length` would count an astral character (e.g. an emoji) twice and
+ * reject a description that actually fits.
+ */
+export function validateRenderedTicketDescription(description) {
+    if (typeof description !== "string") {
+        return fail("A rendered ticket description must be a string.");
+    }
+    const placeholder = PLACEHOLDER_RE.exec(description);
+    if (placeholder) {
+        return fail(`Rendered description still references ${placeholder[0]}. Resolve every ` +
+            "placeholder to a real key before emitting — a worker sees only this text.");
+    }
+    const length = countSpecCharacters(description);
+    if (length > TICKET_SPEC_MAX_CHARS) {
+        return fail(`Rendered description is ${length} characters, over the conductor's ` +
+            `${TICKET_SPEC_MAX_CHARS}-character bound. The reconciler truncates silently ` +
+            "at this bound, so emitting it would drop required content. Compact the " +
+            "description; if the required content still will not fit, escalate this as " +
+            "a decomposition/scope finding.");
+    }
+    return succeed(description);
+}
+// ===========================================================================
+// Sanitization and serialization
+// ===========================================================================
+/** Values that look like a credential regardless of their key. */
+const SECRET_VALUE_PATTERNS = [
+    /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi,
+    /\bghp_[A-Za-z0-9]{20,}/g,
+    /\bgithub_pat_[A-Za-z0-9_]{20,}/g,
+    /\bsk-[A-Za-z0-9]{20,}/g,
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}/g,
+    /\bAKIA[0-9A-Z]{16}\b/g,
+];
+/** Redaction marker used in place of removed secret-like content. */
+export const REDACTED = "[REDACTED]";
+/** Replace credential-shaped substrings in free text. */
+function sanitizeText(input) {
+    let out = input;
+    for (const pattern of SECRET_VALUE_PATTERNS) {
+        out = out.replace(pattern, REDACTED);
+    }
+    return out;
+}
+/** Truncate to a bound, marking the cut so a reader knows content was dropped. */
+function bound(input, max) {
+    const sanitized = sanitizeText(input);
+    if (countSpecCharacters(sanitized) <= max)
+        return sanitized;
+    return Array.from(sanitized).slice(0, max).join("") + "…[truncated]";
+}
+/** Field bounds for report findings — keeps one run's report reviewable. */
+const FINDING_SUMMARY_MAX = 600;
+const FINDING_RESOLUTION_MAX = 600;
+const FINDING_SEAM_MAX = 200;
+const FINDING_EVIDENCE_MAX = 200;
+/**
+ * Serialize a manifest through a strict allowlist. Anything not named here — a
+ * description, an exploration body, a credential, a raw Jira response — cannot
+ * survive into the recovery artifact.
+ */
+export function serializeSiblingTicketManifest(candidate) {
+    return {
+        schema_version: SIBLING_TICKET_MANIFEST_SCHEMA_VERSION,
+        epic_key: candidate.epic_key,
+        epic_slug: candidate.epic_slug,
+        plan_version: candidate.plan_version,
+        decomposition_fingerprint: candidate.decomposition_fingerprint,
+        finalized_fingerprint: candidate.finalized_fingerprint ?? null,
+        run_phase: candidate.run_phase,
+        mappings: (candidate.mappings ?? []).map((m) => ({
+            plan_node_id: m.plan_node_id,
+            ticket_key: m.ticket_key,
+            exploration_path: m.exploration_path,
+            draft_path: m.draft_path,
+        })),
+        decisions: (candidate.decisions ?? []).map((d) => ({
+            finding_id: d.finding_id,
+            chosen_option: bound(d.chosen_option, FINDING_SUMMARY_MAX),
+            rationale: bound(d.rationale, FINDING_RESOLUTION_MAX),
+        })),
+        completed_mutations: (candidate.completed_mutations ?? []).map((c) => ({
+            kind: c.kind,
+            ticket_key: c.ticket_key,
+            detail: bound(c.detail, FINDING_SUMMARY_MAX),
+        })),
+    };
+}
+/**
+ * Serialize a report through a strict allowlist with bounded fields and
+ * secret-value scrubbing. A finding quotes conflicting evidence, so this is the
+ * one artifact most likely to carry ticket prose — bound every field and never
+ * admit a full description or raw response.
+ */
+export function serializeHarmonizationReport(candidate) {
+    return {
+        schema_version: HARMONIZATION_REPORT_SCHEMA_VERSION,
+        harmonization_run_id: candidate.harmonization_run_id,
+        epic_key: candidate.epic_key,
+        epic_slug: candidate.epic_slug,
+        plan_version: candidate.plan_version,
+        findings: (candidate.findings ?? []).map((f) => ({
+            id: f.id,
+            finding_class: f.finding_class,
+            affected_ticket_keys: [...(f.affected_ticket_keys ?? [])],
+            affected_seam: bound(f.affected_seam ?? "", FINDING_SEAM_MAX),
+            affected_files: [...(f.affected_files ?? [])],
+            conflict_summary: bound(f.conflict_summary ?? "", FINDING_SUMMARY_MAX),
+            evidence_refs: (f.evidence_refs ?? []).map((e) => bound(e, FINDING_EVIDENCE_MAX)),
+            resolution_status: f.resolution_status,
+            resolution: bound(f.resolution ?? "", FINDING_RESOLUTION_MAX),
+        })),
+    };
+}
+/**
+ * Build a stable finding id from normalized class, affected nodes, and seam or
+ * file identity, so the same contradiction keeps its id across runs and a
+ * resumed decision still applies.
+ */
+export function buildFindingId(findingClass, affectedTicketKeys, seamIdentity) {
+    const keys = [...affectedTicketKeys].sort().join("+");
+    const seam = seamIdentity
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return `${findingClass}:${keys}:${seam}`;
+}
+// ===========================================================================
+// Atomic writes
+// ===========================================================================
+/**
+ * Write JSON by temp-file-then-rename so an interrupted run cannot leave a
+ * partial manifest, report, or sidecar. The temp file goes in the DESTINATION
+ * directory because rename is only atomic within a filesystem.
+ *
+ * On failure the previous destination is left untouched and the temp file is
+ * cleaned up; the original error is surfaced rather than the cleanup's.
+ */
+export async function writeJsonAtomically(destination, value, fs) {
+    const dir = path.dirname(destination);
+    const tempPath = path.join(dir, `.${path.basename(destination)}.tmp`);
+    const serialized = JSON.stringify(value, null, 2) + "\n";
+    try {
+        await fs.writeFile(tempPath, serialized);
+    }
+    catch (err) {
+        await cleanupQuietly(tempPath, fs);
+        return fail(`Could not write ${tempPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        await fs.rename(tempPath, destination);
+    }
+    catch (err) {
+        await cleanupQuietly(tempPath, fs);
+        return fail(`Could not replace ${destination}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return succeed(destination);
+}
+/** Best-effort temp cleanup — never masks the original failure. */
+async function cleanupQuietly(target, fs) {
+    try {
+        await fs.unlink(target);
+    }
+    catch {
+        // The temp file may never have been created; nothing to report.
+    }
+}