codecartographer-pi 0.19.5 → 0.20.0

package/dist/core/yaml.js

@@ -71,6 +71,55 @@ function findKeySeparator(text) {
     }
     return -1;
 }
+/**
+ * Whether a line's content is a mapping entry in YAML's sense: a key followed
+ * by `:` and then a space or the end of the line. `findKeySeparator` alone
+ * finds any bare colon, which would read a wrapped value such as
+ * `see https://example.com` as a key.
+ */
+function looksLikeMappingEntry(text) {
+    const separator = findKeySeparator(text);
+    if (separator === -1)
+        return false;
+    const next = text[separator + 1];
+    return next === undefined || next === " " || next === "\t";
+}
+function looksLikeSequenceItem(text) {
+    return text.startsWith("- ") || text === "-";
+}
+/**
+ * Whether the scalar text is plain: unquoted, and not a block indicator. Only
+ * a plain scalar can continue onto more-indented lines.
+ */
+function isPlainScalarText(text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return false;
+    if (trimmed.startsWith('"') || trimmed.startsWith("'"))
+        return false;
+    if (trimmed.startsWith("[") || trimmed.startsWith("{"))
+        return false;
+    return true;
+}
+/**
+ * Fold a plain scalar's first line with its continuation lines: a single line
+ * break becomes a space and a run of k blank lines becomes k newlines, as for
+ * a folded block scalar.
+ */
+function foldPlainScalar(first, continuation) {
+    let result = first;
+    let pendingBreaks = 0;
+    for (const line of continuation) {
+        if (line === "") {
+            pendingBreaks++;
+            continue;
+        }
+        result += pendingBreaks > 0 ? "\n".repeat(pendingBreaks) : " ";
+        pendingBreaks = 0;
+        result += line;
+    }
+    return result;
+}
 export function parseYamlScalar(rawValue) {
     const trimmed = stripYamlComment(rawValue).trim();
     if (trimmed === "")
@@ -163,10 +212,70 @@ function applyBlockScalar(blockLines, header) {
 export function parseSimpleYaml(raw) {
     const lines = raw.split(/\r?\n/);
     let index = 0;
+    /**
+     * Every parse error names the line it failed on, quotes it, and says which
+     * construct was expected: a model writing a handoff has to be able to tell
+     * a parser limitation from its own mistake (#246).
+     */
+    const fail = (at, message) => {
+        throw new Error(`YAML line ${at + 1}: ${message} — "${(lines[at] ?? "").trim()}"`);
+    };
+    // YAML indents with spaces only. A tab was counted as two columns and then
+    // sliced as one character, so `\tkey: v` parsed as the key "" — garbage
+    // rather than an error.
+    for (let at = 0; at < lines.length; at++) {
+        if (/^ *\t/.test(lines[at] ?? "") && !isBlankOrComment(lines[at] ?? "")) {
+            fail(at, "tabs are not allowed in YAML indentation; use spaces");
+        }
+    }
     const skipBlank = () => {
         while (index < lines.length && isBlankOrComment(lines[index] ?? ""))
             index++;
     };
+    /**
+     * Consume the continuation lines of a plain scalar that began on the line
+     * just consumed: lines indented deeper than `baseIndent` that are neither
+     * a mapping entry nor a sequence item nor a comment. A wrapped
+     * `closeout_summary:` is exactly this shape, and it used to fail the
+     * indentation check with a message that blamed whitespace (#246, probe D).
+     * Blank lines inside the run are kept (they fold to newlines); trailing
+     * blank lines are left for the caller.
+     */
+    const collectPlainContinuation = (baseIndent) => {
+        const collected = [];
+        let pendingBlank = 0;
+        let cursor = index;
+        while (cursor < lines.length) {
+            const candidate = lines[cursor] ?? "";
+            if (candidate.trim() === "") {
+                pendingBlank++;
+                cursor++;
+                continue;
+            }
+            const candidateIndent = countIndent(candidate);
+            if (candidateIndent <= baseIndent)
+                break;
+            const text = candidate.slice(candidateIndent);
+            if (text.startsWith("#") || looksLikeSequenceItem(text) || looksLikeMappingEntry(text))
+                break;
+            for (let i = 0; i < pendingBlank; i++)
+                collected.push("");
+            pendingBlank = 0;
+            collected.push(stripYamlComment(text).trim());
+            cursor++;
+            index = cursor;
+        }
+        return collected;
+    };
+    /** A scalar value read from `rawValue`, folded with any continuation lines. */
+    const parseScalarWithContinuation = (rawValue, baseIndent) => {
+        if (!isPlainScalarText(rawValue))
+            return parseYamlScalar(rawValue);
+        const continuation = collectPlainContinuation(baseIndent);
+        if (continuation.length === 0)
+            return parseYamlScalar(rawValue);
+        return foldPlainScalar(stripYamlComment(rawValue).trim(), continuation);
+    };
     /**
      * Read the body of a block scalar that opened on the line just consumed.
      * Shared by mapping values (`key: >-`) and sequence items (`- >-`): when only
@@ -228,34 +337,58 @@ export function parseSimpleYaml(raw) {
             if (lineIndent < indent)
                 break;
             if (lineIndent > indent) {
-                throw new Error(`Invalid YAML indentation near: ${line.trim()}`);
+                fail(index, `this line is indented ${lineIndent} columns but the mapping it belongs to starts at column ${indent}; a sibling key must align with the first key, and a wrapped value must not contain ": "`);
             }
             const trimmed = line.slice(indent);
-            if (trimmed.startsWith("- ") || trimmed === "-")
-                break;
+            if (looksLikeSequenceItem(trimmed)) {
+                // A list that is a key's value is consumed by that key's branch
+                // below before the loop ever sees it, so a dash here has no key.
+                fail(index, "a sequence item where a mapping entry was expected; a list that belongs to the key above must be indented under it, or sit at that key's own column");
+            }
             const separator = findKeySeparator(trimmed);
             if (separator === -1) {
-                throw new Error(`Invalid YAML mapping entry: ${trimmed}`);
+                fail(index, 'expected a mapping entry ("key: value")');
             }
             const key = trimmed.slice(0, separator).trim();
             const rawValue = trimmed.slice(separator + 1).trim();
-            index++;
             if (seen.has(key)) {
-                throw new Error(`Duplicate YAML key: ${key} near line: ${line.trim()}`);
+                fail(index, `Duplicate YAML key: ${key}`);
             }
             seen.add(key);
+            index++;
             const blockHeader = parseBlockScalarHeader(rawValue);
             if (blockHeader) {
                 assign(key, applyBlockScalar(collectBlockScalarLines(indent), blockHeader));
                 continue;
             }
             if (rawValue !== "") {
-                assign(key, parseYamlScalar(rawValue));
+                assign(key, parseScalarWithContinuation(rawValue, indent));
                 continue;
             }
             skipBlank();
-            if (index < lines.length && countIndent(lines[index] ?? "") > indent) {
-                assign(key, parseBlock(countIndent(lines[index] ?? "")));
+            if (index >= lines.length) {
+                assign(key, null);
+                continue;
+            }
+            const nextLine = lines[index] ?? "";
+            const nextIndent = countIndent(nextLine);
+            if (nextIndent > indent) {
+                const nextText = nextLine.slice(nextIndent);
+                if (looksLikeMappingEntry(nextText) || looksLikeSequenceItem(nextText)) {
+                    assign(key, parseBlock(nextIndent));
+                }
+                else {
+                    // A scalar that starts on the line after its key
+                    // (`summary:` / `  The phase mapped…`), wrapped or not.
+                    index++;
+                    assign(key, parseScalarWithContinuation(nextText, indent));
+                }
+            }
+            else if (nextIndent === indent && looksLikeSequenceItem(nextLine.slice(nextIndent))) {
+                // YAML lets a block sequence sit at the same indent as the key it
+                // belongs to (`items:` / `- a`). This read as `items: null` and
+                // then, at the top level, dropped every line after it (#246).
+                assign(key, parseSequence(indent));
             }
             else {
                 assign(key, null);
@@ -286,8 +419,17 @@ export function parseSimpleYaml(raw) {
             index++;
             if (rawItem === "") {
                 skipBlank();
-                if (index < lines.length && countIndent(lines[index] ?? "") > indent) {
-                    result.push(parseBlock(countIndent(lines[index] ?? "")));
+                const nextLine = lines[index] ?? "";
+                const nextIndent = countIndent(nextLine);
+                if (index < lines.length && nextIndent > indent) {
+                    const nextText = nextLine.slice(nextIndent);
+                    if (looksLikeMappingEntry(nextText) || looksLikeSequenceItem(nextText)) {
+                        result.push(parseBlock(nextIndent));
+                    }
+                    else {
+                        index++;
+                        result.push(parseScalarWithContinuation(nextText, indent));
+                    }
                 }
                 else {
                     result.push(null);
@@ -299,12 +441,21 @@ export function parseSimpleYaml(raw) {
                 result.push(applyBlockScalar(collectBlockScalarLines(indent), itemBlockHeader));
                 continue;
             }
+            if (looksLikeSequenceItem(rawItem)) {
+                // A sequence item that is itself a sequence (`- - a`). Rewrite the
+                // line as the inner item at its own column and parse a block there,
+                // so the inner sequence's later items (`    - b`) find their first.
+                index--;
+                lines[index] = `${" ".repeat(itemIndent)}${afterDash.trimStart()}`;
+                result.push(parseBlock(itemIndent));
+                continue;
+            }
             const separator = findKeySeparator(rawItem);
             if (separator !== -1) {
                 const key = rawItem.slice(0, separator).trim();
                 const rawValue = rawItem.slice(separator + 1).trim();
                 const item = {};
-                item[key] = rawValue === "" ? null : parseYamlScalar(rawValue);
+                item[key] = rawValue === "" ? null : parseScalarWithContinuation(rawValue, indent);
                 skipBlank();
                 if (rawValue === "" && index < lines.length && countIndent(lines[index] ?? "") > indent + 1) {
                     item[key] = parseBlock(countIndent(lines[index] ?? ""));
@@ -317,14 +468,22 @@ export function parseSimpleYaml(raw) {
                 result.push(item);
                 continue;
             }
-            result.push(parseYamlScalar(rawItem));
+            result.push(parseScalarWithContinuation(rawItem, indent));
         }
         return result;
     };
     skipBlank();
     if (index >= lines.length)
         return {};
-    return parseBlock(countIndent(lines[index] ?? ""));
+    const document = parseBlock(countIndent(lines[index] ?? ""));
+    // A top-level block that ends before the input does used to leave the rest
+    // unread and unreported — a mapping followed by a stray `- item` silently
+    // lost everything from that line on (#246).
+    skipBlank();
+    if (index < lines.length) {
+        fail(index, "unexpected content after the document's top-level block ended (is this line indented like its neighbours?)");
+    }
+    return document;
 }
 export function formatYamlScalar(value) {
     if (value === null)

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

@@ -10,6 +10,7 @@
 import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { disposeChildSession } from "./agent-runner.js";
 import { closeoutFileName, pathExists } from "../../core/index.js";
 import { createChildModelRuntime } from "./child-model-runtime.js";
 /** Closeout content over this many bytes is truncated before being passed to
@@ -151,20 +152,26 @@ async function runRewriterOnce(ctx, prompt) {
         tools: [],
         resourceLoader: loader,
     });
-    await session.prompt(prompt);
-    for (let i = session.messages.length - 1; i >= 0; i--) {
-        const msg = session.messages[i];
-        if (msg.role !== "assistant")
-            continue;
-        const blocks = msg.content;
-        const parts = [];
-        for (const c of blocks) {
-            if (c.type === "text" && c.text)
-                parts.push(c.text);
+    try {
+        await session.prompt(prompt);
+        for (let i = session.messages.length - 1; i >= 0; i--) {
+            const msg = session.messages[i];
+            if (msg.role !== "assistant")
+                continue;
+            const blocks = msg.content;
+            const parts = [];
+            for (const c of blocks) {
+                if (c.type === "text" && c.text)
+                    parts.push(c.text);
+            }
+            const joined = parts.join("\n").trim();
+            if (joined)
+                return joined;
         }
-        const joined = parts.join("\n").trim();
-        if (joined)
-            return joined;
+        return "";
+    }
+    finally {
+        // One prompt, one answer; the child has nothing left to do (#256).
+        disposeChildSession(session);
     }
-    return "";
 }

package/dist/extensions/codecarto/agent-runner.d.ts

@@ -11,7 +11,6 @@ export declare function primaryOutputExists(cwd: string, primaryOutput: string):
 export declare function buildPhaseContinuationPrompt(compacted: boolean): string;
 export declare function waitForCompaction(compactionCompleted: Promise<boolean>, timeoutMs?: number): Promise<boolean>;
 export interface PhaseRunCallbacks {
-    onSessionCreated?: (session: AgentSession) => void;
     onToolStart?: (toolCallId: string, toolName: string) => void;
     onToolEnd?: (toolCallId: string, toolName: string) => void;
     onTextDelta?: (delta: string, fullText: string) => void;
@@ -37,7 +36,6 @@ export interface PhaseRunOptions {
     primaryOutput?: string;
 }
 export interface PhaseRunResult {
-    session: AgentSession;
     responseText: string;
     toolUses: number;
     turnCount: number;
@@ -61,3 +59,9 @@ export interface PhaseRunResult {
  * shows lineage.
  */
 export declare function runPhase(ctx: ExtensionContext, prompt: string, callbacks?: PhaseRunCallbacks, options?: PhaseRunOptions, signal?: AbortSignal): Promise<PhaseRunResult>;
+/**
+ * Dispose a child session, swallowing whatever dispose throws: the work is
+ * done and its result is already in hand, so a failing cleanup hook must not
+ * turn a finished phase into an error.
+ */
+export declare function disposeChildSession(session: Pick<AgentSession, "dispose">): void;

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

@@ -113,7 +113,6 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
         resourceLoader: loader,
     });
     await session.bindExtensions({});
-    callbacks.onSessionCreated?.(session);
     let toolUses = 0;
     let turnCount = 0;
     let currentMessageText = "";
@@ -200,19 +199,38 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
             if (!aborted)
                 await session.prompt(buildPhaseContinuationPrompt(compacted));
         }
