codecartographer-pi 0.1.4 → 0.6.1

package/.codecarto/workflow/config.yaml

@@ -0,0 +1,13 @@
+# CodeCartographer workspace-level orchestrator configuration. Optional.
+# Missing keys fall back to defaults defined in core/orchestrator-config.ts.
+
+orchestrator:
+  # When true, /codecarto-next runs the orchestrator's LLM as a one-shot
+  # rewriter: it reads the previous phase's closeout + the next phase's
+  # template and produces a customized seed prompt for the sub-agent.
+  # Adds orchestrator-side tokens; off by default.
+  #
+  # Per-invocation overrides:
+  #   /codecarto-next --llm-steer       -> force on for this run
+  #   /codecarto-next --no-llm-steer    -> force off for this run
+  llm_steer_next_phase: false

package/README.md

@@ -77,23 +77,36 @@ If you install the whole repository as a Pi package, Pi may still run package in
 What the Pi extension adds:
 
 - `/codecarto-init` to copy `.codecarto/` into the current repository
-- `/codecarto-next` to queue the next eligible phase prompt (or, in sub-agent mode, spawn the phase as a child session)
+- `/codecarto-next [--llm-steer | --no-llm-steer]` to spawn the next eligible phase as a sub-agent (the optional flag opts into the LLM-rewriter for the seed prompt; see *Phase orchestration* below)
 - `/codecarto-status` to show current phase progress
 - `/codecarto-validate` and `/codecarto-complete` for validation-gated status updates
-- a footer/widget showing the active CodeCartographer phase
+- `/codecarto-phase <id>` to force a specific phase even out of pipeline order
+- `/codecarto-skill <name>` to run a post-pipeline skill once all phases are complete
+- `/codecarto-usage` to show cumulative + per-phase token usage from local phase runs (0.6.0+)
+- a footer/widget showing the active CodeCartographer phase, plus a live **Agents** widget above the editor while a phase sub-agent is running
 - tool interception that blocks `edit` and `write` outside `.codecarto/`
 - direct phase prompts that tell Pi exactly which `.codecarto/findings/<phase>/SKILL.md` file to read, without registering those internal files as global Pi skills
 
-### Orchestrator / phase sub-agent mode
+### Phase orchestration (0.2.0 – 0.6.0)
 
-When `/codecarto-init` runs from the Pi extension (0.1.3+), the current Pi session is recorded as the **orchestrator** for that workspace. Each subsequent `/codecarto-next`:
+`/codecarto-next` runs each phase as an isolated `AgentSession` while your TUI stays on the orchestrator session. The phase's tool calls, file reads, and reasoning live in the child's own context window — they never accumulate in the orchestrator. A persistent **Agents** widget appears above the editor while a phase is running, showing live tool count, token usage, elapsed time, and the current activity. The widget auto-clears once the phase finishes (and lingers a few seconds after for visibility).
 
-- **Run from the orchestrator** — spawns a child Pi session pre-seeded with the phase prompt. The TUI switches to the child; phase tool calls and reasoning land in the child's context window, leaving the orchestrator clean.
-- **Run from inside a phase child** — switches the TUI back to the orchestrator and chains the next phase as another child, atomically.
+```
+● CodeCartographer
+└─ ⠹ architecture phase  ⟳ 3 · 5 tool uses · 12.3k tokens · 1m32s
+   ⎿ reading…
+```
+
+Capabilities layered on top of the parallel-widget runner:
+
+- **0.3.0 — file-backed sessions.** Phase sub-agents persist their transcripts to the same `~/.pi/agent/sessions/<encoded-cwd>/` directory the orchestrator uses, so Pi's `/resume`, `/tree`, and `/export` browse them as first-class sessions. The picker shows them with an explicit `CodeCartographer phase: <id>` name and lineage back to the orchestrator's own session.
+- **0.4.0 — phase-completion summary.** When a phase finishes (completed, aborted, or errored), a Markdown closeout block is appended to the orchestrator's transcript via `pi.sendMessage(...)`. You see it in the TUI scrollback; the orchestrator's LLM picks it up as context on your next message. No auto-trigger — control of the next step stays with you.
+- **0.5.0 — opt-in LLM-steered seed prompt.** Set `orchestrator.llm_steer_next_phase: true` in `.codecarto/workflow/config.yaml`, or pass `--llm-steer` per invocation, and the orchestrator's model will run a one-shot rewriter that reads the previous phase's closeout and customizes the next phase's seed prompt to highlight relevant prior findings. Off by default — extra orchestrator-side tokens, opt-in.
+- **0.6.0 — local usage log.** Each phase run is appended to `.codecarto/workflow/.usage.local.yaml` (gitignored). `/codecarto-usage` reports cumulative + per-phase totals. Best-effort logging — write failures don't surface as phase errors.
 
