codecartographer-pi 0.19.5 → 0.20.0

package/dist/core/completion.js

@@ -1,7 +1,7 @@
 import { appendFile, copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { getNextEligiblePhase, resolvePhase, validatePhaseOutput } from "./pipeline.js";
-import { applyHandoff, autoAssignIds, buildTerminalNextActions, loadHandoffFile, normalizeStatus } from "./status.js";
+import { recomputeCursor, resolvePhase, validatePhaseOutput } from "./pipeline.js";
+import { applyHandoff, autoAssignIds, loadHandoffFile, normalizeStatus } from "./status.js";
 import { compareDottedVersions, dateOnly, newlineIfUnterminated, pathExists, uniqueStrings } from "./utils.js";
 import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
 /**
@@ -253,6 +253,80 @@ export function closureEvidenceGateActive(scaffoldVersion) {
     const comparison = compareDottedVersions(scaffoldVersion, CLOSURE_EVIDENCE_GATE_SCAFFOLD_VERSION);
     return comparison !== null && comparison >= 0;
 }
+/**
+ * Whether `text` names one of `ids` as a whole token: the id must not run
+ * straight into another id character on either side, so `arch-CF2` matches
+ * "routed as `arch-CF2`" and not "arch-CF20".
+ */
+function mentionsAnyId(text, ids) {
+    for (const id of ids) {
+        let from = 0;
+        while (true) {
+            const at = text.indexOf(id, from);
+            if (at === -1)
+                break;
+            const before = at === 0 ? "" : text[at - 1];
+            const after = text[at + id.length] ?? "";
+            if (!/[A-Za-z0-9_-]/.test(before) && !/[A-Za-z0-9_-]/.test(after))
+                return true;
+            from = at + 1;
+        }
+    }
+    return false;
+}
+/**
+ * Turn each PARTIAL validation row into a `needs-maintainer-decision`
+ * question on the phase, unless the row's criterion or evidence cell names an
+ * entry the workspace already tracks: an open question, carry-forward, or
+ * post-pipeline item, from this handoff or an earlier phase. VALIDATE.md asks
+ * the phase to name the tracking entry in the evidence cell; honouring it is
+ * what stops a routed gap from also becoming a duplicate question that every
+ * later phase re-triages and someone must close (#239).
+ *
+ * Runs after the handoff has been applied. That is also what keeps the auto
+ * ids distinct from the handoff's: both `autoAssignIds` from `oq-<phase>-1`,
+ * and assigning the gaps first let a later id-less handoff question replace a
+ * gap under the same id.
+ */
+function addPartialRowQuestions(status, phaseId, rows) {
+    const phase = status.phases[phaseId];
+    if (!phase)
+        return;
+    const trackedIds = new Set();
+    for (const phaseState of Object.values(status.phases)) {
+        for (const entry of [...(phaseState.open_questions ?? []), ...(phaseState.carry_forward ?? [])]) {
+            if (entry.id)
+                trackedIds.add(entry.id);
+        }
+    }
+    for (const entry of status.post_pipeline) {
+        if (entry.id)
+            trackedIds.add(entry.id);
+    }
+    const gapEntries = [];
+    for (const row of rows) {
+        if (!row.result.toUpperCase().includes("PARTIAL"))
+            continue;
+        if (mentionsAnyId(`${row.criterion} ${row.evidence}`, trackedIds))
+            continue;
+        const candidate = {
+            kind: "needs-maintainer-decision",
+            description: row.criterion || "Partial validation gap",
+            deferred_reason: row.evidence || "Marked PARTIAL by validation",
+        };
+        // Idempotent across re-runs of completion: the same gap is one question.
+        if (phase.open_questions.some((entry) => entry.description === candidate.description && entry.deferred_reason === candidate.deferred_reason))
+            continue;
+        gapEntries.push(candidate);
+    }
+    if (gapEntries.length === 0)
+        return;
+    // Reserve every id already on the phase so the new ones skip them; the
+    // placeholders keep autoAssignIds from touching the existing entries.
+    const reserved = phase.open_questions.filter((entry) => entry.id).map((entry) => ({ id: entry.id }));
+    autoAssignIds([...reserved, ...gapEntries], "oq", phaseId);
+    phase.open_questions.push(...gapEntries);
+}
 export async function completeValidatedPhase(cwd, validation, sourceLabel) {
     const initialState = await getWorkspaceState(cwd);
     if (!initialState)
@@ -391,20 +465,6 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
             open_questions: [],
             carry_forward: [],
         };
-        const gapEntries = lockedValidation.rows
-            .filter((row) => row.result.toUpperCase().includes("PARTIAL"))
-            .map((row) => ({
-            kind: "needs-maintainer-decision",
-            description: row.criterion || "Partial validation gap",
-            deferred_reason: row.evidence || "Marked PARTIAL by validation",
-        }));
-        autoAssignIds(gapEntries, "oq", validation.phaseId);
-        const mergedOpenQuestions = [...existingPhase.open_questions];
-        for (const candidate of gapEntries) {
-            if (!mergedOpenQuestions.some((entry) => entry.description === candidate.description && entry.deferred_reason === candidate.deferred_reason)) {
-                mergedOpenQuestions.push(candidate);
-            }
-        }
         nextStatus.phases[validation.phaseId] = {
             status: "complete",
             owner_notes: uniqueStrings([
@@ -414,22 +474,31 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
                 `Validation: ${lockedValidation.overall}`,
             ]),
             outputs_present: uniqueStrings([...existingPhase.outputs_present, validation.primaryOutput]),
-            open_questions: mergedOpenQuestions,
+            open_questions: [...existingPhase.open_questions],
             carry_forward: existingPhase.carry_forward ?? [],
         };
         if (handoff)
             applyHandoff(nextStatus, handoff);
+        // After the handoff, so a gap the handoff routed is recognised as
+        // tracked and the ids the handoff introduced are known (#239).
+        addPartialRowQuestions(nextStatus, validation.phaseId, lockedValidation.rows);
         nextStatus.last_updated = completionTimestamp;
         const nextWorkspace = { ...lockedState, status: nextStatus };
-        const nextEligible = getNextEligiblePhase(nextWorkspace);
-        nextStatus.current_phase = nextEligible?.id ?? "complete";
-        nextStatus.next_actions = nextEligible
-            ? [`Begin ${nextEligible.id} phase by producing ${nextEligible.primary_output ?? `findings/${nextEligible.id}/`}`]
-            : buildTerminalNextActions(nextStatus);
-        const artifacts = await writeCompletionArtifacts(lockedState.workspaceDir, validation.phaseId, lockedValidation, completionTimestamp, handoff);
-        closeoutPath = artifacts.closeoutPath;
-        orchestratorCheckpoint = buildOrchestratorCheckpoint(artifacts.decisionsAppended, artifacts.totalPendingProposals, nextStatus);
-        return { state: { ...nextWorkspace, status: nextStatus } };
+        recomputeCursor(nextWorkspace);
+        return {
+            state: { ...nextWorkspace, status: nextStatus },
+            // The closeout, THREAD_LOG line, decision rows, and staged proposals
+            // all assert that the phase is complete, so they are written only
+            // after status.yaml has landed (#234). Each writer is idempotent
+            // (canonical closeout name, link-deduped index line, text-deduped
+            // rows), so re-running completion regenerates whatever a failure
+            // here left out.
+            afterCommit: async () => {
+                const artifacts = await writeCompletionArtifacts(lockedState.workspaceDir, validation.phaseId, lockedValidation, completionTimestamp, handoff);
+                closeoutPath = artifacts.closeoutPath;
+                orchestratorCheckpoint = buildOrchestratorCheckpoint(artifacts.decisionsAppended, artifacts.totalPendingProposals, nextStatus);
+            },
+        };
     });
     return {
         updatedState,

package/dist/core/dashboard-writer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Render and atomically replace `.codecarto/dashboard.html`.
+ * @returns true when a fresh dashboard landed on disk; false when the
+ * workspace is missing or any gather/render/write step failed (swallowed —
+ * lifecycle callers must never fail on a dashboard problem, but they may
+ * report truthfully whether a refresh happened).
+ */
+export declare function writeDashboard(cwd: string, packageVersion: string): Promise<boolean>;

package/dist/core/dashboard-writer.js

@@ -0,0 +1,159 @@
+// I/O wrapper that gathers all dashboard inputs and writes the rendered
+// HTML to `.codecarto/dashboard.html`. Best-effort — failures are swallowed
+// and never escalate to a phase error the user sees, mirroring the
+// recordUsage discipline at extensions/codecarto/index.ts.
+//
+// Lived in the Pi extension until #254, with the MCP server reaching across
+// to import it; both surfaces refresh the dashboard at the same lifecycle
+// points (init, completion, amendment, pipeline switch, on demand), so it is
+// a core primitive like everything else they share.
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicWriteFile, DASHBOARD_RELATIVE_PATH, getWorkspaceState, loadUsage, NARRATION_CACHE_RELATIVE_PATH, parseSimpleYaml, pathExists, renderDashboard, } from "./index.js";
+const CLOSEOUT_FILENAME_RE = /^(\d{4}-\d{2}-\d{2})-(.+)\.md$/;
+/**
+ * Render and atomically replace `.codecarto/dashboard.html`.
+ * @returns true when a fresh dashboard landed on disk; false when the
+ * workspace is missing or any gather/render/write step failed (swallowed —
+ * lifecycle callers must never fail on a dashboard problem, but they may
+ * report truthfully whether a refresh happened).
+ */
+export async function writeDashboard(cwd, packageVersion) {
+    try {
+        const state = await getWorkspaceState(cwd);
+        if (!state)
+            return false;
+        const workspaceDir = state.workspaceDir;
+        const [usage, closeouts, outputsPresent, narration] = await Promise.all([
+            loadUsage(workspaceDir),
+            listCloseouts(workspaceDir),
+            buildOutputsPresent(state.workspaceDir, state.pipeline),
+            loadNarration(workspaceDir),
+        ]);
+        const inputs = {
+            status: state.status,
+            pipeline: state.pipeline,
+            usage,
+            closeouts,
+            outputsPresent,
+            packageVersion,
+            generatedAt: new Date().toISOString(),
+            narration,
+        };
+        const html = renderDashboard(inputs);
+        await atomicWriteFile(join(workspaceDir, DASHBOARD_RELATIVE_PATH), html);
+        return true;
+    }
+    catch {
+        // Best-effort: a failed dashboard write must not surface as a phase
+        // error. The user's pipeline state is unaffected; the next state
+        // change will trigger another render attempt.
+        return false;
+    }
+}
+async function listCloseouts(workspaceDir) {
+    const dir = join(workspaceDir, "closeouts");
+    if (!(await pathExists(dir)))
+        return [];
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        const m = CLOSEOUT_FILENAME_RE.exec(name);
+        if (!m)
+            continue;
+        out.push({ date: m[1], phaseOrModule: m[2], fileName: name, summary: await readCloseoutSummary(join(dir, name)) });
+    }
+    return out;
+}
+async function readCloseoutSummary(path) {
+    try {
+        const raw = await readFile(path, "utf8");
+        const lines = raw.split(/\r?\n/);
+        const summaryStart = lines.findIndex((line) => /^##\s+Summary\s*$/i.test(line.trim()));
+        if (summaryStart === -1)
+            return undefined;
+        const body = [];
+        for (const line of lines.slice(summaryStart + 1)) {
+            if (/^##\s+/.test(line.trim()))
+                break;
+            const trimmed = line.trim();
+            if (!trimmed || trimmed === "-")
+                continue;
+            body.push(trimmed.replace(/^[-*]\s+/, ""));
+            if (body.join(" ").length > 280)
+                break;
+        }
+        const summary = body.join(" ").trim();
+        return summary ? `${summary.slice(0, 280)}${summary.length > 280 ? "…" : ""}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function buildOutputsPresent(workspaceDir, pipeline) {
+    const out = new Map();
+    for (const phaseId of pipeline.phase_order) {
+        const phaseDef = pipeline.phases.find((p) => p.id === phaseId);
+        if (!phaseDef)
+            continue;
+        const entry = { secondary: [] };
+        if (phaseDef.primary_output) {
+            entry.primary = {
+                path: phaseDef.primary_output,
+                exists: await pathExists(join(workspaceDir, phaseDef.primary_output)),
+            };
+        }
+        for (const sec of phaseDef.secondary_outputs ?? []) {
+            entry.secondary.push({
+                path: sec.path,
+                exists: await pathExists(join(workspaceDir, sec.path)),
+            });
+        }
+        out.set(phaseId, entry);
+    }
+    return out;
+}
+async function loadNarration(workspaceDir) {
+    const path = join(workspaceDir, NARRATION_CACHE_RELATIVE_PATH);
+    if (!(await pathExists(path)))
+        return undefined;
+    try {
+        const raw = await readFile(path, "utf8");
+        const { frontmatter, body } = splitFrontmatter(raw);
+        if (!frontmatter)
+            return undefined;
+        const generatedAt = typeof frontmatter.generatedAt === "string" ? frontmatter.generatedAt : "";
+        const phaseCountAtGeneration = typeof frontmatter.phaseCountAtGeneration === "number" ? frontmatter.phaseCountAtGeneration : 0;
+        if (!generatedAt)
+            return undefined;
+        return { content: body.trim(), generatedAt, phaseCountAtGeneration };
+    }
+    catch {
+        return undefined;
+    }
+}
+function splitFrontmatter(raw) {
+    if (!raw.startsWith("---\n"))
+        return { frontmatter: null, body: raw };
+    const end = raw.indexOf("\n---\n", 4);
+    if (end === -1)
+        return { frontmatter: null, body: raw };
+    const yamlText = raw.slice(4, end);
+    const body = raw.slice(end + 5);
+    try {
+        const parsed = parseSimpleYaml(yamlText);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return { frontmatter: parsed, body };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return { frontmatter: null, body };
+}

package/dist/core/index.d.ts

@@ -16,3 +16,5 @@ export * from "./dashboard.ts";
 export * from "./library.ts";
 export * from "./synthesis.ts";
 export * from "./broadside.ts";
+export * from "./secrets.ts";
+export * from "./dashboard-writer.ts";

package/dist/core/index.js

@@ -19,3 +19,5 @@ export * from "./dashboard.js";
 export * from "./library.js";
 export * from "./synthesis.js";
 export * from "./broadside.js";
+export * from "./secrets.js";
+export * from "./dashboard-writer.js";

package/dist/core/library.js

@@ -32,10 +32,13 @@ import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
-import { canonicalPath, isPlainObject, normalizeForComparison, pathExists } from "./utils.js";
+import { acquireLock } from "./status.js";
+import { atomicWriteFile, canonicalPath, isPlainObject, normalizeForComparison, pathExists, uniqueTempSuffix } from "./utils.js";
 import { parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
 // ─── Constants ──────────────────────────────────────────────────────────────
 export const LIBRARY_MARKER_FILE = ".codecarto-library";
+/** Transient lock taken for the duration of one publish (see publishEntry). */
+const PUBLISH_LOCK_FILE = ".publish.lock";
 export const LIBRARY_INDEX_FILE = "index.yaml";
 export const LIBRARY_INDEX_MD_FILE = "INDEX.md";
 export const ENTRIES_DIR = "entries";
@@ -73,9 +76,7 @@ export async function writeMarker(libraryRoot, marker) {
     await mkdir(libraryRoot, { recursive: true });
     const markerPath = join(libraryRoot, LIBRARY_MARKER_FILE);
     const normalized = normalizeMarker(marker);
-    const tempPath = `${markerPath}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
-    await rename(tempPath, markerPath);
+    await atomicWriteFile(markerPath, `${JSON.stringify(normalized, null, 2)}\n`);
 }
 function normalizeMarker(raw) {
     const r = raw;
@@ -285,9 +286,7 @@ async function listVersionDirs(entryDir) {
 }
 async function writeLatestPointer(entryDir, versionDirName) {
     const latestPath = join(entryDir, LATEST_POINTER_FILE);
-    const tempPath = `${latestPath}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, `${versionDirName}\n`, "utf8");
-    await rename(tempPath, latestPath);
+    await atomicWriteFile(latestPath, `${versionDirName}\n`);
 }
 async function readLatestPointer(entryDir) {
     const latestPath = join(entryDir, LATEST_POINTER_FILE);
@@ -379,108 +378,120 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
     }
     const namespace = input.namespace;
     const entryDir = entryRoot(libraryRoot, namespace, input.slug);
-    const preview = await previewPublishVersion(libraryRoot, spec, { slug: input.slug, namespace }, opts);
-    const latestVersion = preview.latestVersion;
-    // Collision guard. Slugs derive from the trailing path segment of the source
-    // repo, so two unrelated projects (acme/whisper and openai/whisper) collapse
-    // onto one slug. Without this check the second publish would append its spec
-    // to the first project's version history, and the index would then report the
-    // newcomer's source_repo as though it owned every prior version. Checked
-    // before the idempotence branch below, because a metadata-only update would
-    // overwrite the wrong entry just as silently.
-    if (latestVersion > 0 && !opts.allowSourceRepoChange) {
-        const recorded = await readRecordedSourceRepo(libraryRoot, namespace, input.slug, latestVersion);
-        if (recorded !== null && !sameSourceRepo(recorded, input.source_repo)) {
+    // One publisher at a time. Version assignment reads the entry directory
+    // and then creates v<N+1>; two publishes of one slug in the same window
+    // both picked the same N, so the loser died on a raw rename error and the
+    // winner's latest pointer could be overwritten (#240). The lock lives in
+    // the library root, which exists before any entry does, so a refused
+    // publish still writes nothing.
+    const lock = await acquireLock(join(libraryRoot, PUBLISH_LOCK_FILE));
+    try {
+        const preview = await previewPublishVersion(libraryRoot, spec, { slug: input.slug, namespace }, opts);
+        const latestVersion = preview.latestVersion;
+        // Collision guard. Slugs derive from the trailing path segment of the source
+        // repo, so two unrelated projects (acme/whisper and openai/whisper) collapse
+        // onto one slug. Without this check the second publish would append its spec
+        // to the first project's version history, and the index would then report the
+        // newcomer's source_repo as though it owned every prior version. Checked
+        // before the idempotence branch below, because a metadata-only update would
+        // overwrite the wrong entry just as silently.
+        if (latestVersion > 0 && !opts.allowSourceRepoChange) {
+            const recorded = await readRecordedSourceRepo(libraryRoot, namespace, input.slug, latestVersion);
+            if (recorded !== null && !sameSourceRepo(recorded, input.source_repo)) {
+                const label = namespace ? `${namespace}/${input.slug}` : input.slug;
+                throw new SourceRepoMismatchError(`Refusing to publish: entry "${label}" v${latestVersion} records source_repo ` +
+                    `"${recorded}", but this publish carries "${input.source_repo}". Publishing would ` +
+                    `append this spec to a different project's version history. Publish this project ` +
+                    `under a distinct slug to shelve it separately, or — if the repository itself ` +
+                    `moved (rename, org transfer, host change) — re-publish with the source-repo ` +
+                    `change allowed: allow_source_repo_change on codecarto_publish, ` +
+                    `allowSourceRepoChange in PublishOptions.`, recorded, input.source_repo);
+            }
+        }
+        // Confidentiality guard. Levels are ordered internal < shared < public. An
+        // entry may sit in a library at or below its own level, but one more
+        // restricted than its library would be exposed to everyone the library
+        // reaches: an internal spec in a public library is a leak. Either side that
+        // declares nothing counts as internal — the marker default initLibrary
+        // writes, and the entry default docs/library-format.md documents — so a
+        // library with no visibility field accepts everything it did before. Like
+        // the collision guard this runs ahead of the idempotence branch, so a
+        // metadata-only update cannot reclassify an entry past it, and it fails
+        // before anything is written.
+        const entryConfidentiality = input.confidentiality ?? DEFAULT_VISIBILITY;
+        const libraryVisibility = marker.visibility ?? DEFAULT_VISIBILITY;
+        if (!opts.allowConfidentialityMismatch && VISIBILITY_RANK[entryConfidentiality] < VISIBILITY_RANK[libraryVisibility]) {
             const label = namespace ? `${namespace}/${input.slug}` : input.slug;
-            throw new SourceRepoMismatchError(`Refusing to publish: entry "${label}" v${latestVersion} records source_repo ` +
-                `"${recorded}", but this publish carries "${input.source_repo}". Publishing would ` +
-                `append this spec to a different project's version history. Publish this project ` +
-                `under a distinct slug to shelve it separately, or — if the repository itself ` +
-                `moved (rename, org transfer, host change) — re-publish with the source-repo ` +
-                `change allowed: allow_source_repo_change on codecarto_publish, ` +
-                `allowSourceRepoChange in PublishOptions.`, recorded, input.source_repo);
+            const declared = input.confidentiality ? "" : " (the default when none is declared)";
+            throw new ConfidentialityMismatchError(`Refusing to publish: entry "${label}" has confidentiality "${entryConfidentiality}"${declared}, ` +
+                `but library "${marker.name}" has visibility "${libraryVisibility}". Publishing would expose a ` +
+                `spec classified "${entryConfidentiality}" to everyone the "${libraryVisibility}" library reaches. ` +
+                `Publish it to a library whose visibility is "${entryConfidentiality}" or narrower, declare a ` +
+                `confidentiality of "${libraryVisibility}" or wider if the spec may travel that far, or — if ` +
+                `this exposure is intended — re-publish with the mismatch allowed: ` +
+                `allow_confidentiality_mismatch on codecarto_publish, allowConfidentialityMismatch in PublishOptions.`, entryConfidentiality, libraryVisibility);
         }
-    }
-    // Confidentiality guard. Levels are ordered internal < shared < public. An
-    // entry may sit in a library at or below its own level, but one more
-    // restricted than its library would be exposed to everyone the library
-    // reaches: an internal spec in a public library is a leak. Either side that
-    // declares nothing counts as internal — the marker default initLibrary
-    // writes, and the entry default docs/library-format.md documents — so a
-    // library with no visibility field accepts everything it did before. Like
-    // the collision guard this runs ahead of the idempotence branch, so a
-    // metadata-only update cannot reclassify an entry past it, and it fails
-    // before anything is written.
-    const entryConfidentiality = input.confidentiality ?? DEFAULT_VISIBILITY;
-    const libraryVisibility = marker.visibility ?? DEFAULT_VISIBILITY;
-    if (!opts.allowConfidentialityMismatch && VISIBILITY_RANK[entryConfidentiality] < VISIBILITY_RANK[libraryVisibility]) {
-        const label = namespace ? `${namespace}/${input.slug}` : input.slug;
-        const declared = input.confidentiality ? "" : " (the default when none is declared)";
-        throw new ConfidentialityMismatchError(`Refusing to publish: entry "${label}" has confidentiality "${entryConfidentiality}"${declared}, ` +
-            `but library "${marker.name}" has visibility "${libraryVisibility}". Publishing would expose a ` +
-            `spec classified "${entryConfidentiality}" to everyone the "${libraryVisibility}" library reaches. ` +
-            `Publish it to a library whose visibility is "${entryConfidentiality}" or narrower, declare a ` +
-            `confidentiality of "${libraryVisibility}" or wider if the spec may travel that far, or — if ` +
-            `this exposure is intended — re-publish with the mismatch allowed: ` +
-            `allow_confidentiality_mismatch on codecarto_publish, allowConfidentialityMismatch in PublishOptions.`, entryConfidentiality, libraryVisibility);
-    }
-    // Content-hash idempotence: if the latest version's spec matches bytes-for-bytes
-    // (decided by previewPublishVersion above), update metadata in place and
-    // return without bumping the version.
-    if (!preview.isNewVersion) {
-        const latestVersionDir = versionDir(libraryRoot, namespace, input.slug, latestVersion);
-        // buildMetadata writes provenance only when the input carries it, and
-        // neither surface sends it on publish — so without this the rewrite
-        // would drop the block the version's original publish recorded.
-        const provenance = input.provenance ?? (await readRecordedProvenance(libraryRoot, namespace, input.slug, latestVersion));
-        const metadata = buildMetadata({ ...input, provenance }, latestVersion);
-        await atomicWriteYaml(join(latestVersionDir, METADATA_FILE), metadata);
+        // Content-hash idempotence: if the latest version's spec matches bytes-for-bytes
+        // (decided by previewPublishVersion above), update metadata in place and
+        // return without bumping the version.
+        if (!preview.isNewVersion) {
+            const latestVersionDir = versionDir(libraryRoot, namespace, input.slug, latestVersion);
+            // buildMetadata writes provenance only when the input carries it, and
+            // neither surface sends it on publish — so without this the rewrite
+            // would drop the block the version's original publish recorded.
+            const provenance = input.provenance ?? (await readRecordedProvenance(libraryRoot, namespace, input.slug, latestVersion));
+            const metadata = buildMetadata({ ...input, provenance }, latestVersion);
+            await atomicWriteYaml(join(latestVersionDir, METADATA_FILE), metadata);
+            if (!opts.skipReindex)
+                await reindex(libraryRoot);
+            return {
+                slug: input.slug,
+                namespace,
+                version: latestVersion,
+                isNewVersion: false,
+                entryDir,
+                versionDir: latestVersionDir,
+            };
+        }
+        const nextVersion = preview.version;
+        const finalVersionDir = versionDir(libraryRoot, namespace, input.slug, nextVersion);
+        const stagingDir = `${entryDir}.publish.${uniqueTempSuffix()}`;
+        // Stage all files under a sibling directory, then atomically rename it
+        // into place as v<N>. If the rename fails partway, the staging dir is
+        // left for the user to inspect or remove.
+        await mkdir(stagingDir, { recursive: true });
+        try {
+            const metadata = buildMetadata({ ...input, provenance: input.provenance ?? { prior_version: latestVersion === 0 ? null : latestVersion, mutation_source: null } }, nextVersion);
+            await writeFile(join(stagingDir, SPEC_FILE), spec, "utf8");
+            await atomicWriteYaml(join(stagingDir, METADATA_FILE), metadata);
+            await mkdir(entryDir, { recursive: true });
+            await rename(stagingDir, finalVersionDir);
+        }
+        catch (err) {
+            // Best-effort cleanup of the staging directory.
+            try {
+                await rm(stagingDir, { recursive: true, force: true });
+            }
+            catch {
+                // swallow — leave the staging dir for diagnostics
+            }
+            throw err;
+        }
+        await writeLatestPointer(entryDir, `v${nextVersion}`);
         if (!opts.skipReindex)
             await reindex(libraryRoot);
         return {
             slug: input.slug,
             namespace,
-            version: latestVersion,
-            isNewVersion: false,
+            version: nextVersion,
+            isNewVersion: true,
             entryDir,
-            versionDir: latestVersionDir,
+            versionDir: finalVersionDir,
         };
     }
-    const nextVersion = preview.version;
-    const finalVersionDir = versionDir(libraryRoot, namespace, input.slug, nextVersion);
-    const stagingDir = `${entryDir}.publish.${process.pid}.${Date.now()}`;
-    // Stage all files under a sibling directory, then atomically rename it
-    // into place as v<N>. If the rename fails partway, the staging dir is
-    // left for the user to inspect or remove.
-    await mkdir(stagingDir, { recursive: true });
-    try {
-        const metadata = buildMetadata({ ...input, provenance: input.provenance ?? { prior_version: latestVersion === 0 ? null : latestVersion, mutation_source: null } }, nextVersion);
-        await writeFile(join(stagingDir, SPEC_FILE), spec, "utf8");
-        await atomicWriteYaml(join(stagingDir, METADATA_FILE), metadata);
-        await mkdir(entryDir, { recursive: true });
-        await rename(stagingDir, finalVersionDir);
-    }
-    catch (err) {
-        // Best-effort cleanup of the staging directory.
-        try {
-            await rm(stagingDir, { recursive: true, force: true });
-        }
-        catch {
-            // swallow — leave the staging dir for diagnostics
-        }
-        throw err;
+    finally {
+        await lock.release();
     }
-    await writeLatestPointer(entryDir, `v${nextVersion}`);
-    if (!opts.skipReindex)
-        await reindex(libraryRoot);
-    return {
-        slug: input.slug,
-        namespace,
-        version: nextVersion,
-        isNewVersion: true,
-        entryDir,
-        versionDir: finalVersionDir,
-    };
 }
 function buildMetadata(input, version) {
     const out = {
@@ -665,7 +676,10 @@ export async function listEntries(libraryRoot, filter = {}) {
             return false;
         if (filter.slug !== undefined && e.slug !== filter.slug)
             return false;
-        if (filter.source_repo !== undefined && e.source_repo !== filter.source_repo)
+        // Same equivalence the publish guard applies: `.git`, scheme, userinfo,
+        // default port, and forge-host case do not make two references two
+        // repositories, so they must not make a filter miss one either (#257).
+        if (filter.source_repo !== undefined && !sameSourceRepo(e.source_repo, filter.source_repo))
             return false;
         if (filter.tag !== undefined && !e.tags.includes(filter.tag))
             return false;
@@ -853,10 +867,7 @@ async function writeIndexMarkdown(libraryRoot, index, marker) {
         lines.push("");
     }
     const content = lines.join("\n");
-    const path = join(libraryRoot, LIBRARY_INDEX_MD_FILE);
-    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, content, "utf8");
-    await rename(tempPath, path);
+    await atomicWriteFile(join(libraryRoot, LIBRARY_INDEX_MD_FILE), content);
 }
 function formatIndexRow(e, namespaced) {
     // Link to the newest version directory, not `latest/`: the pointer is a
@@ -941,10 +952,7 @@ async function findProvenanceConflict(libraryRoot, namespace, slug) {
 }
 // ─── Atomic YAML write ──────────────────────────────────────────────────────
 async function atomicWriteYaml(path, value) {
-    const serialized = `${stringifySimpleYaml(value)}\n`;
-    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, serialized, "utf8");
-    await rename(tempPath, path);
+    await atomicWriteFile(path, `${stringifySimpleYaml(value)}\n`);
 }
 // ─── Hash ───────────────────────────────────────────────────────────────────
 function sha256(content) {