+        return {
+            responseText: getLastAssistantText(session) || currentMessageText,
+            toolUses,
+            turnCount,
+            aborted,
+            sessionFile: sessionManager.getSessionFile(),
+        };
     }
     finally {
         unsubscribe();
         abortCleanup();
+        // The child is done, on every path. Dispose aborts whatever it still
+        // has in flight, drops its agent subscription and listeners, and runs
+        // the per-session resource cleanups extensions registered — a seven
+        // phase auto run used to keep all of that for every phase, rewrite,
+        // and narration until the process exited (#256). Nothing reads the
+        // session after this: the result carries the text and the file path.
+        disposeChildSession(session);
+    }
+}
+/**
+ * Dispose a child session, swallowing whatever dispose throws: the work is
+ * done and its result is already in hand, so a failing cleanup hook must not
+ * turn a finished phase into an error.
+ */
+export function disposeChildSession(session) {
+    try {
+        session.dispose();
+    }
+    catch {
+        // nothing to do with a cleanup failure but move on
     }
-    return {
-        session,
-        responseText: getLastAssistantText(session) || currentMessageText,
-        toolUses,
-        turnCount,
-        aborted,
-        sessionFile: sessionManager.getSessionFile(),
-    };
 }
 /**
  * Walk session.messages backward to find the last non-empty assistant text.

package/dist/extensions/codecarto/agent-state.d.ts

@@ -1,4 +1,3 @@
-import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { type CompactionTelemetry } from "../../core/usage.ts";
 export type PhaseStatus = "running" | "completed" | "error" | "aborted";
 export interface PhaseActivity {
@@ -20,7 +19,6 @@ export interface PhaseActivity {
     };
     /** Compaction outcomes observed during this phase session. */
     compactions: CompactionTelemetry;
