@launch11/srgical 0.0.7 → 0.0.8

package/README.md

@@ -31,7 +31,7 @@ This repo currently ships the foundation for:
   Prints the installed version with release-note links instead of only echoing the semver.
 - `srgical doctor`
   Reports the active plan, plan readiness, execution state, auto-run state, and which supported agents are available
-  locally.
+  locally, along with any cached AI advice for the selected plan.
 - `srgical about`
   Shows package details, release links, and the currently supported agent adapters.
 - `srgical changelog`
@@ -40,7 +40,8 @@ This repo currently ships the foundation for:
   Creates a local `.srgical/` planning pack from built-in templates, with `--plan <id>` for named plans.
 - `srgical studio`
   Opens a full-screen planning studio where you can switch between named plans, inspect readiness with `/readiness`,
-  inspect supported tools with `/agents`, and explicitly trigger pack writes, single-step execution, or `/auto`.
+  inspect supported tools with `/agents`, refresh AI guidance with `/advice`, and explicitly trigger pack writes,
+  single-step execution, or `/auto`.
 - `srgical run-next`
   Replays the generated next-agent prompt through the active agent, with `--plan <id>` for plan targeting,
   `--dry-run` for safe preview, `--agent <id>` for a one-run override, and `--auto` for bounded multi-step execution.
@@ -168,10 +169,19 @@ Inside the studio, the footer is intentionally minimal:
 - `PgUp/PgDn` scrolls the transcript
 - `/agents` chooses the current tool
 - `/help` shows the full command set
+- `/quit` exits the studio
 
 The composer is now multiline with a minimum two-line visible input area. `Enter` sends, while `Shift+Enter`,
 `Alt+Enter`, or `Ctrl+J` inserts a newline when the terminal exposes those keys distinctly.
 
+The studio can also ask the active agent for an AI assessment of the current planning state. Run `/advice` to cache a
+plain-English summary of:
+
+- the problem statement the agent believes you are solving,
+- whether the current plan state is clear or still fuzzy,
+- what research or repo truth still needs to be gathered,
+- and the best next move right now.
+
 ## Current Claude Caveat
 
 Claude support is real, but it is not treated as interchangeable with Codex. The current non-interactive Claude path

package/dist/commands/doctor.js

