pi-forge 1.2.3 → 1.2.5

package/dist/server/routes/quick-actions.js

@@ -0,0 +1,384 @@
+import { spawn } from "node:child_process";
+import { config } from "../config.js";
+import { getProject } from "../project-manager.js";
+import { scrubbedEnv } from "../pty-manager.js";
+import { createQuickAction, DEFAULT_TIMEOUT_MS, deleteQuickAction, getQuickAction, isCommandAction, isPromptAction, MAX_COMMAND_BYTES, MAX_PROMPT_BYTES, MAX_TIMEOUT_MS, QuickActionNotFoundError, readQuickActions, updateQuickAction, } from "../quick-actions.js";
+import { errorSchema } from "./_schemas.js";
+/**
+ * Wire shape — same on the way in (POST/PUT body) and out
+ * (GET response). Discriminator is presence of `command` vs `text`;
+ * the validator below rejects both/neither with 400.
+ */
+const quickActionSchema = {
+    type: "object",
+    required: ["id", "name"],
+    properties: {
+        id: { type: "string" },
+        name: { type: "string" },
+        enabled: { type: "boolean" },
+        command: { type: "string" },
+        timeoutMs: { type: "integer" },
+        text: { type: "string" },
+        mode: { type: "string", enum: ["send", "insert"] },
+    },
+};
+const runResultSchema = {
+    type: "object",
+    required: ["success", "exitCode", "stdout", "stderr", "durationMs", "timedOut", "truncated"],
+    properties: {
+        success: { type: "boolean" },
+        exitCode: { type: ["integer", "null"] },
+        stdout: { type: "string" },
+        stderr: { type: "string" },
+        durationMs: { type: "integer" },
+        timedOut: { type: "boolean" },
+        truncated: { type: "boolean" },
+    },
+};
+/** Per-stream output cap. A chip that prints 100 MB of node_modules
+ * paths shouldn't drag the request handler down — truncate and flag
+ * it; the user can re-run in the integrated terminal if they need the
+ * full output. */
+const MAX_OUTPUT_BYTES = 1_000_000;
+/**
+ * Normalise + validate one wire body into a QuickAction-shaped patch.
+ * Centralises the one-of discriminator + byte caps so POST and PUT
+ * both produce identical 400s on the same bad input.
+ */
+function validateBody(body, reply) {
+    const trimmedName = body.name.trim();
+    if (trimmedName.length === 0) {
+        reply.code(400).send({ error: "invalid_name" });
+        return undefined;
+    }
+    const hasCmd = typeof body.command === "string" && body.command.length > 0;
+    const hasText = typeof body.text === "string" && body.text.length > 0;
+    if (hasCmd === hasText) {
+        reply.code(400).send({
+            error: "invalid_action",
+            message: "exactly one of `command` or `text` is required",
+        });
+        return undefined;
+    }
+    const out = { name: trimmedName };
+    if (body.enabled !== undefined)
+        out.enabled = body.enabled;
+    if (hasCmd) {
+        const cmd = body.command;
+        if (Buffer.byteLength(cmd, "utf8") > MAX_COMMAND_BYTES) {
+            reply.code(400).send({ error: "command_too_large" });
+            return undefined;
+        }
+        out.command = cmd;
+        if (body.timeoutMs !== undefined) {
+            const t = body.timeoutMs;
+            if (!Number.isInteger(t) || t <= 0) {
+                reply.code(400).send({ error: "invalid_timeout" });
+                return undefined;
+            }
+            out.timeoutMs = Math.min(t, MAX_TIMEOUT_MS);
+        }
+    }
+    else {
+        const text = body.text;
+        if (Buffer.byteLength(text, "utf8") > MAX_PROMPT_BYTES) {
+            reply.code(400).send({ error: "prompt_too_large" });
+            return undefined;
+        }
+        out.text = text;
+        out.mode = body.mode ?? "send";
+    }
+    return out;
+}
+function handleError(reply, err) {
+    if (err instanceof QuickActionNotFoundError) {
+        return reply.code(404).send({ error: "action_not_found" });
+    }
+    reply.log.error({ err }, "quick-actions route error");
+    return reply.code(500).send({ error: "internal_error" });
+}
+/**
+ * Spawn the command under `/bin/sh -c` with a scrubbed env (same
+ * posture as the integrated terminal — no pi-forge / provider
+ * secrets leak into chip output). stdout and stderr are captured
+ * separately so the chat card can render them in distinct blocks.
+ */
+async function runCommand(command, cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        const proc = spawn("/bin/sh", ["-c", command], {
+            cwd,
+            env: scrubbedEnv(),
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutLen = 0;
+        let stderrLen = 0;
+        let truncated = false;
+        let timedOut = false;
+        proc.stdout?.on("data", (chunk) => {
+            const remaining = MAX_OUTPUT_BYTES - stdoutLen;
+            if (remaining <= 0) {
+                truncated = true;
+                return;
+            }
+            if (chunk.length > remaining) {
+                stdoutChunks.push(chunk.subarray(0, remaining));
+                stdoutLen += remaining;
+                truncated = true;
+            }
+            else {
+                stdoutChunks.push(chunk);
+                stdoutLen += chunk.length;
+            }
+        });
+        proc.stderr?.on("data", (chunk) => {
+            const remaining = MAX_OUTPUT_BYTES - stderrLen;
+            if (remaining <= 0) {
+                truncated = true;
+                return;
+            }
+            if (chunk.length > remaining) {
+                stderrChunks.push(chunk.subarray(0, remaining));
+                stderrLen += remaining;
+                truncated = true;
+            }
+            else {
+                stderrChunks.push(chunk);
+                stderrLen += chunk.length;
+            }
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                proc.kill("SIGTERM");
+            }
+            catch {
+                // best-effort
+            }
+            // SIGKILL grace — match the exec-route convention.
+            setTimeout(() => {
+                try {
+                    proc.kill("SIGKILL");
+                }
+                catch {
+                    // best-effort
+                }
+            }, 2000);
+        }, timeoutMs);
+        proc.on("error", (err) => {
+            clearTimeout(timer);
+            // Spawn error (ENOENT on `/bin/sh`, etc.) — surface as a failed
+            // run with the error on stderr so the chat card shows it.
+            resolve({
+                exitCode: null,
+                stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                stderr: err.message,
+                timedOut,
+                truncated,
+            });
+        });
+        proc.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: code,
+                stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf8"),
+                timedOut,
+                truncated,
+            });
+        });
+    });
+}
+export const quickActionRoutes = async (fastify) => {
+    fastify.get("/quick-actions", {
+        schema: {
+            description: "List all quick-action chips. Global (not per-project) — chips " +
+                "are operator-personal, same install-private rationale as the " +
+                "other forge-owned config files.",
+            tags: ["config"],
+            response: {
+                200: {
+                    type: "object",
+                    required: ["actions"],
+                    properties: {
+                        actions: { type: "array", items: quickActionSchema },
+                    },
+                },
+            },
+        },
+    }, async () => ({ actions: await readQuickActions() }));
+    fastify.post("/quick-actions", {
+        schema: {
+            description: "Create a quick-action chip. Exactly one of `command` or `text` " +
+                "must be set — presence is the kind discriminator (no `kind` " +
+                "field on the wire, matches the MCP server-config convention). " +
+                "400 on both/neither, 400 on byte-cap overflow.",
+            tags: ["config"],
+            body: {
+                type: "object",
+                required: ["name"],
+                additionalProperties: false,
+                properties: {
+                    name: { type: "string", minLength: 1, maxLength: 200 },
+                    enabled: { type: "boolean" },
+                    command: { type: "string" },
+                    timeoutMs: { type: "integer", minimum: 1 },
+                    text: { type: "string" },
+                    mode: { type: "string", enum: ["send", "insert"] },
+                },
+            },
+            response: {
+                201: quickActionSchema,
+                400: errorSchema,
+            },
+        },
+    }, async (req, reply) => {
+        const validated = validateBody(req.body, reply);
+        if (validated === undefined)
+            return reply;
+        try {
+            const created = await createQuickAction(validated);
+            return reply.code(201).send(created);
+        }
+        catch (err) {
+            return handleError(reply, err);
+        }
+    });
+    fastify.put("/quick-actions/:id", {
+        schema: {
+            description: "Replace a quick-action chip. Full record on the body — switching " +
+                "kind (command ↔ prompt) drops the now-unused fields. Same " +
+                "validation rules as POST.",
+            tags: ["config"],
+            params: {
+                type: "object",
+                required: ["id"],
+                properties: { id: { type: "string" } },
+            },
+            body: {
+                type: "object",
+                required: ["name"],
+                additionalProperties: false,
+                properties: {
+                    name: { type: "string", minLength: 1, maxLength: 200 },
+                    enabled: { type: "boolean" },
+                    command: { type: "string" },
+                    timeoutMs: { type: "integer", minimum: 1 },
+                    text: { type: "string" },
+                    mode: { type: "string", enum: ["send", "insert"] },
+                },
+            },
+            response: {
+                200: quickActionSchema,
+                400: errorSchema,
+                404: errorSchema,
+            },
+        },
+    }, async (req, reply) => {
+        const validated = validateBody(req.body, reply);
+        if (validated === undefined)
+            return reply;
+        try {
+            const updated = await updateQuickAction(req.params.id, validated);
+            return updated;
+        }
+        catch (err) {
+            return handleError(reply, err);
+        }
+    });
+    fastify.delete("/quick-actions/:id", {
+        schema: {
+            description: "Delete a quick-action chip.",
+            tags: ["config"],
+            params: {
+                type: "object",
+                required: ["id"],
+                properties: { id: { type: "string" } },
+            },
+            response: {
+                204: { type: "null" },
+                404: errorSchema,
+            },
+        },
+    }, async (req, reply) => {
+        try {
+            await deleteQuickAction(req.params.id);
+            return reply.code(204).send();
+        }
+        catch (err) {
+            return handleError(reply, err);
+        }
+    });
+    fastify.post("/quick-actions/:id/run", {
+        schema: {
+            description: "Execute a command-kind quick action in the named project's " +
+                "cwd. Returns captured stdout/stderr and the exit code. The " +
+                "spawned shell inherits a SCRUBBED env (same as the " +
+                "integrated terminal — no pi-forge or provider secrets). " +
+                "Hard-gated under MINIMAL_UI: command runs return 403 " +
+                "`command_actions_disabled_in_minimal` regardless of who " +
+                "is calling. Prompt-kind actions are not executable here " +
+                "(420-style validation error) — those are a pure client " +
+                "concern that route through the composer or sendPrompt.",
+            tags: ["config"],
+            params: {
+                type: "object",
+                required: ["id"],
+                properties: { id: { type: "string" } },
+            },
+            body: {
+                type: "object",
+                required: ["projectId"],
+                additionalProperties: false,
+                properties: {
+                    projectId: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: runResultSchema,
+                400: errorSchema,
+                403: errorSchema,
+                404: errorSchema,
+            },
+        },
+    }, async (req, reply) => {
+        // Defense in depth — the client also hides command chips
+        // under MINIMAL_UI, but a stale tab or scripted caller could
+        // still POST here. Refuse at the route.
+        if (config.minimalUi) {
+            return reply.code(403).send({ error: "command_actions_disabled_in_minimal" });
+        }
+        const action = await getQuickAction(req.params.id);
+        if (action === undefined) {
+            return reply.code(404).send({ error: "action_not_found" });
+        }
+        if (isPromptAction(action)) {
+            return reply.code(400).send({
+                error: "not_a_command_action",
+                message: "prompt actions are dispatched client-side, not via this route",
+            });
+        }
+        if (!isCommandAction(action)) {
+            return reply.code(400).send({ error: "invalid_action" });
+        }
+        const project = await getProject(req.body.projectId);
+        if (project === undefined) {
+            return reply.code(404).send({ error: "project_not_found" });
+        }
+        const timeoutMs = Math.min(action.timeoutMs ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+        const started = Date.now();
+        const result = await runCommand(action.command, project.path, timeoutMs);
+        const durationMs = Date.now() - started;
+        return {
+            success: result.exitCode === 0 && !result.timedOut,
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            durationMs,
+            timedOut: result.timedOut,
+            truncated: result.truncated,
+        };
+    });
+};
+//# sourceMappingURL=quick-actions.js.map

package/dist/server/routes/quick-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quick-actions.js","sourceRoot":"","sources":["../../src/routes/quick-actions.ts"],"names":[],"mappings":"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"}

package/dist/server/routes/todos.js

@@ -0,0 +1,67 @@
+import { getSession } from "../session-registry.js";
+import { getState } from "../todo/store.js";
+import { errorSchema } from "./_schemas.js";
+/**
+ * GET /sessions/:id/todos
+ *
+ * Returns the current todo state for a session. Used by the UI
+ * panel as the initial fetch when an SSE snapshot hasn't landed
+ * yet (cold load, cross-tab join). The store's `getState` is
+ * cache-first with replay-on-miss, so this is honest after a
+ * server restart even if the cache is empty.
+ *
+ * The wire shape mirrors the SSE `todo_update` event so the
+ * client can use one normaliser for both paths.
+ */
+const taskSchema = {
+    type: "object",
+    required: ["id", "subject", "status"],
+    additionalProperties: true,
+    properties: {
+        id: { type: "integer" },
+        subject: { type: "string" },
+        description: { type: "string" },
+        activeForm: { type: "string" },
+        status: { type: "string", enum: ["pending", "in_progress", "completed", "deleted"] },
+        blockedBy: { type: "array", items: { type: "integer" } },
+        owner: { type: "string" },
+        metadata: { type: "object", additionalProperties: true },
+    },
+};
+export const todoRoutes = async (fastify) => {
+    fastify.get("/sessions/:id/todos", {
+        schema: {
+            description: "Return the current todo list for this session. Cache-first; " +
+                "rebuilds from the session branch on cache miss so a server " +
+                "restart doesn't lie about state.",
+            tags: ["sessions"],
+            params: {
+                type: "object",
+                required: ["id"],
+                properties: { id: { type: "string" } },
+            },
+            response: {
+                200: {
+                    type: "object",
+                    required: ["tasks", "nextId"],
+                    properties: {
+                        tasks: { type: "array", items: taskSchema },
+                        nextId: { type: "integer" },
+                    },
+                },
+                404: errorSchema,
+            },
+        },
+    }, async (req, reply) => {
+        const live = getSession(req.params.id);
+        if (live === undefined) {
+            return reply.code(404).send({ error: "session_not_found" });
+        }
+        // AgentSession.sessionManager is the public accessor (see
+        // agent-session.d.ts). getState is cache-first with replay-
+        // on-miss, so this stays honest after a server restart.
+        const state = getState(req.params.id, live.session.sessionManager);
+        return { tasks: state.tasks, nextId: state.nextId };
+    });
+};
+//# sourceMappingURL=todos.js.map

package/dist/server/routes/todos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todos.js","sourceRoot":"","sources":["../../src/routes/todos.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,GAAG;IACjB,IAAI,EAAE,QAAQ;IACd,QAAQ,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC;IACrC,oBAAoB,EAAE,IAAI;IAC1B,UAAU,EAAE;QACV,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;QACvB,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC3B,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC/B,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC9B,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE;QACpF,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE;QACxD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QACzB,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,oBAAoB,EAAE,IAAI,EAAE;KACzD;CACO,CAAC;AAEX,MAAM,CAAC,MAAM,UAAU,GAAuB,KAAK,EAAE,OAAO,EAAE,EAAE;IAC9D,OAAO,CAAC,GAAG,CACT,qBAAqB,EACrB;QACE,MAAM,EAAE;YACN,WAAW,EACT,8DAA8D;gBAC9D,6DAA6D;gBAC7D,kCAAkC;YACpC,IAAI,EAAE,CAAC,UAAU,CAAC;YAClB,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,CAAC,IAAI,CAAC;gBAChB,UAAU,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;aACvC;YACD,QAAQ,EAAE;gBACR,GAAG,EAAE;oBACH,IAAI,EAAE,QAAQ;oBACd,QAAQ,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC;oBAC7B,UAAU,EAAE;wBACV,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE;wBAC3C,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;qBAC5B;iBACF;gBACD,GAAG,EAAE,WAAW;aACjB;SACF;KACF,EACD,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;QACnB,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACvC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC,CAAC;QAC9D,CAAC;QACD,0DAA0D;QAC1D,4DAA4D;QAC5D,wDAAwD;QACxD,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QACnE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;IACtD,CAAC,CACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/server/session-registry.js

@@ -9,6 +9,11 @@ import { readProjects } from "./project-manager.js";
 import { filterEnabledTools, readToolOverrides } from "./tool-overrides.js";
 import { discoverExtensionResources } from "./extensions-discovery.js";
 import { customToolsForProject as mcpCustomToolsForProject, ensureProjectLoaded as mcpEnsureProjectLoaded, isGloballyEnabled as mcpIsGloballyEnabled, } from "./mcp/manager.js";
+import { createAskUserQuestionTool } from "./ask-user-question/tool.js";
+import { createTodoTool } from "./todo/tool.js";
+import { clearForSession as clearTodoForSession, refreshFromBranch as refreshTodoFromBranch, } from "./todo/store.js";
+import { createProcessTool } from "./processes/tool.js";
+import { processManager } from "./processes/manager.js";
 export class SessionNotFoundError extends Error {
     constructor(id) {
         super(`session not found: ${id}`);
@@ -52,6 +57,21 @@ export const BUILTIN_TOOL_NAMES = [
     "grep",
     "find",
     "ls",
+    // ask_user_question is implemented in pi-forge (see ask-user-question/),
+    // not in the pi SDK. Listed here so the Tools settings tab surfaces it
+    // under "Built-in tools" — disabling it filters it out of the allowlist
+    // passed to createAgentSession, so the agent never sees the tool.
+    "ask_user_question",
+    // todo is implemented in pi-forge (see todo/), contract-compatible with
+    // @juicesharp/rpiv-todo. Same disable-via-settings semantics as
+    // ask_user_question.
+    "todo",
+    // process is implemented in pi-forge (see processes/), contract-
+    // compatible with @aliou/pi-processes. Manages background processes
+    // the agent spawns (dev servers, watchers, etc.) — separate spawn
+    // surface from bash, with lifecycle management + log capture +
+    // regex watches. Disable here to filter out of the allowlist.
+    "process",
 ];
 /**
  * Build the `tools` allowlist passed to `createAgentSession` for this
@@ -247,7 +267,15 @@ export async function createSession(projectId, workspacePath) {
     // agentDir IS passed: without it, the SDK falls back to ~/.pi/agent and
     // ignores PI_CONFIG_DIR entirely, breaking auth.json/models.json wiring
     // for Phase 6's prompt route.
-    const customTools = await resolveMcpCustomTools(projectId, workspacePath);
+    const mcpTools = await resolveMcpCustomTools(projectId, workspacePath);
+    // SessionManager.getSessionId() is synchronous and stable from
+    // create() onward — read it BEFORE createAgentSession so the
+    // forge-native ask_user_question tool can bind to the right
+    // session in its execute() closure.
+    const askTool = createAskUserQuestionTool(sessionManager.getSessionId());
+    const todoTool = createTodoTool(sessionManager.getSessionId(), sessionManager);
+    const processTool = createProcessTool(sessionManager.getSessionId(), workspacePath);
+    const customTools = [...mcpTools, askTool, todoTool, processTool];
     const settingsManager = await buildSessionSettingsManager(workspacePath, projectId);
     const resourceLoader = await buildForgeResourceLoader(workspacePath, config.piConfigDir, settingsManager, projectId);
     const { session } = await createAgentSession({
@@ -426,7 +454,15 @@ export async function resumeSession(sessionId, projectId, workspacePath) {
         // collapses to the project session dir.
         const childSessionDir = match.parentSessionId !== undefined ? join(match.path, "..") : dir;
         const sessionManager = SessionManager.open(match.path, childSessionDir, workspacePath);
-        const customTools = await resolveMcpCustomTools(projectId, workspacePath);
+        const mcpTools = await resolveMcpCustomTools(projectId, workspacePath);
+        const askTool = createAskUserQuestionTool(sessionManager.getSessionId());
+        const todoTool = createTodoTool(sessionManager.getSessionId(), sessionManager);
+        const processTool = createProcessTool(sessionManager.getSessionId(), workspacePath);
+        const customTools = [...mcpTools, askTool, todoTool, processTool];
+        // Resumed session — refresh the todo cache from the branch so
+        // the UI panel sees the persisted state on first SSE connect,
+        // not an empty list.
+        refreshTodoFromBranch(sessionManager.getSessionId(), sessionManager);
         const settingsManager = await buildSessionSettingsManager(workspacePath, projectId);
         const resourceLoader = await buildForgeResourceLoader(workspacePath, config.piConfigDir, settingsManager, projectId);
         const { session } = await createAgentSession({
@@ -604,6 +640,17 @@ export async function disposeSession(sessionId) {
         catch {
             // ignore — SDK doesn't currently throw, but H2-defensive
         }
+        // Drop the todo cache for this session. The cache is a fast
+        // path; even without this, a future session with the same id
+        // would recover via replay-on-miss. Cleaner to be explicit.
+        clearTodoForSession(sessionId);
+        // Terminate every live process owned by this session (SIGTERM,
+        // brief grace, SIGKILL) and remove the per-session log dir.
+        // Best-effort + bounded — disposeSession itself can take up to
+        // GRACE_MS but no longer; the outer disposeAllSessions caller
+        // doesn't block on this beyond its own ABORT_TIMEOUT_MS race
+        // because we await it last.
+        await processManager.disposeSession(sessionId).catch(() => undefined);
     }
     finally {
         registry.delete(sessionId);
@@ -1015,7 +1062,15 @@ async function forkSessionLocked(sessionId, entryId) {
         throw new Error("fork_failed");
     const dir = sessionDirFor(source.projectId);
     const sessionManager = SessionManager.open(newPath, dir, source.workspacePath);
-    const customTools = await resolveMcpCustomTools(source.projectId, source.workspacePath);
+    const mcpTools = await resolveMcpCustomTools(source.projectId, source.workspacePath);
+    const askTool = createAskUserQuestionTool(sessionManager.getSessionId());
+    const todoTool = createTodoTool(sessionManager.getSessionId(), sessionManager);
+    const processTool = createProcessTool(sessionManager.getSessionId(), source.workspacePath);
+    const customTools = [...mcpTools, askTool, todoTool, processTool];
+    // Forked session — replay the branch (which now belongs to the
+    // fork) so the new session's todo cache reflects the inherited
+    // state, not the parent's stale entry.
+    refreshTodoFromBranch(sessionManager.getSessionId(), sessionManager);
     const settingsManager = await buildSessionSettingsManager(source.workspacePath, source.projectId);
     const resourceLoader = await buildForgeResourceLoader(source.workspacePath, config.piConfigDir, settingsManager, source.projectId);
     const { session } = await createAgentSession({
@@ -1079,7 +1134,20 @@ async function forkSessionLocked(sessionId, entryId) {
         try {
             source.unsubscribe();
             const restoredManager = SessionManager.open(originalSourceFile, dir, source.workspacePath);
-            const restoredCustomTools = await resolveMcpCustomTools(source.projectId, source.workspacePath);
+            const restoredMcpTools = await resolveMcpCustomTools(source.projectId, source.workspacePath);
+            const restoredAskTool = createAskUserQuestionTool(restoredManager.getSessionId());
+            const restoredTodoTool = createTodoTool(restoredManager.getSessionId(), restoredManager);
+            const restoredProcessTool = createProcessTool(restoredManager.getSessionId(), source.workspacePath);
+            const restoredCustomTools = [
+                ...restoredMcpTools,
+                restoredAskTool,
+                restoredTodoTool,
+                restoredProcessTool,
+            ];
+            // Re-derive the original source's todo cache from the (now
+            // un-mutated) source JSONL — the SDK's fork machinery left
+            // the cache pointing at fork state.
+            refreshTodoFromBranch(restoredManager.getSessionId(), restoredManager);
             const restoredSettingsManager = await buildSessionSettingsManager(source.workspacePath, source.projectId);
             const restoredResourceLoader = await buildForgeResourceLoader(source.workspacePath, config.piConfigDir, restoredSettingsManager, source.projectId);
             const { session: restoredSession } = await createAgentSession({