-The orchestrator pointer is stored in `.codecarto/workflow/.orchestrator.local.yaml` (gitignored — the file holds an absolute path into the user's Pi session storage, which is machine-local). Workspaces created by 0.1.0 – 0.1.2 don't have this file; the extension falls back to in-place phase prompts (the legacy behavior). Re-run `/codecarto-init` to opt in.
+Versions 0.1.3 – 0.1.4 used a different design — a session-switching pattern via `ctx.newSession()` that flipped the TUI to the child. That delivered context isolation but the switch was visually invisible during normal flow, so 0.2.0 replaced it with the parallel-widget approach. 0.1.x workspaces don't need migration; existing `.codecarto/` directories work with 0.6.0 unchanged.
 
-The MCP-server path is unaffected — it has no session concept; the host (Claude Desktop / Claude Code / etc.) is the orchestrator.
+The MCP-server path is unaffected — it has no session concept; the host (Claude Desktop / Claude Code / etc.) is always the orchestrator. `/codecarto-usage` is Pi-only; the MCP path doesn't run sub-agents itself, so there's no per-phase usage to track on that side.
 
 ## MCP Server
 

package/dist/core/index.d.ts

@@ -5,4 +5,5 @@ export * from "./status.ts";
 export * from "./pipeline.ts";
 export * from "./prompts.ts";
 export * from "./workspace.ts";
-export * from "./orchestrator.ts";
+export * from "./orchestrator-config.ts";
+export * from "./usage.ts";

package/dist/core/index.js

@@ -8,4 +8,5 @@ export * from "./status.js";
 export * from "./pipeline.js";
 export * from "./prompts.js";
 export * from "./workspace.js";
-export * from "./orchestrator.js";
+export * from "./orchestrator-config.js";
+export * from "./usage.js";

package/dist/core/orchestrator-config.d.ts

@@ -0,0 +1,20 @@
+import type { PathLike } from "node:fs";
+export interface OrchestratorConfig {
+    /** When true, /codecarto-next runs an LLM rewriter to produce a seed prompt
+     *  customized to the previous phase's closeout + the next phase's template
+     *  before spawning the sub-agent. Off by default — extra orchestrator-side
+     *  tokens, opt-in. */
+    llm_steer_next_phase: boolean;
+}
+export interface CodecartoConfig {
+    orchestrator: OrchestratorConfig;
+}
+export declare const CONFIG_RELATIVE_PATH = "workflow/config.yaml";
+type RawConfig = {
+    orchestrator?: Partial<{
+        llm_steer_next_phase: unknown;
+    }>;
+};
+export declare function loadCodecartoConfig(workspaceDir: PathLike): Promise<CodecartoConfig>;
+export declare function mergeConfig(raw: RawConfig | null | undefined): CodecartoConfig;
+export {};

package/dist/core/orchestrator-config.js

@@ -0,0 +1,45 @@
+// Workspace-level orchestrator configuration. Lives at
+// `.codecarto/workflow/config.yaml`. Missing file or missing keys fall back
+// to defaults, so existing workspaces created before this file existed
+// keep working unchanged. Schema is intentionally narrow — one surface
+// per feature, easy to grow.
+import { join } from "node:path";
+import { pathExists } from "./utils.js";
+import { loadYamlFile } from "./yaml.js";
+export const CONFIG_RELATIVE_PATH = "workflow/config.yaml";
+const DEFAULT_CONFIG = {
+    orchestrator: {
+        llm_steer_next_phase: false,
+    },
+};
+export async function loadCodecartoConfig(workspaceDir) {
+    const configPath = join(workspaceDir, CONFIG_RELATIVE_PATH);
+    if (!(await pathExists(configPath)))
+        return cloneDefault();
+    try {
+        const raw = await loadYamlFile(configPath);
+        return mergeConfig(raw);
+    }
+    catch {
+        // Malformed YAML: fall back to defaults rather than failing the
+        // command. The user can fix it; a broken config shouldn't block work.
+        return cloneDefault();
+    }
+}
+export function mergeConfig(raw) {
+    const merged = cloneDefault();
+    if (!raw || typeof raw !== "object")
+        return merged;
+    const o = raw.orchestrator;
+    if (o && typeof o === "object") {
+        if (typeof o.llm_steer_next_phase === "boolean") {
+            merged.orchestrator.llm_steer_next_phase = o.llm_steer_next_phase;
+        }
+    }
+    return merged;
+}
+function cloneDefault() {
+    return {
+        orchestrator: { ...DEFAULT_CONFIG.orchestrator },
+    };
+}

package/dist/core/usage.d.ts

@@ -0,0 +1,31 @@
+export declare const USAGE_RELATIVE_PATH = "workflow/.usage.local.yaml";
+export type UsageRunStatus = "completed" | "aborted" | "error";
+export interface UsageTokens {
+    input: number;
+    output: number;
+    cache_write: number;
+}
+export interface UsageRun {
+    timestamp: string;
+    phase: string;
+    status: UsageRunStatus;
+    turn_count: number;
+    tool_uses: number;
+    duration_ms: number;
+    tokens: UsageTokens;
+    session_file?: string;
+}
+export interface UsageFile {
+    version: number;
+    runs: UsageRun[];
+}
+export interface UsageTotals {
+    runs: number;
+    tokens: UsageTokens;
+    tool_uses: number;
+    duration_ms: number;
+}
+export declare function loadUsage(workspaceDir: string): Promise<UsageFile>;
+export declare function appendUsageRun(workspaceDir: string, run: UsageRun): Promise<void>;
+export declare function computeTotals(file: UsageFile): UsageTotals;
+export declare function computePerPhaseTotals(file: UsageFile): Map<string, UsageTotals>;

package/dist/core/usage.js

@@ -0,0 +1,94 @@
+// Local-only phase usage log. Lives at
+// `.codecarto/workflow/.usage.local.yaml` (gitignored). Append-only —
+// each finished phase sub-agent contributes one entry. Totals are computed
+// on read so the file never holds a number that contradicts the runs.
+//
+// Concurrency: /codecarto-next rejects re-entry on a phase that's already
+// running, and phases run sequentially against this file, so a plain
+// read-modify-write is safe enough. If parallel-phase dispatch ever ships,
+// switch this to atomic-rename (see core/workspace.ts for the pattern).
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathExists } from "./utils.js";
+import { parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
+export const USAGE_RELATIVE_PATH = "workflow/.usage.local.yaml";
+const SCHEMA_VERSION = 1;
+export async function loadUsage(workspaceDir) {
+    const path = join(workspaceDir, USAGE_RELATIVE_PATH);
+    if (!(await pathExists(path)))
+        return emptyUsage();
+    try {
+        const raw = await readFile(path, "utf8");
+        const parsed = parseSimpleYaml(raw);
+        return normalize(parsed);
+    }
+    catch {
+        // Malformed file: treat as empty rather than blocking the user. They
+        // can fix or delete the file; corrupt local state shouldn't stop work.
+        return emptyUsage();
+    }
+}
+export async function appendUsageRun(workspaceDir, run) {
+    const current = await loadUsage(workspaceDir);
+    current.runs.push(run);
+    const path = join(workspaceDir, USAGE_RELATIVE_PATH);
+    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    const serialized = `${stringifySimpleYaml(current)}\n`;
+    await writeFile(tempPath, serialized, "utf8");
+    await rename(tempPath, path);
+}
+export function computeTotals(file) {
+    const totals = {
+        runs: file.runs.length,
+        tokens: { input: 0, output: 0, cache_write: 0 },
+        tool_uses: 0,
+        duration_ms: 0,
+    };
+    for (const r of file.runs) {
+        totals.tokens.input += r.tokens?.input ?? 0;
+        totals.tokens.output += r.tokens?.output ?? 0;
+        totals.tokens.cache_write += r.tokens?.cache_write ?? 0;
+        totals.tool_uses += r.tool_uses ?? 0;
+        totals.duration_ms += r.duration_ms ?? 0;
+    }
+    return totals;
+}
+export function computePerPhaseTotals(file) {
+    const byPhase = new Map();
+    for (const r of file.runs) {
+        const t = byPhase.get(r.phase) ?? {
+            runs: 0,
+            tokens: { input: 0, output: 0, cache_write: 0 },
+            tool_uses: 0,
+            duration_ms: 0,
+        };
+        t.runs += 1;
+        t.tokens.input += r.tokens?.input ?? 0;
+        t.tokens.output += r.tokens?.output ?? 0;
+        t.tokens.cache_write += r.tokens?.cache_write ?? 0;
+        t.tool_uses += r.tool_uses ?? 0;
+        t.duration_ms += r.duration_ms ?? 0;
+        byPhase.set(r.phase, t);
+    }
+    return byPhase;
+}
+function emptyUsage() {
+    return { version: SCHEMA_VERSION, runs: [] };
+}
+function normalize(raw) {
+    if (!raw || typeof raw !== "object")
+        return emptyUsage();
+    const runs = Array.isArray(raw.runs) ? raw.runs.filter(isUsageRun) : [];
+    return {
+        version: typeof raw.version === "number" ? raw.version : SCHEMA_VERSION,
+        runs,
+    };
+}
+function isUsageRun(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const r = x;
+    return (typeof r.timestamp === "string" &&
+        typeof r.phase === "string" &&
+        typeof r.status === "string");
+}

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

@@ -0,0 +1,33 @@
+import { type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type WorkspaceState } from "../../core/index.ts";
+export interface RewritePhasePromptInput {
+    ctx: ExtensionContext;
+    state: WorkspaceState;
+    originalPrompt: string;
+    nextPhaseId: string;
+}
+export interface RewritePhasePromptResult {
+    prompt: string;
+    used: boolean;
+    skipReason?: string;
+    /** ID of the previous phase whose closeout the rewriter read, when used. */
+    prevPhaseId?: string;
+}
+/**
+ * Run the rewriter and return the customized seed prompt. On any failure
+ * (no prior phase, missing closeout, rewriter session error, empty output)
+ * returns the original prompt with `used: false` and a skip reason — never
+ * throws. The caller decides what to surface to the user.
+ */
+export declare function rewritePhasePrompt(input: RewritePhasePromptInput): Promise<RewritePhasePromptResult>;
+/**
+ * Build the markdown block injected into the orchestrator's session
+ * (via pi.sendMessage with customType "codecarto-steering") whenever the
+ * rewriter produces a customized seed. Lets the user audit what the
+ * rewriter chose to emphasize before the phase sub-agent starts.
+ */
+export declare function buildSteeringMessage(input: {
+    nextPhaseId: string;
+    prevPhaseId?: string;
+    rewrittenPrompt: string;
+}): string;

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

@@ -0,0 +1,169 @@
+// Optional LLM-steered prompt rewriter for /codecarto-next.
+//
+// When enabled (workspace config `orchestrator.llm_steer_next_phase: true`,
+// or per-invocation `--llm-steer`), this runs a one-shot in-memory
+// AgentSession on the orchestrator's model with no tools. It receives the
+// stock phase prompt + the previous phase's closeout (if any) and returns
+// a customized seed prompt that acknowledges the prior findings.
+//
+// Off by default. The orchestrator's tokens stay yours unless you opt in.
+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 { closeoutFileName, pathExists } from "../../core/index.js";
+/** Closeout content over this many bytes is truncated before being passed to
+ *  the rewriter. Keeps the orchestrator-side cost predictable. */
+const CLOSEOUT_BYTE_BUDGET = 8000;
+/**
+ * Run the rewriter and return the customized seed prompt. On any failure
+ * (no prior phase, missing closeout, rewriter session error, empty output)
+ * returns the original prompt with `used: false` and a skip reason — never
+ * throws. The caller decides what to surface to the user.
+ */
+export async function rewritePhasePrompt(input) {
+    const { ctx, state, originalPrompt, nextPhaseId } = input;
+    const prevPhaseId = findPreviousPhaseId(state, nextPhaseId);
+    if (!prevPhaseId) {
+        return { prompt: originalPrompt, used: false, skipReason: "no previous phase to steer from" };
+    }
+    const closeout = await readLatestCloseout(state.workspaceDir, prevPhaseId);
+    if (!closeout) {
+        return { prompt: originalPrompt, used: false, skipReason: `no closeout found for ${prevPhaseId}` };
+    }
+    const rewriterPrompt = buildRewriterPrompt({
+        nextPhaseId,
+        prevPhaseId,
+        originalPrompt,
+        prevCloseout: closeout,
+    });
+    let customized;
+    try {
+        customized = await runRewriterOnce(ctx, rewriterPrompt);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { prompt: originalPrompt, used: false, skipReason: `rewriter session failed: ${message}` };
+    }
+    const trimmed = customized.trim();
+    if (!trimmed) {
+        return { prompt: originalPrompt, used: false, skipReason: "rewriter returned empty output" };
+    }
+    return { prompt: trimmed, used: true, prevPhaseId };
+}
+/**
+ * Build the markdown block injected into the orchestrator's session
+ * (via pi.sendMessage with customType "codecarto-steering") whenever the
+ * rewriter produces a customized seed. Lets the user audit what the
+ * rewriter chose to emphasize before the phase sub-agent starts.
+ */
+export function buildSteeringMessage(input) {
+    const provenance = input.prevPhaseId
+        ? `customized by the orchestrator's LLM from \`${input.prevPhaseId}\`'s closeout`
+        : "customized by the orchestrator's LLM";
+    return [
+        `**Steering: \`${input.nextPhaseId}\` seed prompt**`,
+        "",
+        `_${provenance}. The phase sub-agent will receive the prompt below as its first user message._`,
+        "",
+        "---",
+        "",
+        input.rewrittenPrompt,
+    ].join("\n");
+}
+function findPreviousPhaseId(state, nextPhaseId) {
+    const order = state.pipeline.phase_order;
+    const idx = order.indexOf(nextPhaseId);
+    if (idx <= 0)
+        return undefined;
+    for (let i = idx - 1; i >= 0; i--) {
+        if (state.status.phases[order[i]]?.status === "complete")
+            return order[i];
+    }
+    return undefined;
+}
+async function readLatestCloseout(workspaceDir, phaseId) {
+    const closeoutsDir = join(workspaceDir, "closeouts");
+    if (!(await pathExists(closeoutsDir)))
+        return undefined;
+    let entries;
+    try {
+        entries = await readdir(closeoutsDir);
+    }
+    catch {
+        return undefined;
+    }
+    const suffix = closeoutFileName("", phaseId).replace(/^-/, ""); // "<phaseId>.md"
+    const matches = entries.filter((name) => name.endsWith(`-${suffix}`)).sort();
+    const latest = matches.at(-1);
+    if (!latest)
+        return undefined;
+    const raw = await readFile(join(closeoutsDir, latest), "utf8");
+    if (raw.length <= CLOSEOUT_BYTE_BUDGET)
+        return raw;
+    return `${raw.slice(0, CLOSEOUT_BYTE_BUDGET)}\n\n[…closeout truncated for rewriter input…]`;
+}
+function buildRewriterPrompt(input) {
+    return [
+        `You are seeding a sub-agent for the \`${input.nextPhaseId}\` phase of a CodeCartographer pipeline.`,
+        `The previous phase \`${input.prevPhaseId}\` just completed. Read its closeout below and produce a CUSTOMIZED seed prompt for the next phase's sub-agent.`,
+        "",
+        "Constraints for the customized prompt:",
+        `- Stay faithful to the original ${input.nextPhaseId} phase template; do not change its structure, required outputs, or completion criteria.`,
+        `- Add a short \"context from ${input.prevPhaseId}\" preamble that names the specific findings, open questions, or carry-forward items from the closeout that the ${input.nextPhaseId} phase should pay attention to.`,
+        "- Do not invent findings the closeout does not state.",
+        "- Do not add commentary directed at the user; the output is the sub-agent's seed prompt.",
+        "",
+        "Output ONLY the customized seed prompt as plain Markdown. No preface, no fenced code blocks, no commentary.",
+        "",
+        "=== ORIGINAL NEXT-PHASE PROMPT ===",
+        input.originalPrompt,
+        "=== END ORIGINAL NEXT-PHASE PROMPT ===",
+        "",
+        `=== PREVIOUS PHASE (${input.prevPhaseId}) CLOSEOUT ===`,
+        input.prevCloseout,
+        `=== END PREVIOUS PHASE (${input.prevPhaseId}) CLOSEOUT ===`,
+    ].join("\n");
+}
+async function runRewriterOnce(ctx, prompt) {
+    const cwd = ctx.cwd;
+    const agentDir = getAgentDir();
+    const loader = new DefaultResourceLoader({
+        cwd,
+        agentDir,
+        // Even more stripped than the phase runner: no extensions either,
+        // since the rewriter has no tools and shouldn't pick up codecarto's
+        // tool-interception (it has no tools to intercept).
+        noExtensions: true,
+        noSkills: true,
+        noPromptTemplates: true,
+        noThemes: true,
+        noContextFiles: true,
+    });
+    await loader.reload();
+    const { session } = await createAgentSession({
+        cwd,
+        agentDir,
+        sessionManager: SessionManager.inMemory(cwd),
+        settingsManager: SettingsManager.create(cwd, agentDir),
+        modelRegistry: ctx.modelRegistry,
+        model: ctx.model,
+        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);
+        }
+        const joined = parts.join("\n").trim();
+        if (joined)
+            return joined;
+    }
+    return "";
+}

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