@@ -91,6 +91,12 @@ function renderPlanDetailLines(state) {
     if (state.autoRun) {
         lines.push(`Auto run detail: attempted ${state.autoRun.stepsAttempted}${state.autoRun.maxSteps ? `/${state.autoRun.maxSteps}` : ""}, stop reason ${state.autoRun.stopReason ?? "none"}`);
     }
+    if (state.advice) {
+        lines.push(`AI advice: ${state.advice.problemStatement}`, `  Clarity: ${state.advice.clarity}`, `  Assessment: ${state.advice.stateAssessment}`, `  Research: ${state.advice.researchNeeded.length > 0 ? state.advice.researchNeeded.join(", ") : "none"}`, `  Next: ${state.advice.nextAction}`);
+    }
+    else {
+        lines.push("AI advice: none cached yet (run `/advice` in studio to generate guidance).");
+    }
     return lines;
 }
 function renderNextStepLines(nextStepSummary, nextRecommended) {

package/dist/core/advice-state.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPlanningAdviceState = loadPlanningAdviceState;
+exports.savePlanningAdviceState = savePlanningAdviceState;
+exports.normalizePlanningAdvice = normalizePlanningAdvice;
+exports.parsePlanningAdviceResponse = parsePlanningAdviceResponse;
+const workspace_1 = require("./workspace");
+async function loadPlanningAdviceState(workspaceRoot, options = {}) {
+    const paths = (0, workspace_1.getPlanningPackPaths)(workspaceRoot, options);
+    if (!(await (0, workspace_1.fileExists)(paths.adviceState))) {
+        return null;
+    }
+    try {
+        return normalizePlanningAdvice(JSON.parse(await (0, workspace_1.readText)(paths.adviceState)), paths.planId);
+    }
+    catch {
+        return null;
+    }
+}
+async function savePlanningAdviceState(workspaceRoot, advice, options = {}) {
+    const paths = await (0, workspace_1.ensurePlanningDir)(workspaceRoot, options);
+    const payload = {
+        version: 1,
+        planId: paths.planId,
+        updatedAt: new Date().toISOString(),
+        ...advice
+    };
+    await (0, workspace_1.writeText)(paths.adviceState, JSON.stringify(payload, null, 2));
+    return payload;
+}
+function normalizePlanningAdvice(value, fallbackPlanId) {
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const candidate = value;
+    const clarity = normalizeClarity(candidate.clarity);
+    if (candidate.version !== 1 ||
+        typeof candidate.problemStatement !== "string" ||
+        !clarity ||
+        typeof candidate.stateAssessment !== "string" ||
+        !Array.isArray(candidate.researchNeeded) ||
+        candidate.researchNeeded.some((item) => typeof item !== "string") ||
+        typeof candidate.advice !== "string" ||
+        typeof candidate.nextAction !== "string") {
+        return null;
+    }
+    return {
+        version: 1,
+        planId: typeof candidate.planId === "string" ? candidate.planId : fallbackPlanId,
+        updatedAt: typeof candidate.updatedAt === "string" ? candidate.updatedAt : new Date().toISOString(),
+        problemStatement: candidate.problemStatement.trim(),
+        clarity,
+        stateAssessment: candidate.stateAssessment.trim(),
+        researchNeeded: candidate.researchNeeded.map((item) => item.trim()).filter(Boolean),
+        advice: candidate.advice.trim(),
+        nextAction: candidate.nextAction.trim()
+    };
+}
+function parsePlanningAdviceResponse(raw, fallbackPlanId) {
+    const jsonStart = raw.indexOf("{");
+    const jsonEnd = raw.lastIndexOf("}");
+    if (jsonStart === -1 || jsonEnd === -1 || jsonEnd <= jsonStart) {
+        return null;
+    }
+    try {
+        return normalizePlanningAdvice(JSON.parse(raw.slice(jsonStart, jsonEnd + 1)), fallbackPlanId);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeClarity(value) {
+    if (value === "clear" || value === "mostly clear" || value === "still fuzzy") {
+        return value;
+    }
+    return null;
+}

package/dist/core/agent.js

@@ -8,6 +8,7 @@ exports.detectPrimaryAgent = detectPrimaryAgent;
 exports.resolveExecutionAgent = resolveExecutionAgent;
 exports.requestPlannerReply = requestPlannerReply;
 exports.writePlanningPack = writePlanningPack;
+exports.requestPlanningAdvice = requestPlanningAdvice;
 exports.runNextPrompt = runNextPrompt;
 exports.selectPrimaryAgent = selectPrimaryAgent;
 exports.resetAgentAdaptersForTesting = resetAgentAdaptersForTesting;
@@ -31,6 +32,7 @@ const codexAdapter = {
         };
     },
     requestPlannerReply: codex_1.requestPlannerReply,
+    requestPlanningAdvice: codex_1.requestPlanningAdvice,
     writePlanningPack: codex_1.writePlanningPack,
     runNextPrompt: codex_1.runNextPrompt
 };
@@ -49,6 +51,7 @@ const claudeAdapter = {
         };
     },
     requestPlannerReply: claude_1.requestPlannerReply,
+    requestPlanningAdvice: claude_1.requestPlanningAdvice,
     writePlanningPack: claude_1.writePlanningPack,
     runNextPrompt: claude_1.runNextPrompt
 };
@@ -67,6 +70,7 @@ const augmentAdapter = {
         };
     },
     requestPlannerReply: augment_1.requestPlannerReply,
+    requestPlanningAdvice: augment_1.requestPlanningAdvice,
     writePlanningPack: augment_1.writePlanningPack,
     runNextPrompt: augment_1.runNextPrompt
 };
@@ -127,6 +131,10 @@ async function writePlanningPack(workspaceRoot, messages, options = {}) {
     const { adapter } = await resolvePrimaryAgent(workspaceRoot, options);
     return adapter.writePlanningPack(workspaceRoot, messages, options);
 }
