codecartographer-pi 0.15.0 → 0.17.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 } from "./pipeline.js";
-import { applyHandoff, autoAssignIds, loadHandoffFile, normalizeStatus } from "./status.js";
+import { getNextEligiblePhase, resolvePhase, validatePhaseOutput } from "./pipeline.js";
+import { applyHandoff, autoAssignIds, buildTerminalNextActions, loadHandoffFile, normalizeStatus } from "./status.js";
 import { dateOnly, pathExists, uniqueStrings } from "./utils.js";
 import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
 /**
@@ -46,6 +46,18 @@ function visibleMarkdown(content) {
 export const DECISIONS_COMPLETION_LOG_HEADING = "## Completion log";
 /** Section heading completion stages proposed conventions under. */
 export const CONVENTIONS_PENDING_HEADING = "## Pending proposals";
+/**
+ * True when `heading` exists as its own visible line. Both orchestrator-file
+ * templates mention their headings in running prose (issue #111: a raw
+ * substring check saw the decisions-template's "…rows under `## Completion
+ * log`…" sentence and never inserted the real heading), so presence checks
+ * must match a whole trimmed line of comment-stripped content.
+ */
+function hasVisibleHeadingLine(content, heading) {
+    return visibleMarkdown(content)
+        .split(/\r?\n/)
+        .some((line) => line.trim() === heading);
+}
 /**
  * Ensure an orchestrator file exists: prefer the workspace's template, fall
  * back to a minimal header for scaffolds that predate the template.
@@ -90,7 +102,7 @@ async function appendDecisionLog(workspaceDir, phaseId, closeoutFile, decisions)
         if (Number.isFinite(parsed) && parsed >= nextNumber)
             nextNumber = parsed + 1;
     }
-    if (!content.includes(DECISIONS_COMPLETION_LOG_HEADING)) {
+    if (!hasVisibleHeadingLine(content, DECISIONS_COMPLETION_LOG_HEADING)) {
         content += `${content.endsWith("\n") ? "" : "\n"}\n${DECISIONS_COMPLETION_LOG_HEADING}\n\nAppended by completion from each phase handoff's \`decisions\` array. The orchestrator may re-file entries into the category sections above; numbering is shared with them.\n`;
     }
     const source = closeoutFile.replace(/\.md$/, "");
@@ -114,13 +126,20 @@ export async function countPendingProposals(workspaceDir, content) {
             return 0;
         text = await readFile(filePath, "utf8");
     }
-    const start = text.indexOf(CONVENTIONS_PENDING_HEADING);
-    if (start === -1)
+    // Same line-anchored rule as the heading-insertion checks: a prose mention
+    // of the heading must not open the section early and miscount.
+    const lines = visibleMarkdown(text).split(/\r?\n/);
+    const headingIndex = lines.findIndex((line) => line.trim() === CONVENTIONS_PENDING_HEADING);
+    if (headingIndex === -1)
         return 0;
-    const rest = text.slice(start + CONVENTIONS_PENDING_HEADING.length);
-    const end = rest.indexOf("\n## ");
-    const section = end === -1 ? rest : rest.slice(0, end);
-    return section.split(/\r?\n/).filter((line) => line.startsWith("- **")).length;
+    let count = 0;
+    for (const line of lines.slice(headingIndex + 1)) {
+        if (line.startsWith("## "))
+            break;
+        if (line.startsWith("- **"))
+            count += 1;
+    }
+    return count;
 }
 /**
  * Stage handoff `proposed_conventions` in CONVENTIONS.md under
@@ -135,7 +154,7 @@ async function stageProposedConventions(workspaceDir, phaseId, timestamp, propos
         return { staged: 0, totalPending: await countPendingProposals(workspaceDir) };
     }
     let content = await ensureOrchestratorFile(workspaceDir, "CONVENTIONS.md", "conventions-template.md", "# Conventions\n\nCross-cutting patterns promoted to project-wide invariants. This scaffold predates templates/conventions-template.md; refresh the framework-owned files for the full format.\n");
-    if (!content.includes(CONVENTIONS_PENDING_HEADING)) {
+    if (!hasVisibleHeadingLine(content, CONVENTIONS_PENDING_HEADING)) {
         content += `${content.endsWith("\n") ? "" : "\n"}\n${CONVENTIONS_PENDING_HEADING}\n\nStaged by completion from each phase handoff's \`proposed_conventions\`. The orchestrator promotes an entry into a numbered convention above (or removes it with a note) at the phase boundary — see GUIDE.md §Roles.\n`;
     }
     // Same visible-content rule as the decision log: template comments must not
@@ -256,6 +275,22 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
         const phase = resolvePhase(lockedState, validation.phaseId);
         if (!phase?.primary_output)
             throw new Error(`Phase ${validation.phaseId} is missing primary_output.`);
+        // Re-validate the output under the lock (#132). The caller's
+        // validation snapshot can predate a concurrent edit or another
+        // session's completion; a stale PASS must not complete a phase whose
+        // output no longer validates. The locked recheck is the authoritative
+        // one and is what every artifact below is written from.
+        // A validation that never touched a file on disk (no outputPath)
+        // has nothing to race against, so the caller's result stands — the
+        // real surfaces (MCP, Pi) always validate real files.
+        const authoritative = validation.outputPath
+            ? await validatePhaseOutput(lockedState, validation.phaseId)
+            : validation;
+        if (authoritative.overall === "FAIL" || authoritative.overall === "MISSING") {
+            throw new Error(`Refusing to complete ${validation.phaseId}: the output no longer validates under the status lock ` +
+                `(now ${authoritative.overall}). It changed since the last validation — re-run validation and fix the output first.`);
+        }
+        const lockedValidation = authoritative;
         const nextStatus = normalizeStatus(lockedState.status, lockedState.pipeline, lockedState.status.pipeline, lockedState.cwd);
         const existingPhase = nextStatus.phases[validation.phaseId] ?? {
             status: "pending",
@@ -264,7 +299,7 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
             open_questions: [],
             carry_forward: [],
         };
-        const gapEntries = validation.rows
+        const gapEntries = lockedValidation.rows
             .filter((row) => row.result.toUpperCase().includes("PARTIAL"))
             .map((row) => ({
             kind: "needs-maintainer-decision",
@@ -284,7 +319,7 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
                 ...existingPhase.owner_notes,
                 `Completed via ${sourceLabel}.`,
                 `Primary output: .codecarto/${validation.primaryOutput}`,
-                `Validation: ${validation.overall}`,
+                `Validation: ${lockedValidation.overall}`,
             ]),
             outputs_present: uniqueStrings([...existingPhase.outputs_present, validation.primaryOutput]),
             open_questions: mergedOpenQuestions,
@@ -298,8 +333,8 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
         nextStatus.current_phase = nextEligible?.id ?? "complete";
         nextStatus.next_actions = nextEligible
             ? [`Begin ${nextEligible.id} phase by producing ${nextEligible.primary_output ?? `findings/${nextEligible.id}/`}`]
-            : ["All phases complete. Review findings, open questions, and downstream implementation notes."];
-        const artifacts = await writeCompletionArtifacts(lockedState.workspaceDir, validation.phaseId, validation, completionTimestamp, handoff);
+            : 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 } };

package/dist/core/index.d.ts

@@ -13,3 +13,4 @@ export * from "./guide.ts";
 export * from "./dashboard.ts";
 export * from "./library.ts";
 export * from "./synthesis.ts";
+export * from "./broadside.ts";

package/dist/core/index.js

@@ -16,3 +16,4 @@ export * from "./guide.js";
 export * from "./dashboard.js";
 export * from "./library.js";
 export * from "./synthesis.js";
+export * from "./broadside.js";

package/dist/core/library.d.ts

@@ -108,6 +108,20 @@ export declare function isValidSlug(slug: string): boolean;
  * to ask the user about it.
  */
 export declare function deriveSlug(sourceRepo: string): string;
