codecartographer-pi 0.1.2 → 0.1.4

package/README.md

@@ -77,13 +77,24 @@ 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
+- `/codecarto-next` to queue the next eligible phase prompt (or, in sub-agent mode, spawn the phase as a child session)
 - `/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
 - 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
+
+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`:
+
+- **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.
+
+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.
+
+The MCP-server path is unaffected — it has no session concept; the host (Claude Desktop / Claude Code / etc.) is the orchestrator.
+
 ## MCP Server
 
 The same framework is also packaged as a [Model Context Protocol](https://modelcontextprotocol.io) server, so any MCP-compatible host (Claude Code, Claude Desktop, etc.) can drive a CodeCartographer workflow without the Pi runtime. The server imports the same `core/` primitives the Pi extension uses, so phase prompts and validation are byte-identical across both surfaces.

package/dist/core/index.d.ts

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

package/dist/core/index.js

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

package/dist/core/orchestrator.d.ts

@@ -0,0 +1,6 @@
+export interface OrchestratorState {
+    sessionFile: string;
+    sessionId: string;
+}
+export declare function loadOrchestratorState(cwd: string): Promise<OrchestratorState | null>;
+export declare function writeOrchestratorState(cwd: string, state: OrchestratorState): Promise<void>;

package/dist/core/orchestrator.js

@@ -0,0 +1,36 @@
+// Per-machine pointer to the Pi session that runs as the CodeCartographer
+// orchestrator. Stored in `.codecarto/workflow/.orchestrator.local.yaml`
+// (gitignored) so committed `status.yaml` doesn't leak machine-specific
+// session file paths to collaborators.
+//
+// Only the Pi extension writes/reads this — the MCP path has no session
+// concept. When the file is missing or malformed, `/codecarto-next` falls
+// back to in-place phase prompts (legacy 0.1.0–0.1.2 behavior).
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { pathExists } from "./utils.js";
+import { loadYamlFile, stringifySimpleYaml } from "./yaml.js";
+const ORCHESTRATOR_STATE_RELATIVE = "workflow/.orchestrator.local.yaml";
+function orchestratorStatePath(cwd) {
+    return join(cwd, ".codecarto", ORCHESTRATOR_STATE_RELATIVE);
+}
+export async function loadOrchestratorState(cwd) {
+    const path = orchestratorStatePath(cwd);
+    if (!(await pathExists(path)))
+        return null;
+    let data;
+    try {
+        data = await loadYamlFile(path);
+    }
+    catch {
+        return null;
+    }
+    if (!data?.sessionFile || !data?.sessionId)
+        return null;
+    return { sessionFile: data.sessionFile, sessionId: data.sessionId };
+}
+export async function writeOrchestratorState(cwd, state) {
+    const path = orchestratorStatePath(cwd);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${stringifySimpleYaml(state)}\n`, "utf8");
+}

package/dist/extensions/codecarto/index.js

@@ -1,6 +1,6 @@
 import { cp, mkdir, rm, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildThreadLogEntry, buildValidationSummary, canonicalPath, closeoutFileName, createEmptyStatus, dateOnly, DEFAULT_PIPELINE_PATH, ensureCloseoutStub, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadYamlFile, normalizeForComparison, normalizeStatus, packagedWorkspaceDir, pathExists, PIPELINE_ALIASES, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, uniqueStrings, updateStatusAtomically, validatePhaseOutput, } from "../../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildThreadLogEntry, buildValidationSummary, canonicalPath, closeoutFileName, createEmptyStatus, dateOnly, DEFAULT_PIPELINE_PATH, ensureCloseoutStub, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadOrchestratorState, loadYamlFile, normalizeForComparison, normalizeStatus, packagedWorkspaceDir, pathExists, PIPELINE_ALIASES, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, uniqueStrings, updateStatusAtomically, validatePhaseOutput, writeOrchestratorState, } from "../../core/index.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
 const STATUS_LINE_ID = "codecarto-status";
 const SAFE_TOOL_NAMES = ["read", "grep", "find", "ls", "edit", "write"];
@@ -153,6 +153,21 @@ export default function codeCartographerExtension(pi) {
             normalizedStatus.last_updated = new Date().toISOString();
             await writeFile(rawStatusPath, `${stringifySimpleYaml(normalizedStatus)}\n`, "utf8");
             lastFeedbackLines = [`Initialized workspace with pipeline: ${getPipelineLabel(selectedPipelinePath)}`];
+            // Claim the current Pi session as the orchestrator for this workspace.
+            // /codecarto-next will then spawn each phase as a child session, keeping
+            // the orchestrator's context window clean. The pointer is gitignored
+            // (workflow/.orchestrator.local.yaml) so it's machine-local. If we have
+            // no session file (rare; Pi running headless), skip silently — handlers
+            // fall back to in-place phase prompts.
+            const orchestratorSessionFile = ctx.sessionManager.getSessionFile();
+            const orchestratorSessionId = ctx.sessionManager.getSessionId();
+            if (orchestratorSessionFile && orchestratorSessionId) {
+                await writeOrchestratorState(ctx.cwd, {
+                    sessionFile: orchestratorSessionFile,
+                    sessionId: orchestratorSessionId,
+                });
+                lastFeedbackLines.push(`Claimed this session as the orchestrator (${orchestratorSessionId.slice(0, 8)}…).`);
+            }
             ctx.ui.notify(`Initialized CodeCartographer (${getPipelineLabel(selectedPipelinePath)})`, "info");
             await ctx.reload();
             return;
@@ -184,15 +199,71 @@ export default function codeCartographerExtension(pi) {
                 return;
             }
             const prompt = await buildPhasePrompt(state, phase, false);
-            if (ctx.isIdle()) {
-                pi.sendUserMessage(prompt);
+            const orchestrator = await loadOrchestratorState(ctx.cwd);
+            const currentSessionFile = ctx.sessionManager.getSessionFile();
+            // Legacy path: workspace has no orchestrator pointer (created by 0.1.2
+            // or earlier, or Pi has no session file). Queue the prompt in-place
+            // exactly as we did before sub-agent mode existed.
+            if (!orchestrator || !currentSessionFile) {
+                if (ctx.isIdle())
+                    pi.sendUserMessage(prompt);
+                else
+                    pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+                lastFeedbackLines = [`Queued phase prompt for ${phase.id} (in-place; run /codecarto-init to enable sub-agent mode)`];
+                setUiState(ctx, state, lastFeedbackLines);
+                ctx.ui.notify(`Queued CodeCartographer phase: ${phase.id}`, "info");
+                return;
             }
-            else {
-                pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+            // Orchestrator path: we're the parent. Spawn a child session for the
+            // phase so its tool calls and reasoning land in an isolated context.
+            //
+            // SDK contract: after `ctx.newSession()` resolves, `ctx` is invalidated
+            // — touching `ctx.ui` or `ctx.sessionManager` from the outer scope
+            // raises "extension ctx is stale after session replacement". So all
+            // outer-session work (status line, widget) has to happen BEFORE the
+            // call, and any work that needs a fresh ctx happens INSIDE the
+            // `withSession` callback against the new session's ctx.
+            if (currentSessionFile === orchestrator.sessionFile) {
+                lastFeedbackLines = [`Spawned ${phase.id} phase in a sub-agent`];
+                setUiState(ctx, state, lastFeedbackLines);
+                ctx.ui.notify(`CodeCartographer phase: ${phase.id} (sub-agent)`, "info");
+                await ctx.newSession({
+                    parentSession: orchestrator.sessionFile,
+                    withSession: async (childCtx) => {
+                        childCtx.sendUserMessage(prompt);
+                    },
+                });
+                return;
             }
-            lastFeedbackLines = [`Queued phase prompt for ${phase.id}`];
+            // Phase-child path: switch the TUI back to the orchestrator and chain
+            // the next phase atomically. Same staleness rule: pre-switch work uses
+            // `ctx`; post-switch work uses the fresh `orchestratorCtx` passed to
+            // `withSession`. Inside that callback the inner `newSession()` again
+            // invalidates `orchestratorCtx`, so the inner spawn must be the last
+            // thing the callback does.
+            lastFeedbackLines = ["Returning to orchestrator and queuing next phase as a sub-agent"];
             setUiState(ctx, state, lastFeedbackLines);
-            ctx.ui.notify(`Queued CodeCartographer phase: ${phase.id}`, "info");
+            await ctx.switchSession(orchestrator.sessionFile, {
+                withSession: async (orchestratorCtx) => {
+                    const freshState = await getWorkspaceState(orchestratorCtx.cwd);
+                    if (!freshState) {
+                        orchestratorCtx.ui.notify("Workspace state not found after switch.", "error");
+                        return;
+                    }
+                    const nextPhase = getNextEligiblePhase(freshState);
+                    if (!nextPhase) {
+                        orchestratorCtx.ui.notify("All CodeCartographer phases are complete.", "info");
+                        return;
+                    }
+                    const nextPrompt = await buildPhasePrompt(freshState, nextPhase, false);
+                    await orchestratorCtx.newSession({
+                        parentSession: orchestrator.sessionFile,
+                        withSession: async (nextChildCtx) => {
+                            nextChildCtx.sendUserMessage(nextPrompt);
+                        },
+                    });
+                },
+            });
         },
     });
     pi.registerCommand("codecarto-phase", {

package/dist/mcp-server/server.js

@@ -367,7 +367,7 @@ const HANDLERS = {
 };
 // ---------- server bootstrap ----------
 export function buildServer() {
-    const server = new Server({ name: "codecartographer", version: "0.1.2" }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "codecartographer", version: "0.1.4" }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const handler = HANDLERS[request.params.name];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "CodeCartographer packaged for Pi as an extension-driven workflow wrapper.",
   "type": "module",
   "keywords": [