+async function requestPlanningAdvice(workspaceRoot, messages, packState, options = {}) {
+    const { adapter } = await resolvePrimaryAgent(workspaceRoot, options);
+    return adapter.requestPlanningAdvice(workspaceRoot, messages, packState, options);
+}
 async function runNextPrompt(workspaceRoot, prompt, options = {}) {
     const { adapter } = await resolveExecutionAgent(workspaceRoot, options.agentId, { planId: options.planId });
     return adapter.runNextPrompt(workspaceRoot, prompt, { planId: options.planId });

package/dist/core/augment.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectAugment = detectAugment;
 exports.requestPlannerReply = requestPlannerReply;
+exports.requestPlanningAdvice = requestPlanningAdvice;
 exports.writePlanningPack = writePlanningPack;
 exports.runNextPrompt = runNextPrompt;
 exports.setAugmentRuntimeForTesting = setAugmentRuntimeForTesting;
@@ -55,6 +56,15 @@ async function requestPlannerReply(workspaceRoot, messages, _options = {}) {
     });
     return result.lastMessage.trim();
 }
+async function requestPlanningAdvice(workspaceRoot, messages, packState, options = {}) {
+    const result = await runAugmentExec({
+        cwd: workspaceRoot,
+        prompt: await (0, prompts_1.buildAdvicePrompt)(messages, workspaceRoot, packState, options),
+        askMode: true,
+        maxTurns: 4
+    });
+    return result.lastMessage.trim();
+}
 async function writePlanningPack(workspaceRoot, messages, options = {}) {
     const planningEpoch = await (0, planning_epochs_1.preparePlanningPackForWrite)(workspaceRoot, options);
     const augmentStatus = await detectAugment();

package/dist/core/claude.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectClaude = detectClaude;
 exports.requestPlannerReply = requestPlannerReply;
+exports.requestPlanningAdvice = requestPlanningAdvice;
 exports.writePlanningPack = writePlanningPack;
 exports.runNextPrompt = runNextPrompt;
 exports.setClaudeRuntimeForTesting = setClaudeRuntimeForTesting;
@@ -49,6 +50,15 @@ async function requestPlannerReply(workspaceRoot, messages, _options = {}) {
     });
     return result.lastMessage.trim();
 }
+async function requestPlanningAdvice(workspaceRoot, messages, packState, options = {}) {
+    const result = await runClaudeExec({
+        cwd: workspaceRoot,
+        prompt: await (0, prompts_1.buildAdvicePrompt)(messages, workspaceRoot, packState, options),
+        permissionMode: "plan",
+        maxTurns: 4
+    });
+    return result.lastMessage.trim();
+}
 async function writePlanningPack(workspaceRoot, messages, options = {}) {
     const planningEpoch = await (0, planning_epochs_1.preparePlanningPackForWrite)(workspaceRoot, options);
     const claudeStatus = await detectClaude();

package/dist/core/codex.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectCodex = detectCodex;
 exports.requestPlannerReply = requestPlannerReply;
+exports.requestPlanningAdvice = requestPlanningAdvice;
 exports.writePlanningPack = writePlanningPack;
 exports.runNextPrompt = runNextPrompt;
 exports.setCodexRuntimeForTesting = setCodexRuntimeForTesting;
@@ -47,6 +48,16 @@ async function requestPlannerReply(workspaceRoot, messages, _options = {}) {
     });
     return result.lastMessage.trim();
 }