+/**
+ * Reduce a repo reference to a comparable form so that spellings of the same
+ * repository do not read as different projects. Handles scheme, `git@host:path`
+ * SCP syntax, a `www.` host prefix, a trailing `.git`, repeated and trailing
+ * slashes, backslash separators, and case.
+ *
+ * This is deliberately conservative: it only collapses spellings that are
+ * unambiguously the same target. Anything it cannot prove equivalent stays
+ * distinct, because the caller treats "different" as a hard error. Case is the
+ * one place that cuts the other way — see the note above the return.
+ */
+export declare function normalizeSourceRepo(sourceRepo: string): string;
+/** True when two repo references denote the same repository. */
+export declare function sameSourceRepo(a: string, b: string): boolean;
 export interface PublishInput {
     slug: string;
     namespace?: string;
@@ -131,6 +145,14 @@ export interface PublishOptions {
     forceNewVersion?: boolean;
     /** Skip the regen of index.yaml + INDEX.md (caller will batch). */
     skipReindex?: boolean;
+    /**
+     * Permit publishing when the target entry's recorded `source_repo` differs
+     * from the incoming one. Off by default: a mismatch usually means two
+     * different projects derived the same slug, and continuing would append
+     * one project's spec to the other's version history. Set this only when
+     * the repository genuinely moved (rename, org transfer, host change).
+     */
+    allowSourceRepoChange?: boolean;
 }
 export interface PublishResult {
     slug: string;

package/dist/core/library.js

@@ -136,6 +136,83 @@ export function deriveSlug(sourceRepo) {
     const safe = slug.length === 0 || !/^[a-z]/.test(slug) ? `entry-${slug}`.slice(0, 64) : slug;
     return RESERVED_SLUGS.has(safe) ? `${safe}-entry` : safe;
 }
+/**
+ * Reduce a repo reference to a comparable form so that spellings of the same
+ * repository do not read as different projects. Handles scheme, `git@host:path`
+ * SCP syntax, a `www.` host prefix, a trailing `.git`, repeated and trailing
+ * slashes, backslash separators, and case.
+ *
+ * This is deliberately conservative: it only collapses spellings that are
+ * unambiguously the same target. Anything it cannot prove equivalent stays
+ * distinct, because the caller treats "different" as a hard error. Case is the
+ * one place that cuts the other way — see the note above the return.
+ */
+export function normalizeSourceRepo(sourceRepo) {
+    let s = sourceRepo.trim().replace(/\\/g, "/");
+    // Order matters here. The scheme comes off first so that the SCP branch
+    // below sees only genuine `host:path` syntax, and the userinfo strip runs
+    // before either interpretation of a colon. Getting this order wrong makes
+    // `ssh://git@host/acme/tool` and `https://host/acme/tool` read as two
+    // different repositories, which would refuse a legitimate re-publish.
+    const hadScheme = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(s);
+    s = s.replace(/^[A-Za-z][A-Za-z0-9+.-]*:\/\//, "");
+    // git@, user:token@, oauth2:x-oauth-basic@ ...
+    s = s.replace(/^[^/@]+@/, "");
+    // SCP syntax (git@github.com:acme/tool) only ever appears without a scheme,
+    // where the colon separates host from path rather than naming a port. The
+    // dot requirement keeps a Windows drive letter (C:/repos/tool) out of this
+    // branch.
+    if (!hadScheme)
+        s = s.replace(/^([^:/]+\.[^:/]+):(.+)$/, "$1/$2");
+    // A default port for the transports in play is not a distinguishing part of
+    // the address. Any other port is left alone, since two services on one host
+    // may genuinely differ by port.
+    s = s.replace(/^([^/]+):(?:22|80|443)(?=\/|$)/, "$1");
+    s = s.replace(/^www\./i, "");
+    s = s.replace(/\.git$/i, "");
+    // Repeated separators name the same location. A leading `//` is the one
+    // exception: on Windows that is a UNC share (\\server\share), which is not
+    // the same place as /server/share.
+    s = s.startsWith("//") ? `/${s.replace(/\/{2,}/g, "/")}` : s.replace(/\/{2,}/g, "/");
+    s = s.replace(/\/+$/, "");
+    // Case folding is only safe where the target is case-insensitive. Hosts are,
+    // as are the repository paths the major forges serve over them, and so are
+    // Windows drive paths. A POSIX absolute path is not: /srv/Repos/tool and
+    // /srv/repos/tool are two directories on Linux, and folding them together
+    // would hide exactly the cross-project collision this comparison exists to
+    // catch. Pi records the analyzed directory as source_repo, so local paths
+    // are a common case here rather than a curiosity.
+    return isCaseSensitivePath(s) ? s : s.toLowerCase();
+}
+/** An absolute POSIX path (or a `~` home reference), where case is significant. */
+function isCaseSensitivePath(s) {
+    return s.startsWith("/") || s === "~" || s.startsWith("~/");
+}
+/** True when two repo references denote the same repository. */
+export function sameSourceRepo(a, b) {
+    return normalizeSourceRepo(a) === normalizeSourceRepo(b);
+}
+/**
+ * The `source_repo` recorded on an entry's newest version, or null when it
+ * cannot be determined (no metadata, unreadable, or malformed). Null means
+ * "unknown", and callers treat unknown as permission to proceed rather than
+ * as a mismatch.
+ */
+async function readRecordedSourceRepo(libraryRoot, namespace, slug, version) {
+    const metaPath = join(versionDir(libraryRoot, namespace, slug, version), METADATA_FILE);
+    if (!(await pathExists(metaPath)))
+        return null;
+    try {
+        const raw = parseSimpleYaml(await readFile(metaPath, "utf8"));
+        if (!isPlainObject(raw))
+            return null;
+        const recorded = raw.source_repo;
+        return typeof recorded === "string" && recorded.trim() !== "" ? recorded : null;
+    }
+    catch {
+        return null;
+    }
+}
 // ─── Path helpers ───────────────────────────────────────────────────────────
 function entryRoot(libraryRoot, namespace, slug) {
     return namespace ? join(libraryRoot, ENTRIES_DIR, namespace, slug) : join(libraryRoot, ENTRIES_DIR, slug);
@@ -198,6 +275,26 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
     const existingVersions = await listVersionDirs(entryDir);
     const latestVersion = existingVersions.length === 0 ? 0 : existingVersions[existingVersions.length - 1];
     const newSpecHash = sha256(spec);
+    // 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 Error(`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.`);
+        }
+    }
     // Content-hash idempotence: if the latest version's spec matches bytes-for-bytes,
     // update metadata in place and return without bumping the version.
     if (latestVersion > 0 && !opts.forceNewVersion) {
@@ -635,7 +732,10 @@ function formatIndexRow(e, namespaced) {
     return `| ${slugLink} | v${e.latest_version} | ${headline} | ${tags} |`;
 }
 function escapeMd(value) {
-    return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+    // Backslashes first: escaping only the pipe lets an input ending in `\`
+    // turn the emitted `\|` into a literal-backslash-plus-cell-delimiter and
+    // break out of the table cell (code scanning alert #3).
+    return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
 }
 // ─── Atomic YAML write ──────────────────────────────────────────────────────
 async function atomicWriteYaml(path, value) {

package/dist/core/orchestrator-config.js

@@ -14,7 +14,7 @@
 // `library.path` is returned tilde-expanded and absolute so consumers
 // don't have to expand themselves.
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { expandTilde, pathExists } from "./utils.js";
 import { loadYamlFile, parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
@@ -131,7 +131,10 @@ export async function writeLibraryConfig(configPath, libraryPath, namespace = nu
     if (namespace)
         library.namespace = namespace;
     const updated = { ...existing, library };
-    const dir = configPath.includes("/") ? configPath.slice(0, configPath.lastIndexOf("/")) : ".";
+    // dirname() honors the platform separator; the previous hand-rolled
+    // `includes("/")` check treated every Windows path as a bare filename
+    // and left mkdir a no-op before the writeFile ENOENT'd (#128).
+    const dir = dirname(configPath);
     await mkdir(dir, { recursive: true });
     await writeFile(configPath, `${stringifySimpleYaml(updated)}\n`, "utf8");
 }

package/dist/core/pipeline.js

@@ -5,6 +5,7 @@ import { pathExists } from "./utils.js";
 export const PIPELINE_ALIASES = {
     "full-with-audit": "workflow/pipeline-full-with-audit.yaml",
     "full-with-deep-audit": "workflow/pipeline-full-with-deep-audit.yaml",
+    "scout-first": "workflow/pipeline-scout-first.yaml",
     full: "workflow/pipeline.yaml",
     "defect-scan": "workflow/pipeline-defect-scan.yaml",
     lite: "workflow/pipeline-lite.yaml",

package/dist/core/status.d.ts

@@ -9,6 +9,14 @@ export declare function autoAssignIds(entries: OpenQuestionEntry[], prefix: stri
 export declare function ensurePostPipelineArray(value: unknown): PostPipelineEntry[];
 export declare function ensurePhaseRecord(value: unknown): Record<string, StatusPhase>;
 export declare function createEmptyStatus(projectName: string, pipelinePath: string, pipeline: PipelineFile): NormalizedStatus;
+/**
+ * Route the terminal boundary to the post-pipeline surfaces (issue #114). The
+ * moment every phase completes is exactly when skills, amendments, publishing,
+ * and the dashboard apply; the prior static sentence left them undiscovered —
+ * the 0.15.0 field test finished two full runs with every one of them unused.
+ * Amendment recomputes this list so closure counts never go stale.
+ */
+export declare function buildTerminalNextActions(status: NormalizedStatus): string[];
 export declare function normalizeStatus(status: StatusFile, pipeline: PipelineFile, pipelinePath: string, cwd: string): NormalizedStatus;
 export declare function parseHandoff(value: unknown): PhaseHandoff;
 /**

package/dist/core/status.js

@@ -126,6 +126,28 @@ export function createEmptyStatus(projectName, pipelinePath, pipeline) {
         post_pipeline: [],
     };
 }
+/**
+ * Route the terminal boundary to the post-pipeline surfaces (issue #114). The
+ * moment every phase completes is exactly when skills, amendments, publishing,
+ * and the dashboard apply; the prior static sentence left them undiscovered —
+ * the 0.15.0 field test finished two full runs with every one of them unused.
+ * Amendment recomputes this list so closure counts never go stale.
+ */
+export function buildTerminalNextActions(status) {
+    const openQuestions = Object.values(status.phases).reduce((sum, phase) => sum + (phase.open_questions?.length ?? 0), 0);
+    const postPipeline = status.post_pipeline.length;
+    const actions = [
+        "All phases complete. Review findings; post-pipeline skills: codecarto_list_skills / codecarto_skill.",
+    ];
+    if (openQuestions > 0 || postPipeline > 0) {
+        actions.push(`${openQuestions} open question(s) and ${postPipeline} post-pipeline item(s) remain — apply resolutions with codecarto_amend (write scratch/amendments/<slug>.yaml from templates/amendment.yaml).`);
+    }
+    if ("reimplementation-spec" in status.phases) {
+        actions.push("Publish the finished spec to a library: codecarto_publish (create one with codecarto_library_init; see the library guide topic).");
+    }
+    actions.push("Dashboard: .codecarto/dashboard.html (refreshed on completion and amendment; codecarto_dashboard re-renders on demand). Usage totals: codecarto_usage.");
+    return actions;
+}
 export function normalizeStatus(status, pipeline, pipelinePath, cwd) {
     if (typeof status.schema_version === "number" && status.schema_version > 1) {
         throw new Error(`Unsupported status schema_version ${status.schema_version}. Supported: 1.`);
@@ -323,7 +345,15 @@ export async function acquireLock(lockPath) {
     while (true) {
         try {
             const handle = await open(lockPath, "wx");
-            await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n`, "utf8");
+            try {
+                await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n`, "utf8");
+            }
+            catch (error) {
+                // A non-EEXIST write failure must not leak the descriptor the
+                // open just created (#131); close best-effort, then rethrow.
+                await handle.close().catch(() => undefined);
+                throw error;
+            }
             await handle.close();
             return {
                 release: async () => {

package/dist/core/utils.js

@@ -34,7 +34,13 @@ export function isWithinPath(path, root) {
     const normalizedRoot = normalizeForComparison(resolve(root));
     if (normalizedPath === normalizedRoot)
         return true;
-    return normalizedPath.startsWith(`${normalizedRoot}${process.platform === "win32" ? "\\" : "/"}`);
+    // A filesystem root (e.g. "/" or "C:\") already ends in a separator;
+    // appending another one produced a prefix ("//" / "C:\\") that no real
+    // path starts with, falsely rejecting every legitimate subpath (#130).
+    const prefix = normalizedRoot.endsWith("/") || normalizedRoot.endsWith("\\")
+        ? normalizedRoot
+        : `${normalizedRoot}${process.platform === "win32" ? "\\" : "/"}`;
+    return normalizedPath.startsWith(prefix);
 }
 /**
  * Symlink-aware version of isWithinPath. Resolves symlinks on both the path

package/dist/core/workspace.d.ts

@@ -11,7 +11,24 @@ export declare const ORCHESTRATOR_FILES: readonly [{
 }, {
     readonly file: "DECISIONS.md";
     readonly template: "decisions-template.md";
+}, {
+    readonly file: "BACKLOG.md";
+    readonly template: "backlog-project.md";
+}, {
+    readonly file: "THREAD_LOG.md";
+    readonly template: "thread-log.md";
 }];
+/**
+ * Copy the packaged template into a target workspace, skipping this
+ * repository's own project state. Directories are still created, so a fresh
+ * workspace has an empty `closeouts/` rather than no `closeouts/`.
+ *
+ * @param targetWorkspaceDir - Absolute path to the `.codecarto/` to create or merge into.
+ * @param sourceWorkspaceDir - The template to copy from. Defaults to the packaged
+ *   template; tests pass a synthetic directory so they can prove the state filter
+ *   without mutating the repository's own live workspace mid-suite.
+ */
+export declare function copyPackagedWorkspace(targetWorkspaceDir: string, sourceWorkspaceDir?: string): Promise<void>;
 /**
  * Seed the orchestrator-maintained files from the workspace's templates
  * (issue #98): orchestration is on by default, so a fresh workspace starts

package/dist/core/workspace.js

@@ -3,7 +3,7 @@
 // + normalizes the per-project workspace state from disk, and provides the
 // atomic status-update primitive used by /codecarto-complete.
 import { existsSync, readFileSync } from "node:fs";
-import { appendFile, copyFile, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { appendFile, copyFile, cp, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { acquireLock, applyHandoff, createEmptyStatus, normalizeStatus, parseHandoff } from "./status.js";
@@ -102,7 +102,71 @@ export async function getWorkspaceState(cwd) {
 export const ORCHESTRATOR_FILES = [
     { file: "CONVENTIONS.md", template: "conventions-template.md" },
     { file: "DECISIONS.md", template: "decisions-template.md" },
+    { file: "BACKLOG.md", template: "backlog-project.md" },
+    { file: "THREAD_LOG.md", template: "thread-log.md" },
 ];
+/**
+ * Project state that must never travel from the packaged template into a new
+ * workspace.
+ *
+ * This repository's `.codecarto/` is two things at once: the template that gets
+ * copied into a user's repo, and CodeCartographer's own live workspace. The
+ * second role writes real project state into it — a backlog of framework
+ * deferrals, a thread log, closeouts of sessions where CodeCartographer
+ * analyzed itself. Copying the tree wholesale handed every new workspace ~40 KB
+ * of another project's history as its own, and the damage was not only clutter:
+ * GUIDE.md keys first-time-project setup on `closeouts/` being empty, so a
+ * shipped closeout told every new session it was not the first to touch the
+ * project, suppressing the orchestrator role that issues #97/#98 made the
+ * default.
+ *
+ * The four top-level files are seeded fresh from templates instead
+ * ({@link ORCHESTRATOR_FILES}); `closeouts/` is created empty.
+ */
+const INIT_EXCLUDED_TOP_LEVEL = new Set(["BACKLOG.md", "THREAD_LOG.md", "CONVENTIONS.md", "DECISIONS.md"]);
+const INIT_EXCLUDED_DIR_CONTENTS = new Set(["closeouts"]);
+// broadside/ is machine-local scan state (state.json, timestamped run dirs)
+// except for its two template files — the same carve-out .codecarto/.gitignore
+// makes for this repository itself. Without this, init from a local checkout
+// with live scan state handed every new workspace another project's runs.
+// Literal rather than an import from broadside.ts, which imports this module.
+const BROADSIDE_DIR_NAME = "broadside";
+const INIT_BROADSIDE_TEMPLATE_FILES = new Set(["SKILL.md", "config.yaml"]);
+/**
+ * Copy the packaged template into a target workspace, skipping this
+ * repository's own project state. Directories are still created, so a fresh
+ * workspace has an empty `closeouts/` rather than no `closeouts/`.
+ *
+ * @param targetWorkspaceDir - Absolute path to the `.codecarto/` to create or merge into.
+ * @param sourceWorkspaceDir - The template to copy from. Defaults to the packaged
+ *   template; tests pass a synthetic directory so they can prove the state filter
+ *   without mutating the repository's own live workspace mid-suite.
+ */
+export async function copyPackagedWorkspace(targetWorkspaceDir, sourceWorkspaceDir = packagedWorkspaceDir) {
+    await cp(sourceWorkspaceDir, targetWorkspaceDir, {
+        recursive: true,
+        filter: (source) => {
+            const relativePath = relative(sourceWorkspaceDir, source);
+            if (!relativePath)
+                return true; // the workspace root itself
+            const segments = relativePath.split(/[\\/]/);
+            if (segments.length === 1)
+                return !INIT_EXCLUDED_TOP_LEVEL.has(segments[0]);
+            if (segments[0] === BROADSIDE_DIR_NAME) {
+                return segments.length === 2 && INIT_BROADSIDE_TEMPLATE_FILES.has(segments[1]);
+            }
+            // Keep the directory, drop what this repository wrote inside it.
+            return !INIT_EXCLUDED_DIR_CONTENTS.has(segments[0]);
+        },
+    });
+    // The published tarball carries no empty directories, so an excluded-contents
+    // directory may not exist to be copied at all. Create them either way: a
+    // workspace whose closeouts/ is missing rather than empty reads differently
+    // to anything that lists it.
+    for (const name of INIT_EXCLUDED_DIR_CONTENTS) {
+        await mkdir(join(targetWorkspaceDir, name), { recursive: true });
+    }
+}
 /**
  * Seed the orchestrator-maintained files from the workspace's templates
  * (issue #98): orchestration is on by default, so a fresh workspace starts
@@ -131,7 +195,9 @@ export async function seedOrchestratorFiles(workspaceDir) {
  * Everything else present in the packaged template is framework-owned.
  */
 const REFRESH_EXCLUDED_TOP_LEVEL = new Set(["BACKLOG.md", "THREAD_LOG.md", "CONVENTIONS.md", "DECISIONS.md"]);
-const REFRESH_EXCLUDED_DIRS = new Set(["scratch", "inputs", "closeouts"]);
+// broadside/ holds machine-local scout state (batch ids, API key config,
+// generated results) — refresh must never overwrite it.
+const REFRESH_EXCLUDED_DIRS = new Set(["scratch", "inputs", "closeouts", "broadside"]);
 const REFRESH_EXCLUDED_WORKFLOW_FILES = new Set(["status.yaml", "config.yaml", ".usage.local.yaml"]);
 async function listTemplateFiles(dir, relativeDir = "") {
     const entries = await readdir(dir, { withFileTypes: true });

package/dist/extensions/codecarto/agent-runner.js

@@ -183,6 +183,12 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
     }
     try {
         await session.prompt(prompt);
+        // If no compaction fired during the run, the promise above would
+        // otherwise strand the continuation path for the full settle timeout
+        // (#129). Settle it with what actually happened — resolve() is
+        // idempotent, so a real compaction_end event earlier in the run
+        // keeps its `true`.
+        resolveCompaction?.(false);
         let primaryOutputPresent = true;
         if (options.primaryOutput) {
             primaryOutputPresent = await primaryOutputExists(cwd, options.primaryOutput);

package/dist/extensions/codecarto/broadside-flags.d.ts

@@ -0,0 +1,21 @@
+import { type BroadsideLensId } from "../../core/index.ts";
+export type BroadsideAction = "submit" | "collect" | "status" | "models";
+export interface BroadsideFlags {
+    action: BroadsideAction;
+    /** Empty means "the repository's default lens set". */
+    lenses: BroadsideLensId[];
+    incremental: boolean;
+    includeSynthesis?: boolean;
+    includeTriage?: boolean;
+    retryTruncated?: boolean;
+    /** Undefined means "use the repository's config default". */
+    maxCost?: number;
+    waitSeconds?: number;
+    benchmarks: boolean;
+    unknown: string[];
+    /** Set on an invalid combination. The caller surfaces it as an error. */
+    error?: string;
+}
+/** Every token the completer offers, in the order it offers them. */
+export declare const KNOWN_BROADSIDE_TOKENS: readonly ["submit", "collect", "status", "models", "architecture", "api", "security", "defect", "conventions", "porting", "--incremental", "--max-cost=", "--wait=", "--no-synthesis", "--no-triage", "--no-retry-truncated", "--benchmarks"];
+export declare function parseBroadsideFlags(args: string): BroadsideFlags;