@@ -0,0 +1,44 @@
+import { type AgentSession, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+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;
+    onTurnEnd?: (turnCount: number) => void;
+    onMessageEnd?: (usage: {
+        input: number;
+        output: number;
+        cacheWrite: number;
+    }) => void;
+}
+export interface PhaseRunOptions {
+    /** Display name written via appendSessionInfo so the session shows up in
+     *  /resume's picker as e.g. "CodeCartographer phase: blueprint". Pi reads
+     *  it via SessionManager.getSessionName(). */
+    sessionName?: string;
+}
+export interface PhaseRunResult {
+    session: AgentSession;
+    responseText: string;
+    toolUses: number;
+    turnCount: number;
+    aborted: boolean;
+    /** Path to the on-disk session file (under ~/.pi/agent/sessions/<encoded-cwd>/).
+     *  Stable across the run; useful for /codecarto-usage and any future tooling
+     *  that wants to point at the phase's transcript. */
+    sessionFile: string | undefined;
+}
+/**
+ * Run one CodeCartographer phase as an isolated AgentSession. Awaiting this
+ * function blocks until the phase completes (or aborts via signal). The
+ * orchestrator's TUI stays active throughout — only the phase's own context
+ * window holds the tool calls and reasoning.
+ *
+ * The phase session is **persisted** to the default Pi session directory
+ * (`~/.pi/agent/sessions/<encoded-cwd>/`), the same directory the orchestrator
+ * uses, so Pi's `/resume`, `/tree`, and `/export` see phase transcripts as
+ * first-class sessions. They're tagged via `appendSessionInfo` (display name)
+ * and `parentSession` (the orchestrator's session file path) so the picker
+ * shows lineage.
+ */
+export declare function runPhase(ctx: ExtensionContext, prompt: string, callbacks?: PhaseRunCallbacks, options?: PhaseRunOptions, signal?: AbortSignal): Promise<PhaseRunResult>;