+async function requestPlanningAdvice(workspaceRoot, messages, packState, options = {}) {
+    const result = await runCodexExec({
+        cwd: workspaceRoot,
+        prompt: await (0, prompts_1.buildAdvicePrompt)(messages, workspaceRoot, packState, options),
+        allowWrite: false,
+        skipGitRepoCheck: true,
+        ephemeral: true
+    });
+    return result.lastMessage.trim();
+}
 async function writePlanningPack(workspaceRoot, messages, options = {}) {
     const planningEpoch = await (0, planning_epochs_1.preparePlanningPackForWrite)(workspaceRoot, options);
     const codexStatus = await detectCodex();

package/dist/core/planning-advice.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshPlanningAdvice = refreshPlanningAdvice;
+const advice_state_1 = require("./advice-state");
+const agent_1 = require("./agent");
+const planning_pack_state_1 = require("./planning-pack-state");
+async function refreshPlanningAdvice(workspaceRoot, messages, options = {}) {
+    const packState = await (0, planning_pack_state_1.readPlanningPackState)(workspaceRoot, options);
+    const raw = await (0, agent_1.requestPlanningAdvice)(workspaceRoot, messages, packState, options);
+    const parsed = (0, advice_state_1.parsePlanningAdviceResponse)(raw, packState.planId);
+    if (!parsed) {
+        throw new Error("Planning advice could not be parsed from the active agent response.");
+    }
+    return (0, advice_state_1.savePlanningAdviceState)(workspaceRoot, {
+        problemStatement: parsed.problemStatement,
+        clarity: parsed.clarity,
+        stateAssessment: parsed.stateAssessment,
+        researchNeeded: parsed.researchNeeded,
+        advice: parsed.advice,
+        nextAction: parsed.nextAction
+    }, options);
+}

package/dist/core/planning-epochs.js

@@ -21,6 +21,7 @@ const ARCHIVED_PACK_FILE_NAMES = [
     "studio-session.json",
     "planning-state.json",
     "auto-run-state.json",
+    "advice-state.json",
     "execution-state.json",
     "execution-log.md"
 ];
@@ -75,6 +76,7 @@ async function resetActivePlanningPack(paths) {
     await (0, planning_state_1.savePlanningState)(paths.root, "scaffolded", { planId: paths.planId });
     await Promise.all([
         (0, promises_1.rm)(paths.autoRunState, { force: true }),
+        (0, promises_1.rm)(paths.adviceState, { force: true }),
         (0, promises_1.rm)(paths.executionState, { force: true }),
         (0, promises_1.rm)(paths.executionLog, { force: true })
     ]);
@@ -88,6 +90,7 @@ function listArchivablePaths(paths) {
         paths.studioSession,
         paths.planningState,
         paths.autoRunState,
+        paths.adviceState,
         paths.executionState,
         paths.executionLog
     ];

package/dist/core/planning-pack-state.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readPlanningPackState = readPlanningPackState;
 exports.isExecutionStepSummary = isExecutionStepSummary;
 exports.isExecutionReadyState = isExecutionReadyState;
+const advice_state_1 = require("./advice-state");
 const auto_run_state_1 = require("./auto-run-state");
 const execution_state_1 = require("./execution-state");
 const planning_state_1 = require("./planning-state");
@@ -25,9 +26,10 @@ async function readPlanningPackState(workspaceRoot, options = {}) {
             trackerReadable = false;
         }
     }
-    const [lastExecution, planningState, autoRun, docsPresent, studioSession] = await Promise.all([
+    const [lastExecution, planningState, advice, autoRun, docsPresent, studioSession] = await Promise.all([
         (0, execution_state_1.loadExecutionState)(workspaceRoot, options),
         (0, planning_state_1.loadPlanningState)(workspaceRoot, options),
+        (0, advice_state_1.loadPlanningAdviceState)(workspaceRoot, options),
         (0, auto_run_state_1.loadAutoRunState)(workspaceRoot, options),
         countPresentDocs(paths),
         (0, studio_session_1.loadStudioSessionState)(workspaceRoot, options)
@@ -57,6 +59,7 @@ async function readPlanningPackState(workspaceRoot, options = {}) {
         planningState,
         packMode,
         readiness,
+        advice,
         autoRun,
         executionActivated,
         mode,

package/dist/core/prompts.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildPlannerPrompt = buildPlannerPrompt;
 exports.buildPackWriterPrompt = buildPackWriterPrompt;
+exports.buildAdvicePrompt = buildAdvicePrompt;
 const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
 const workspace_1 = require("./workspace");
@@ -71,6 +72,46 @@ ${repoTruth}
 
 Conversation transcript:
 
+${renderTranscript(messages)}
+`;
+}
+async function buildAdvicePrompt(messages, workspaceRoot, packState, options = {}) {
+    const repoTruth = await buildRepoTruthSnapshot(workspaceRoot, options);
+    return `You are the planning advisor inside srgical.
+
+Your job is to assess the current planning state and return only a single JSON object.
+
+Assess the user's current problem statement, whether the repo/project state is clear enough yet, whether more research is needed, and what the best next move is.
+
+Rules:
+- Be specific to the current repository and transcript.
+- Do not invent repo facts that are not supported by the transcript or repo truth snapshot.
+- Prefer concise, practical advice over generic coaching.
+- If the plan is still fuzzy, say so plainly.
+- If more repo research is needed, name the missing area directly.
+- Return valid JSON only. No markdown fences. No prose before or after the JSON.
+
+Required JSON shape:
+{
+  "version": 1,
+  "problemStatement": "string",
+  "clarity": "clear" | "mostly clear" | "still fuzzy",
+  "stateAssessment": "one short sentence",
+  "researchNeeded": ["string", "string"],
+  "advice": "one short paragraph",
+  "nextAction": "one concrete next move"
+}
+
+Current deterministic planning state:
+
+${renderPlanningStateSummary(packState)}
+
+Repo truth snapshot:
+
+${repoTruth}
+
+Conversation transcript:
+
 ${renderTranscript(messages)}
 `;
 }
@@ -121,6 +162,23 @@ async function buildRepoTruthSnapshot(workspaceRoot, options = {}) {
         renderNamedSnippet(".srgical/04-next-agent-prompt.md", nextPromptSnippet)
     ].join("\n");
 }
+function renderPlanningStateSummary(packState) {
+    return [
+        `- planId: ${packState.planId}`,
+        `- packDir: ${packState.packDir}`,
+        `- packPresent: ${packState.packPresent}`,
+        `- packMode: ${packState.packMode}`,
+        `- mode: ${packState.mode}`,
+        `- docsPresent: ${packState.docsPresent}/4`,
+        `- readiness: ${packState.readiness.score}/${packState.readiness.total}`,
+        `- readinessReadyToWrite: ${packState.readiness.readyToWrite}`,
+        `- missingReadinessSignals: ${packState.readiness.missingLabels.join(", ") || "none"}`,
+        `- nextRecommended: ${packState.currentPosition.nextRecommended ?? "none queued"}`,
+        `- nextStepId: ${packState.nextStepSummary?.id ?? "none"}`,
+        `- executionActivated: ${packState.executionActivated}`,
+        `- autoRunStatus: ${packState.autoRun?.status ?? "idle"}`
+    ].join("\n");
+}
 async function summarizePackageManifest(workspaceRoot) {
     const packageJsonPath = node_path_1.default.join(workspaceRoot, "package.json");
     const exists = await (0, workspace_1.fileExists)(packageJsonPath);

package/dist/core/workspace.js

@@ -61,6 +61,7 @@ function getPlanningPackPaths(root, options = {}) {
         executionLog: node_path_1.default.join(dir, "execution-log.md"),
         planningState: node_path_1.default.join(dir, "planning-state.json"),
         autoRunState: node_path_1.default.join(dir, "auto-run-state.json"),
+        adviceState: node_path_1.default.join(dir, "advice-state.json"),
         activePlanFile: node_path_1.default.join(planningRoot, exports.ACTIVE_PLAN_FILE)
     };
 }
@@ -180,7 +181,8 @@ async function hasDefaultPlanPresence(root) {
         fileExists(paths.executionState),
         fileExists(paths.executionLog),
         fileExists(paths.planningState),
-        fileExists(paths.autoRunState)
+        fileExists(paths.autoRunState),
+        fileExists(paths.adviceState)
     ]);
     return checks.some(Boolean);
 }

package/dist/ui/studio.js

@@ -15,13 +15,16 @@ const auto_run_1 = require("../core/auto-run");
 const agent_1 = require("../core/agent");
 const execution_controls_1 = require("../core/execution-controls");
 const execution_state_1 = require("../core/execution-state");
+const planning_advice_1 = require("../core/planning-advice");
 const planning_pack_state_1 = require("../core/planning-pack-state");
 const planning_state_1 = require("../core/planning-state");
 const studio_session_1 = require("../core/studio-session");
 const templates_1 = require("../core/templates");
 const workspace_1 = require("../core/workspace");
-const READY_FOOTER = " PgUp/PgDn scroll   /agents choose tool   /help commands ";
+const READY_FOOTER = " PgUp/PgDn scroll   /agents choose tool   /help commands   /quit exit ";
 const ACTIVITY_FRAMES = ["[    ]", "[=   ]", "[==  ]", "[=== ]", "[ ===]", "[  ==]", "[   =]"];
+const COMPOSER_CURSOR = "{black-fg}{#ffb14a-bg} {/}";
+const escapeBlessedText = blessed_1.default.helpers.escape;
 async function launchStudio(options = {}) {
     let workspace = (0, workspace_1.resolveWorkspace)(options.workspace);
     let planId = await (0, workspace_1.resolvePlanId)(workspace, options.planId);
@@ -99,14 +102,21 @@ async function launchStudio(options = {}) {
             }
         }
     });
-    const input = blessed_1.default.textarea({
+    const input = blessed_1.default.box({
         bottom: 1,
         left: 0,
         width: "100%",
         height: 4,
-        inputOnFocus: true,
         keys: true,
         mouse: true,
+        tags: true,
+        clickable: true,
+        padding: {
+            top: 0,
+            right: 1,
+            bottom: 0,
+            left: 1
+        },
         border: {
             type: "line"
         },
@@ -119,7 +129,6 @@ async function launchStudio(options = {}) {
             }
         }
     });
-    configureComposer(input);
     const footer = blessed_1.default.box({
         bottom: 0,
         left: 0,
@@ -148,6 +157,8 @@ async function launchStudio(options = {}) {
     let trackerSummary = "loading...";
     let executionSummary = "never run";
     let autoSummary = "idle";
+    let adviceSummary = "run /advice for AI guidance";
+    let composerValue = "";
     function setSidebar(status) {
         const planningPaths = (0, workspace_1.getPlanningPackPaths)(workspace, { planId });
         sidebar.setContent([
@@ -171,6 +182,9 @@ async function launchStudio(options = {}) {
             "{bold}Auto{/bold}",
             autoSummary,
             "",
+            "{bold}Advice{/bold}",
+            adviceSummary,
+            "",
             "{bold}State{/bold}",
             status ?? getActivityState()
         ].join("\n"));
@@ -236,6 +250,10 @@ async function launchStudio(options = {}) {
         transcript.setContent(rendered);
         transcript.setScrollPerc(100);
     }
+    function renderComposer() {
+        const escapedValue = escapeBlessedText(composerValue);
+        input.setContent(`${escapedValue}${COMPOSER_CURSOR}`);
+    }
     function scrollTranscript(lines) {
         transcript.scroll(lines);
         screen.render();
@@ -254,6 +272,56 @@ async function launchStudio(options = {}) {
         setFooter();
         screen.render();
     }
+    async function submitComposer() {
+        const rawValue = composerValue;
+        const text = rawValue.trim();
+        composerValue = "";
+        renderComposer();
+        if (!text || (busy && text !== "/stop")) {
+            screen.render();
+            return;
+        }
+        if (text.startsWith("/")) {
+            await handleSlashCommand(text);
+            input.focus();
+            renderComposer();
+            screen.render();
+            return;
+        }
+        startBusy("planner");
+        await appendMessage({
+            role: "user",
+            content: text
+        });
+        renderTranscript();
+        setSidebar();
+        setFooter();
+        renderComposer();
+        screen.render();
+        try {
+            const reply = await (0, agent_1.requestPlannerReply)(workspace, messages, { planId });
+            await appendMessage({
+                role: "assistant",
+                content: reply
+            });
+            await refreshAdvice(false);
+        }
+        catch (error) {
+            await appendMessage({
+                role: "system",
+                content: `Planner call failed: ${error instanceof Error ? error.message : String(error)}`
+            });
+        }
+        finally {
+            stopBusy();
+            renderTranscript();
+            setSidebar();
+            setFooter();
+            renderComposer();
+            input.focus();
+            screen.render();
+        }
+    }
     async function refreshEnvironment() {
         const [storedAgentId, packState] = await Promise.all([
             (0, studio_session_1.loadStoredActiveAgentId)(workspace, { planId }),
@@ -273,9 +341,11 @@ async function launchStudio(options = {}) {
         trackerSummary = formatTrackerSummary(packState.currentPosition);
         executionSummary = formatExecutionSummary(packState.lastExecution);
         autoSummary = formatAutoSummary(packState);
+        adviceSummary = formatAdviceSummary(packState.advice);
         setSidebar();
         setFooter();
         renderTranscript();
+        renderComposer();
         screen.render();
     }
     async function switchPlan(nextPlanId) {
@@ -284,6 +354,20 @@ async function launchStudio(options = {}) {
         messages = await (0, studio_session_1.loadStudioSession)(workspace, { planId });
         await refreshEnvironment();
     }
+    async function refreshAdvice(showInTranscript = false) {
+        try {
+            const advice = await (0, planning_advice_1.refreshPlanningAdvice)(workspace, messages, { planId });
+            await refreshEnvironment();
+            if (showInTranscript) {
+                await appendSystemMessage(renderAdviceMessage(advice));
+            }
+        }
+        catch (error) {
+            if (showInTranscript) {
+                await appendSystemMessage(`Advice refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
     async function handleSlashCommand(command) {
         if (command === "/quit") {
             screen.destroy();
@@ -363,6 +447,17 @@ async function launchStudio(options = {}) {
             await appendSystemMessage(renderReadinessMessage(packState));
             return;
         }
+        if (command === "/advice") {
+            startBusy("planner", "refreshing AI advice...");
+            try {
+                await refreshAdvice(true);
+            }
+            finally {
+                stopBusy();
+                await refreshEnvironment();
+            }
+            return;
+        }
         if (command === "/stop") {
             const state = await (0, auto_run_1.requestAutoRunStop)(workspace, { planId });
             await refreshEnvironment();
@@ -404,9 +499,10 @@ async function launchStudio(options = {}) {
                 "1. Talk normally to sharpen the plan against the real repo.",
                 "2. Use `/plans`, `/plan`, and `/plan new <id>` to manage named planning packs in this workspace.",
                 "3. Use `/readiness` to see what context is still missing before you write the pack.",
-                "4. Run `/write` when the plan is ready to put on disk.",
-                "5. Run `/preview` for a safe execution preview, `/run` for one execution step, or `/auto [max]` for continuous execution.",
-                "6. Run `/stop` to stop auto mode after the current iteration.",
+                "4. Run `/advice` for an AI assessment of the problem statement, clarity, research gaps, and next move.",
+                "5. Run `/write` when the plan is ready to put on disk.",
+                "6. Run `/preview` for a safe execution preview, `/run` for one execution step, or `/auto [max]` for continuous execution.",
+                "7. Run `/stop` to stop auto mode after the current iteration.",
                 "",
                 "Controls:",
                 "- `Enter` sends the current message or command.",
@@ -432,6 +528,7 @@ async function launchStudio(options = {}) {
             try {
                 const result = await (0, agent_1.writePlanningPack)(workspace, messages, { planId });
                 await (0, planning_state_1.markPlanningPackAuthored)(workspace, { planId });
+                await refreshAdvice(false);
                 await appendSystemMessage(`Planning pack updated for \`${planId}\`. Summary:\n${result}`);
             }
             catch (error) {
@@ -459,6 +556,7 @@ async function launchStudio(options = {}) {
                     planId,
                     stepLabel: packState.nextStepSummary?.id ?? packState.currentPosition.nextRecommended
                 });
+                await refreshAdvice(false);
                 await appendSystemMessage(`Execution run finished. ${(0, agent_1.getPrimaryAgentAdapter)().label} summary:\n${result}`);
             }
             catch (error) {
@@ -490,6 +588,7 @@ async function launchStudio(options = {}) {
                         await appendSystemMessage(line);
                     }
                 });
+                await refreshAdvice(false);
                 await appendSystemMessage(`Auto mode finished: ${result.summary}`);
             }
             catch (error) {
@@ -503,46 +602,36 @@ async function launchStudio(options = {}) {
         }
         await appendSystemMessage(`Unknown command: ${command}`);
     }
-    input.on("submit", async (value) => {
-        const text = value.trim();
-        input.clearValue();
-        if (!text || (busy && text !== "/stop")) {
-            screen.render();
+    input.on("click", () => {
+        input.focus();
+        screen.render();
+    });
+    input.on("keypress", async (ch, key) => {
+        if (key.name === "pageup" || key.name === "ppage" || key.name === "pagedown" || key.name === "npage") {
             return;
         }
-        if (text.startsWith("/")) {
-            await handleSlashCommand(text);
-            input.focus();
+        if (key.name === "enter" && !key.shift && !key.meta && !key.ctrl) {
+            await submitComposer();
             return;
         }
-        startBusy("planner");
-        await appendMessage({
-            role: "user",
-            content: text
-        });
-        renderTranscript();
-        setSidebar();
-        setFooter();
-        screen.render();
-        try {
-            const reply = await (0, agent_1.requestPlannerReply)(workspace, messages, { planId });
-            await appendMessage({
-                role: "assistant",
-                content: reply
-            });
+        if ((key.name === "enter" && (key.shift || key.meta)) || (key.ctrl && key.name === "j")) {
+            composerValue += "\n";
+            renderComposer();
+            screen.render();
+            return;
         }
-        catch (error) {
-            await appendMessage({
-                role: "system",
-                content: `Planner call failed: ${error instanceof Error ? error.message : String(error)}`
-            });
+        if (key.name === "backspace") {
+            composerValue = removeLastCodePoint(composerValue);
+            renderComposer();
+            screen.render();
+            return;
         }
-        finally {
-            stopBusy();
-            renderTranscript();
-            setSidebar();
-            setFooter();
-            input.focus();
+        if (key.ctrl || key.meta) {
+            return;
+        }
+        if (ch && !/^[\x00-\x08\x0b-\x0c\x0e-\x1f\x7f]$/.test(ch)) {
+            composerValue += ch;
+            renderComposer();
             screen.render();
         }
     });
@@ -563,8 +652,10 @@ async function launchStudio(options = {}) {
         });
     }
     renderTranscript();
+    renderComposer();
     setSidebar("booting...");
     setFooter(" Starting studio... ");
+    screen.program.hideCursor();
     screen.render();
     input.focus();
     await refreshEnvironment();
@@ -633,6 +724,17 @@ function formatAutoSummary(packState) {
     }
     return lines.join("\n");
 }
+function formatAdviceSummary(advice) {
+    if (!advice) {
+        return "run /advice for AI guidance";
+    }
+    const lines = [
+        `problem: ${advice.problemStatement}`,
+        `clarity: ${advice.clarity}`,
+        `next: ${advice.nextAction}`
+    ];
+    return lines.join("\n");
+}
 function formatAgentSummary(activeAgent, statuses) {
     return [`active: ${activeAgent.label}`, ...statuses.map((status) => formatAgentStatusLine(status, status.id === activeAgent.id))]
         .join("\n");
@@ -774,28 +876,8 @@ function deriveDisplayMode(packState) {
     }
     return packState.trackerReadable ? "Plan Written - Needs Step" : "Gathering Context";
 }
-function configureComposer(input) {
-    const internals = input;
-    const originalListener = internals._listener;
-    if (!originalListener) {
-        return;
-    }
-    internals._listener = function patchedListener(ch, key) {
-        if (key.name === "enter" && !key.shift && !key.meta && !key.ctrl) {
-            if (typeof internals._done === "function") {
-                internals._done(null, internals.value ?? "");
-            }
-            return;
-        }
-        if ((key.name === "enter" && (key.shift || key.meta)) || (key.ctrl && key.name === "j")) {
-            originalListener.call(this, "\n", { ...key, name: "enter" });
-            return;
-        }
-        originalListener.call(this, ch, key);
-    };
-}
 function renderStatusMessage(workspace, packState) {
-    return [
+    const lines = [
         `Plan: ${packState.planId}`,
         `Planning dir: ${(0, workspace_1.getPlanningPackPaths)(workspace, { planId: packState.planId }).relativeDir}`,
         `Mode: ${packState.mode}${packState.hasFailureOverlay ? " [last run failed]" : ""}`,
@@ -804,7 +886,11 @@ function renderStatusMessage(workspace, packState) {
         `Execution activated: ${packState.executionActivated ? "yes" : "no"}`,
         `Auto mode: ${packState.autoRun?.status ?? "idle"}`,
         `Next step: ${packState.nextStepSummary?.id ?? packState.currentPosition.nextRecommended ?? "none queued"}`
-    ].join("\n");
+    ];
+    if (packState.advice) {
+        lines.push(`Advice next: ${packState.advice.nextAction}`);
+    }
+    return lines.join("\n");
 }
 function renderReadinessMessage(packState) {
     return [
@@ -820,6 +906,19 @@ function renderReadinessMessage(packState) {
             : "Next: keep gathering repo truth, constraints, and the first execution slice."
     ].join("\n");
 }
+function renderAdviceMessage(advice) {
+    return [
+        `Problem: ${advice.problemStatement}`,
+        `Clarity: ${advice.clarity}`,
+        `Assessment: ${advice.stateAssessment}`,
+        `Research: ${advice.researchNeeded.length > 0 ? advice.researchNeeded.join(" | ") : "none"}`,
+        `Advice: ${advice.advice}`,
+        `Next: ${advice.nextAction}`
+    ].join("\n");
+}
+function removeLastCodePoint(value) {
+    return Array.from(value).slice(0, -1).join("");
+}
 function renderPlanUsageMessage(currentPlanId, paths) {
     return [
         `Current plan: ${currentPlanId}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launch11/srgical",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "A polished local-first CLI for planning and executing long AI-driven delivery sequences.",
   "files": [
     "dist",