-    session?: AgentSession;
     error?: string;
 }
 export declare function getPhaseActivity(phaseId: string): PhaseActivity | undefined;

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

@@ -17,8 +17,7 @@ import { clearPhase, finishPhase, getPhaseActivity, startPhase } from "./agent-s
 import { buildSteeringMessage, rewritePhasePrompt } from "./agent-rewriter.js";
 import { buildPhaseSummary } from "./agent-summary.js";
 import { getAgentsWidget } from "./agent-widget.js";
-import { writeDashboard } from "./dashboard-writer.js";
-import { appendUsageRun, buildPhasePrompt, buildValidationSummary, completeValidatedPhase, formatMillis, formatTokenCount, getNextEligiblePhase, getWorkspaceState, loadCodecartoConfig, PACKAGE_VERSION, PhasePreflightError, runPhasePreflight, validatePhaseOutput, } from "../../core/index.js";
+import { appendUsageRun, buildPhasePrompt, buildValidationSummary, completeValidatedPhase, formatMillis, formatTokenCount, getNextEligiblePhase, getWorkspaceState, describeConfigProblems, loadCodecartoConfig, PACKAGE_VERSION, PhasePreflightError, runPhasePreflight, validatePhaseOutput, writeDashboard, } from "../../core/index.js";
 /**
  * Run one phase end to end: optional LLM-steered rewrite, spawn the sub-agent,
  * wait for it, then emit the side effects the historical /codecarto-next chain
@@ -60,7 +59,6 @@ export async function runSinglePhase(ctx, pi, state, phase, options) {
         getAgentsWidget().attach(ctx.ui);
     try {
         const result = await runPhase(ctx, prompt, {
-            onSessionCreated: (session) => { activity.session = session; },
             onToolStart: (id, name) => { activity.activeTools.set(id, name); activity.toolUses++; },
             onToolEnd: (id) => { activity.activeTools.delete(id); },
             onTextDelta: (_delta, fullText) => { activity.responseText = fullText; },
@@ -101,7 +99,9 @@ export async function runSinglePhase(ctx, pi, state, phase, options) {
             display: true,
         });
         void recordUsage(state.workspaceDir, phase.id, status, activity, result.sessionFile);
-        void writeDashboard(ctx.cwd, PACKAGE_VERSION);
+        // The phase's sub-agent replaced the session, so reading ctx.cwd here
+        // would throw (#201); the state captured before the run has the root.
+        void writeDashboard(state.cwd, PACKAGE_VERSION);
         return {
             status: result.aborted ? "aborted" : "completed",
             activity,
@@ -128,7 +128,7 @@ export async function runSinglePhase(ctx, pi, state, phase, options) {
             display: true,
         });
         void recordUsage(state.workspaceDir, phase.id, "error", activity);
-        void writeDashboard(ctx.cwd, PACKAGE_VERSION);
+        void writeDashboard(state.cwd, PACKAGE_VERSION);
         return { status: "error", activity, error: message };
     }
     finally {
@@ -190,6 +190,10 @@ export async function runAuto(ctx, pi, initialState, options) {
     const totalTokens = { input: 0, output: 0, cacheWrite: 0 };
     const totalPhases = initialState.pipeline.phase_order.length;
     const config = await loadCodecartoConfig(initialState.workspaceDir);
+    // Once, before the loop: a dropped config file changes what this run does
+    // (the steer toggle lives there) and nothing else in the loop reads it.
+    if (config.problems.length > 0)
+        notifyCtx(ctx, describeConfigProblems(config).join("\n"), "warning");
     const llmSteerEnabled = options.llmSteerOverride ?? config.orchestrator.llm_steer_next_phase;
     let state = initialState;
     while (true) {
@@ -241,7 +245,7 @@ export async function runAuto(ctx, pi, initialState, options) {
         if (phaseResult.status === "completed") {
             // State must be refreshed because the sub-agent may have written
             // findings to disk that the validator reads.
-            const stateForValidation = (await getWorkspaceState(ctx.cwd)) ?? state;
+            const stateForValidation = (await getWorkspaceState(autoCwd)) ?? state;
             validation = await validatePhaseOutput(stateForValidation, phase.id);
         }
         const decision = decideAfterPhase(phaseResult.status, phaseResult.error, validation, options.strict);

package/dist/extensions/codecarto/dashboard-narrator.js

@@ -10,10 +10,11 @@
 //
 // Same one-shot pattern as agent-rewriter.ts:runRewriterOnce — different
 // system prompt, different output target. Never throws.
-import { readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
-import { computeTotals, NARRATION_CACHE_RELATIVE_PATH, loadUsage, pathExists, stringifySimpleYaml, } from "../../core/index.js";
+import { disposeChildSession } from "./agent-runner.js";
+import { atomicWriteFile, computeTotals, NARRATION_CACHE_RELATIVE_PATH, loadUsage, pathExists, stringifySimpleYaml, } from "../../core/index.js";
 import { createChildModelRuntime } from "./child-model-runtime.js";
 // Per-closeout byte budget when stuffing the narrator's input. Three
 // closeouts × 4 KB each ≈ 12 KB of prompt context, which is well under any
@@ -133,10 +134,7 @@ async function writeNarrationCache(workspaceDir, content, phaseCount) {
     const generatedAt = new Date().toISOString();
     const frontmatter = stringifySimpleYaml({ generatedAt, phaseCountAtGeneration: phaseCount });
     const body = `---\n${frontmatter}\n---\n${content}\n`;
-    const path = join(workspaceDir, NARRATION_CACHE_RELATIVE_PATH);
-    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, body, "utf8");
-    await rename(tempPath, path);
+    await atomicWriteFile(join(workspaceDir, NARRATION_CACHE_RELATIVE_PATH), body);
 }
 async function runNarratorOnce(ctx, prompt) {
     const cwd = ctx.cwd;
@@ -161,8 +159,14 @@ async function runNarratorOnce(ctx, prompt) {
         tools: [],
         resourceLoader: loader,
     });
-    await session.prompt(prompt);
-    return getLastAssistantText(session);
+    try {
+        await session.prompt(prompt);
+        return getLastAssistantText(session);
+    }
+    finally {
+        // One prompt, one answer; the child has nothing left to do (#256).
+        disposeChildSession(session);
+    }
 }
 function getLastAssistantText(session) {
     for (let i = session.messages.length - 1; i >= 0; i--) {

package/dist/extensions/codecarto/dashboard-writer.d.ts

@@ -1,8 +1 @@
-/**
- * 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>;
+export { writeDashboard } from "../../core/dashboard-writer.ts";