@pentoshi/clai 3.5.1 → 3.7.2

package/dist/agent/plan-tool.js

@@ -1,7 +1,161 @@
 import chalk from "chalk";
-import { createPlan, loadPlan, savePlan, markTask, } from "../store/plan.js";
+import { createPlan, loadPlan, savePlan, markTask, isBareTaskIdTitle, isPlanTerminal, isPlanSuccessful, readyPlanTasks, validateSessionPlan, } from "../store/plan.js";
 import { renderPlanChecklist } from "../ui/plan-pane.js";
 import { isLumpedSingleTask } from "./tool-call-parser.js";
+import { getActiveProjectRoot } from "./project-root.js";
+import { detectPackageManager } from "./workspace-orient.js";
+/** Titles match for plan merge (exact or mutual long substring). */
+export function titlesMatchForPlan(a, b) {
+    const t1 = a.trim().toLowerCase();
+    const t2 = b.trim().toLowerCase();
+    return (t1 === t2 ||
+        (t1.length > 8 && t2.length > 8 && (t1.includes(t2) || t2.includes(t1))));
+}
+/** Final coding-plan task: start server / probe localhost / leave running. */
+export function looksLikeRunServerTask(title) {
+    const t = title.trim().toLowerCase();
+    if (/\b(dev\s*server|npm\s+run\s+dev|pnpm\s+(run\s+)?dev|yarn\s+dev|bun\s+run\s+dev|shell\.start|localhost|leave\s+(it\s+)?running|verify\s+in\s+browser|open\s+in\s+browser|probe\s+(localhost|http)|http:\/\/localhost)\b/.test(t)) {
+        return true;
+    }
+    if (/\b(start|run)\b.+\b(server|dev|vite|next|preview)\b/.test(t))
+        return true;
+    if (/\b(server|dev|vite|next|preview)\b.+\b(start|run|verify|tail|probe)\b/.test(t)) {
+        return true;
+    }
+    // "run and verify" / "start app" style finals
+    if (/\b(run|start)\b.+\b(app|verify)\b/.test(t) && /\b(server|dev|browser|localhost|url|port|job)\b/.test(t)) {
+        return true;
+    }
+    return false;
+}
+export function looksLikeLocalAppScaffold(kind, goal, detail, tasks) {
+    if (kind === "pentest")
+        return false;
+    const blob = `${kind} ${goal} ${detail} ${tasks.join(" ")}`.toLowerCase();
+    // Pure libraries / CLIs with no server surface
+    if (/\b(library|cli\b|command[- ]line|npm package|rust crate|go module)\b/.test(blob) &&
+        !/\b(react|vite|next|vue|svelte|web\s*app|frontend|dev\s*server|localhost|todo\s*app|dashboard|spa)\b/.test(blob)) {
+        return false;
+    }
+    if (kind === "coding") {
+        // coding + no library-only signal → require run/verify when app-like
+        return /\b(app|react|vite|next|vue|svelte|nuxt|angular|frontend|web|ui|todo|blog|dashboard|spa|server|localhost|scaffold)\b/.test(blob);
+    }
+    return /\b(react|vite|next\.?js?|vue|svelte|nuxt|angular|web\s*app|frontend|spa|todo\s*app|blog\s*app|dashboard)\b/.test(blob);
+}
+export function codingPlanNeedsRunVerifyTask(kind, goal, detail, tasks) {
+    if (!looksLikeLocalAppScaffold(kind, goal, detail, tasks))
+        return false;
+    return !tasks.some(looksLikeRunServerTask);
+}
+function looksLikeInstallTask(title) {
+    const t = title.toLowerCase();
+    return (/\b(install|dependencies|deps|packages)\b/.test(t) &&
+        !/\b(dev\s*server|localhost|probe|run\s+dev)\b/.test(t));
+}
+function looksLikeScaffoldishTask(title) {
+    return /\b(scaffold|create|init|vite|next|bootstrap|cargo\s+new)\b/i.test(title);
+}
+/**
+ * Ensure coding app plans have an explicit install step after scaffold.
+ * Avoids "implement blocked from npm install" + install attributed to wrong task.
+ */
+export function ensureCodingPlanInstallTask(kind, goal, detail, tasks) {
+    if (!looksLikeLocalAppScaffold(kind, goal, detail, tasks))
+        return tasks;
+    if (tasks.some(looksLikeInstallTask))
+        return tasks;
+    if (!tasks.some(looksLikeScaffoldishTask))
+        return tasks;
+    const out = [...tasks];
+    const scaffoldIdx = out.findIndex(looksLikeScaffoldishTask);
+    const insertAt = scaffoldIdx >= 0 ? scaffoldIdx + 1 : 0;
+    out.splice(insertAt, 0, "Install project dependencies (npm/yarn/pnpm/bun install in project root)");
+    return out;
+}
+function looksLikeFeatureImplementTask(title) {
+    const t = title.toLowerCase();
+    if (looksLikeInstallTask(title) || looksLikeRunServerTask(title))
+        return false;
+    if (looksLikeScaffoldishTask(title) && !/\b(feature|todo|component|ui)\b/.test(t)) {
+        return false;
+    }
+    return (/\b(implement|feature|todo|component|ui|crud|auth|localstorage|persist|integrate)\b/.test(t) ||
+        (/\b(add|build|write|create)\b/.test(t) &&
+            /\b(todo|feature|component|page|ui|list|form)\b/.test(t)));
+}
+function looksLikeFeatureAppPlan(goal, detail, tasks) {
+    const blob = `${goal}\n${detail}\n${tasks.join("\n")}`.toLowerCase();
+    if (/\b(just|only)\s+(scaffold|init|boilerplate|starter)\b/.test(blob)) {
+        return false;
+    }
+    return (/\b(todo|to-?do|blog|dashboard|chat|kanban|notes?|crm|shop|auth|login|crud|portfolio)\b/.test(blob) &&
+        /\b(app|application|project|site|ui|feature)\b/.test(blob));
+}
+/**
+ * Ensure feature-app plans include an implement-feature task (not scaffold-only).
+ */
+export function ensureCodingPlanFeatureTask(kind, goal, detail, tasks) {
+    if (!looksLikeLocalAppScaffold(kind, goal, detail, tasks))
+        return tasks;
+    if (!looksLikeFeatureAppPlan(goal, detail, tasks))
+        return tasks;
+    if (tasks.some(looksLikeFeatureImplementTask))
+        return tasks;
+    const out = [...tasks];
+    // Insert after install if present, else after scaffold, else before last (verify)
+    const installIdx = out.findIndex(looksLikeInstallTask);
+    const scaffoldIdx = out.findIndex(looksLikeScaffoldishTask);
+    const runIdx = out.findIndex(looksLikeRunServerTask);
+    let insertAt;
+    if (installIdx >= 0)
+        insertAt = installIdx + 1;
+    else if (scaffoldIdx >= 0)
+        insertAt = scaffoldIdx + 1;
+    else if (runIdx >= 0)
+        insertAt = runIdx;
+    else
+        insertAt = out.length;
+    out.splice(insertAt, 0, "Implement the requested product feature (replace starter boilerplate with real UI/state)");
+    return out;
+}
+/** Ensure local app plans end with shell.start + probe + leave running. */
+export function ensureCodingPlanRunVerifyTask(kind, goal, detail, tasks) {
+    if (!looksLikeLocalAppScaffold(kind, goal, detail, tasks))
+        return tasks;
+    if (tasks.some(looksLikeRunServerTask))
+        return tasks;
+    return [
+        ...tasks,
+        "Start dev server with shell.start, probe localhost, leave running, report URL/port/job id",
+    ];
+}
+/** Preserve the model/user-authored checklist exactly for fresh coding plans. */
+export function normalizeCodingPlanTasks(_kind, _goal, _detail, tasks) {
+    return [...tasks];
+}
+/** Goal is only "run/start the existing app" — do not open a new plan. */
+export function looksLikeRunOnlyGoal(goal, detail) {
+    const blob = `${goal} ${detail}`.toLowerCase();
+    if (!/\b(run|start|launch|serve|dev\s*server|npm\s+run\s+dev)\b/.test(blob)) {
+        return false;
+    }
+    // Exclude fresh scaffold goals
+    if (/\b(scaffold|create|build|implement|add feature|from scratch|new app)\b/.test(blob)) {
+        return false;
+    }
+    return /\b(existing|already|the app|dev server|server|verify|test it|open it)\b/.test(blob)
+        || /^(run|start)\b/.test(blob.trim());
+}
+function nextTaskId(existingIds) {
+    let max = 0;
+    for (const id of existingIds) {
+        const m = /^t(\d+)$/i.exec(id);
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return `t${max + 1}`;
+}
 /** Coerce model-sloppy plan.create fields into clean titles. */
 function normalizePlanGoal(args) {
     const raw = args.goal ?? args.objective ?? args.title ?? args.name;
@@ -59,21 +213,92 @@ function normalizeTaskTitle(t) {
     }
     return "";
 }
+export function slugifyTaskId(text) {
+    return text
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 64);
+}
 /**
  * Accept tasks as string[], object[], or a single newline/comma-separated string.
  * Models frequently emit `[{id,title}]` instead of plain strings.
  */
 function normalizePlanTasks(args) {
+    return normalizePlanTaskEntries(args).map((t) => t.title);
+}
+/** Full entries including model-supplied id/name aliases (X3). */
+export function normalizePlanTaskEntries(args) {
     const raw = args.tasks ?? args.steps ?? args.checklist ?? args.items ?? args.todos;
     if (typeof raw === "string") {
         return raw
             .split(/\n|;|(?:,\s*(?=[A-Z0-9\-]))/)
             .map((s) => s.replace(/^\s*[-*\d.)]+\s*/, "").trim())
-            .filter(Boolean);
+            .filter(Boolean)
+            .map((title) => ({
+            title,
+            aliases: [],
+            dependencies: [],
+            dependenciesSpecified: false,
+            resourceLocks: [],
+        }));
     }
     if (!Array.isArray(raw))
         return [];
-    return raw.map(normalizeTaskTitle).filter(Boolean);
+    return raw
+        .map((t) => {
+        const title = normalizeTaskTitle(t);
+        if (!title || isBareTaskIdTitle(title))
+            return null;
+        const aliases = [];
+        if (t && typeof t === "object") {
+            const o = t;
+            for (const k of ["id", "taskId", "key", "slug"]) {
+                if (typeof o[k] === "string" && o[k].toString().trim()) {
+                    aliases.push(String(o[k]).trim());
+                }
+            }
+            // `name` is often the title; only alias if it differs.
+            if (typeof o.name === "string" &&
+                o.name.trim() &&
+                o.name.trim().toLowerCase() !== title.toLowerCase()) {
+                aliases.push(o.name.trim());
+            }
+        }
+        const slug = slugifyTaskId(title);
+        if (slug && !aliases.includes(slug))
+            aliases.push(slug);
+        const object = t && typeof t === "object" ? t : {};
+        const stringArray = (value) => Array.isArray(value)
+            ? [...new Set(value.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean))]
+            : [];
+        return {
+            title,
+            aliases: [...new Set(aliases)],
+            dependencies: stringArray(object.dependencies ?? object.dependsOn),
+            dependenciesSpecified: Object.prototype.hasOwnProperty.call(object, "dependencies") ||
+                Object.prototype.hasOwnProperty.call(object, "dependsOn"),
+            resourceLocks: stringArray(object.resourceLocks ?? object.resources),
+        };
+    })
+        .filter((x) => Boolean(x));
+}
+/** Resolve model taskId (t1 or slug) to the canonical plan task id. */
+export function resolvePlanTaskId(plan, taskId) {
+    const raw = taskId.trim();
+    if (!raw)
+        return undefined;
+    if (plan.tasks.some((t) => t.id === raw))
+        return raw;
+    const lower = raw.toLowerCase();
+    const slug = slugifyTaskId(raw);
+    for (const t of plan.tasks) {
+        if (t.aliases?.some((a) => a === raw || a.toLowerCase() === lower)) {
+            return t.id;
+        }
+    }
+    return undefined;
 }
 /** Render the portable inline form; the Ink TUI owns its responsive sidebar. */
 export function renderPlanForTerminal(plan) {
@@ -82,40 +307,57 @@ export function renderPlanForTerminal(plan) {
 /** Build the system-context block describing the session's active plan. */
 export function planContextMessage(plan, approved) {
     const lines = [];
-    lines.push(`ACTIVE PLAN for this session (goal: ${plan.goal}, status: ${plan.status}):`);
+    lines.push(`ACTIVE PLAN v${plan.version ?? 1} for this session (goal: ${plan.goal}, status: ${plan.status}):`);
     if (plan.detail.trim())
         lines.push(plan.detail.trim());
     lines.push("Tasks:");
     plan.tasks.forEach((t, i) => {
-        lines.push(`  ${i + 1}. [${t.id}] (${t.state}) ${t.title}`);
+        const aliasHint = t.aliases?.length && t.aliases[0] !== t.id
+            ? ` [aliases: ${t.aliases.slice(0, 3).join(", ")}]`
+            : "";
+        const dependencyHint = t.dependencies?.length
+            ? ` [depends: ${t.dependencies.join(", ")}]`
+            : "";
+        const resourceHint = t.resourceLocks?.length
+            ? ` [locks: ${t.resourceLocks.join(", ")}]`
+            : "";
+        const evidenceHint = t.evidence?.successWorkCount
+            ? ` [evidence: ${t.evidence.successWorkCount} successful tool${t.evidence.successWorkCount === 1 ? "" : "s"}${t.evidence.lastOkTool ? `; last ${t.evidence.lastOkTool}` : ""}]`
+            : "";
+        lines.push(`  ${i + 1}. [${t.id}] (${t.state}) ${t.title}${aliasHint}${dependencyHint}${resourceHint}${evidenceHint}`);
     });
+    lines.push("task.update taskId MUST be t1, t2, … from this list (or a listed alias) — never invent free-form slugs alone.");
+    if (plan.meta?.projectRoot) {
+        lines.push(`project_root: ${plan.meta.projectRoot}`);
+    }
+    if (plan.meta?.packageManager) {
+        lines.push(`package_manager: ${plan.meta.packageManager}`);
+    }
     if (approved) {
         const inProgress = plan.tasks.find((t) => t.state === "in_progress");
-        const firstPending = plan.tasks.find((t) => t.state === "pending");
-        lines.push("The user APPROVED this plan. Execute it task by task NOW.");
+        const firstPending = readyPlanTasks(plan)[0];
+        lines.push("The user APPROVED this plan. Execute it NOW. Tasks are checkpoints — you still own the whole goal.");
         if (inProgress) {
             lines.push(`RESUME TASK ${inProgress.id} (${inProgress.title}) — it was started but interrupted. ` +
                 "Retry what was in progress; do NOT restart completed work from scratch. " +
-                "Do NOT re-do tasks already marked done, and do NOT skip ahead to later tasks.");
+                "Do NOT re-do tasks already marked done.");
         }
         else if (firstPending) {
             lines.push(`START WITH TASK ${firstPending.id} (${firstPending.title}). ` +
-                "Do NOT re-do tasks already marked done, and do NOT skip ahead to later tasks.");
+                "Do NOT re-do tasks already marked done.");
         }
-        lines.push("STRICT ORDER: call task.update {taskId, state:'in_progress'} → do the real work → " +
-            "call task.update {taskId, state:'done'} ONLY after the tool calls actually succeed. " +
-            "If a tool fails, mark the task 'failed' with a note, fix the problem, then retry. " +
-            "Do NOT mark a task done when its commands error out. " +
-            "Never claim something ran without a successful tool call.");
+        lines.push("Flow: task.update in_progress → real work → WAIT for and READ the tool result → " +
+            "mark done only when verified → next task. Durable evidence shown beside a task survives resume; use it to close that task rather than repeating already-confirmed work. " +
+            "Independent read-only lookups may parallelize within a task. " +
+            "Never mark done before successful relevant evidence. If a tool fails: mark failed, fix, retry. " +
+            "For run/verify: prove runtime (shell.start, ready tail, LISTEN, or localhost GET), leave server running, final message includes URL, port, and job id. " +
+            "Do not re-open done tasks. If mid-task evidence shows the plan is wrong, adapt (fix root cause; for pentest, revise plan with completed tasks preserved).");
     }
     else {
-        lines.push("This plan is NOT yet approved, so you MUST NOT execute any of its tasks yet. " +
-            "Any new free-text message from the user right now is a PLAN REVISION, not approval — even if it " +
-            "sounds like an instruction (e.g. 'do not install new tools', 'use only X', 'also add Y', 'skip task 2'). " +
-            "Treat it as feedback: call plan.create AGAIN with the revised goal/detail/tasks to produce an updated " +
-            "plan, then STOP and wait. Do NOT call shell.exec, pkg.install, net.scan, tool.check, fs.write, or any " +
-            "other execution tool. The user will APPROVE with /implement, or CANCEL with /discard. Only after " +
-            "/implement may you begin executing.");
+        lines.push("This plan is NOT yet approved — do not execute tasks (no scaffold/write/install/exploit). " +
+            "User free-text is PLAN REVISION feedback, not approval — even if it sounds like an instruction. " +
+            "Refine with plan.create and/or read-only explore/research, then STOP. " +
+            "User may Accept, Discard, View, or Suggest changes (or /implement / /discard).");
     }
     return lines.join("\n");
 }
@@ -125,12 +367,15 @@ export function planContextMessage(plan, approved) {
  * the agent keeps it in context across the whole session.
  */
 export async function handlePlanTool(call, session, ctx) {
-    void ctx;
+    const autoApprove = Boolean(ctx.autoApprove);
+    void ctx.loopGuard;
+    void ctx.step;
     if (call.name === "plan.create") {
         const goal = normalizePlanGoal(call.args);
         const detail = normalizePlanDetail(call.args);
         const kind = normalizePlanKind(call.args);
-        const taskTitles = normalizePlanTasks(call.args);
+        const taskEntries = normalizePlanTaskEntries(call.args);
+        const taskTitles = taskEntries.map((t) => t.title);
         if (!goal || taskTitles.length === 0) {
             return {
                 handled: true,
@@ -150,67 +395,219 @@ export async function handlePlanTool(call, session, ctx) {
                 handled: true,
                 ok: false,
                 display: chalk.red("  ✗ plan.create: that single task lumps the whole build into one step\n"),
-                modelNote: "plan.create rejected: you put everything into ONE task. Break it into 3-8 SEPARATE, " +
-                    "ordered tasks — each a distinct action, e.g. 'scaffold package.json + vite config', " +
-                    "'create index.html + entry (main.jsx)', 'build App + Post components', 'add posts data + styles', " +
-                    "'install deps and run dev server to verify'. Call plan.create again with that tasks array.",
+                modelNote: "plan.create rejected: you put everything into ONE task. Break it into separate " +
+                    "ordered tasks — each a distinct action (scaffold, implement feature, install, run/verify). " +
+                    "Call plan.create again with a proper tasks array.",
             };
         }
         const existingPlan = await loadPlan(session.sessionId).catch(() => undefined);
+        // X12: do not open a second full plan just to run an existing app.
+        if (existingPlan &&
+            (existingPlan.status === "completed" ||
+                existingPlan.tasks.every((t) => t.state === "done" || t.state === "skipped" || t.state === "failed")) &&
+            looksLikeRunOnlyGoal(goal, detail)) {
+            return {
+                handled: true,
+                ok: false,
+                display: chalk.yellow("  ⚠ plan.create skipped — use tools to run the existing app\n"),
+                modelNote: "plan.create rejected: the previous plan is already finished and this goal is only run/verify. " +
+                    "Do NOT create a new plan or re-list old scaffold tasks. " +
+                    "Just shell.start the dev server, shell.tail until ready, probe localhost " +
+                    "(curl or http.fetch with iOwnThis:true), LEAVE the server running, and tell the user " +
+                    "the URL (http://localhost:<port>), port, and job id.",
+            };
+        }
+        // Preserve authored task count/order. Build, install, and verification
+        // evidence may span tasks; the runtime must not inject regex-derived
+        // checkpoints that change IDs or make progress diverge from the plan.
+        const normalizedTitles = existingPlan
+            ? taskTitles
+            : normalizeCodingPlanTasks(kind, goal, detail, taskTitles);
+        const root = getActiveProjectRoot();
+        const pm = root ? detectPackageManager(root) : undefined;
+        const meta = root || existingPlan?.meta
+            ? {
+                ...(existingPlan?.meta ?? {}),
+                ...(root ? { projectRoot: root } : {}),
+                ...(pm ? { packageManager: pm } : {}),
+            }
+            : undefined;
         const plan = createPlan({
             sessionId: session.sessionId,
             goal,
             detail,
-            taskTitles,
+            taskTitles: normalizedTitles,
             kind,
+            meta,
         });
+        // Attach model-supplied slug aliases so task.update can resolve them (X3).
+        for (let i = 0; i < plan.tasks.length; i++) {
+            const aliases = taskEntries[i]?.aliases ?? [];
+            if (aliases.length)
+                plan.tasks[i].aliases = aliases;
+            const locks = taskEntries[i]?.resourceLocks ?? [];
+            if (locks.length)
+                plan.tasks[i].resourceLocks = locks;
+        }
+        for (let i = 0; i < plan.tasks.length; i++) {
+            const rawDependencies = taskEntries[i]?.dependencies ?? [];
+            const dependencies = rawDependencies.map((dependency) => resolvePlanTaskId(plan, dependency) ?? dependency);
+            if (taskEntries[i]?.dependenciesSpecified) {
+                plan.tasks[i].dependencies = [...new Set(dependencies)];
+            }
+        }
+        let additiveOnly = false;
         if (existingPlan) {
+            plan.version = (existingPlan.version ?? 1) + 1;
+            const usedOldIds = new Set();
             const mappedNewTasks = plan.tasks.map((task) => {
-                const match = existingPlan.tasks.find((t) => {
-                    const t1 = t.title.trim().toLowerCase();
-                    const t2 = task.title.trim().toLowerCase();
-                    return (t1 === t2 ||
-                        (t1.length > 8 && t2.length > 8 && (t1.includes(t2) || t2.includes(t1))));
-                });
+                const match = existingPlan.tasks.find((t) => !usedOldIds.has(t.id) && titlesMatchForPlan(t.title, task.title));
                 if (match) {
+                    usedOldIds.add(match.id);
                     return {
                         ...task,
+                        id: match.id,
                         state: match.state,
                         note: match.note,
+                        evidence: match.evidence,
                     };
                 }
                 return task;
             });
-            const oldTasksToKeep = existingPlan.tasks.filter((oldTask) => {
-                return !mappedNewTasks.some((newTask) => {
-                    const t1 = oldTask.title.trim().toLowerCase();
-                    const t2 = newTask.title.trim().toLowerCase();
-                    return (t1 === t2 ||
-                        (t1.length > 8 && t2.length > 8 && (t1.includes(t2) || t2.includes(t1))));
-                });
+            // Free ids for brand-new tasks (avoid clobbering preserved ids).
+            const taken = new Set(mappedNewTasks.map((t) => t.id));
+            for (const task of mappedNewTasks) {
+                if (usedOldIds.has(task.id))
+                    continue;
+                if (existingPlan.tasks.some((t) => t.id === task.id) ||
+                    mappedNewTasks.filter((t) => t.id === task.id).length > 1) {
+                    let id = nextTaskId([...taken]);
+                    while (taken.has(id))
+                        id = nextTaskId([...taken, id]);
+                    task.id = id;
+                    taken.add(id);
+                }
+                else {
+                    taken.add(task.id);
+                }
+            }
+            const oldTasksToKeep = existingPlan.tasks.filter((oldTask) => !isBareTaskIdTitle(oldTask.title) &&
+                !mappedNewTasks.some((newTask) => titlesMatchForPlan(oldTask.title, newTask.title)));
+            plan.tasks = [...oldTasksToKeep, ...mappedNewTasks].filter((t) => !isBareTaskIdTitle(t.title));
+            const finalIdByInputReference = new Map();
+            for (let index = 0; index < mappedNewTasks.length; index += 1) {
+                const task = mappedNewTasks[index];
+                const entry = taskEntries[index];
+                finalIdByInputReference.set(`t${index + 1}`, task.id);
+                finalIdByInputReference.set(task.id, task.id);
+                finalIdByInputReference.set(slugifyTaskId(task.title), task.id);
+                for (const alias of entry?.aliases ?? []) {
+                    finalIdByInputReference.set(alias, task.id);
+                }
+            }
+            for (let index = 0; index < mappedNewTasks.length; index += 1) {
+                const task = mappedNewTasks[index];
+                const entry = taskEntries[index];
+                const references = entry?.dependenciesSpecified
+                    ? entry.dependencies
+                    : index > 0
+                        ? [`t${index}`]
+                        : [];
+                task.dependencies = [...new Set(references.map((reference) => finalIdByInputReference.get(reference) ??
+                        resolvePlanTaskId(plan, reference) ??
+                        reference))];
+            }
+            // X7: keep approval when only additive pending work remains.
+            const priorFinished = existingPlan.tasks.filter((t) => t.state === "done" || t.state === "skipped" || t.state === "failed");
+            const finishedStillFinished = priorFinished.length > 0 &&
+                priorFinished.every((old) => plan.tasks.some((n) => titlesMatchForPlan(old.title, n.title) &&
+                    (n.state === "done" ||
+                        n.state === "skipped" ||
+                        n.state === "failed")));
+            const hasNewPending = plan.tasks.some((t) => t.state === "pending");
+            const noDoneReopened = !plan.tasks.some((n) => {
+                const old = existingPlan.tasks.find((t) => titlesMatchForPlan(t.title, n.title));
+                return (old &&
+                    (old.state === "done" || old.state === "skipped") &&
+                    n.state === "pending");
             });
-            plan.tasks = [...oldTasksToKeep, ...mappedNewTasks];
+            additiveOnly =
+                finishedStillFinished &&
+                    hasNewPending &&
+                    noDoneReopened &&
+                    (session.planApproved.value ||
+                        existingPlan.status === "approved" ||
+                        existingPlan.status === "in_progress" ||
+                        existingPlan.status === "completed");
+            if (additiveOnly) {
+                plan.status = "in_progress";
+                plan.createdAt = existingPlan.createdAt;
+            }
+        }
+        const dag = validateSessionPlan(plan);
+        if (!dag.ok) {
+            return {
+                handled: true,
+                ok: false,
+                display: chalk.red(`  ✗ plan.create: invalid dependency graph — ${dag.reason}\n`),
+                modelNote: `plan.create failed: ${dag.reason}. Use only declared task ids/aliases and remove dependency cycles.`,
+            };
+        }
+        if (additiveOnly) {
+            session.planApproved.value = true;
+            plan.status = "in_progress";
+        }
+        else if (autoApprove) {
+            session.planApproved.value = true;
+            plan.status = "approved";
+        }
+        else {
+            session.planApproved.value = false;
         }
         await savePlan(plan).catch(() => undefined);
-        // A freshly (re)created plan resets approval — the user must /implement.
-        session.planApproved.value = false;
         const checklist = renderPlanForTerminal(plan);
-        const display = chalk.cyan("  ● planning\n") +
-            checklist +
-            "\n" +
-            chalk.dim("  ✦ plan created — press Ctrl+P to view it, /implement to approve and run it,\n" +
-                "    or /discard to cancel it. Any other message refines this plan.\n");
+        const display = additiveOnly
+            ? chalk.cyan("  ● plan updated (additive)\n") +
+                checklist +
+                "\n" +
+                chalk.dim("  ✦ done tasks preserved — continue from the first pending task only.\n" +
+                    "    Do NOT re-run completed scaffold/build work.\n")
+            : autoApprove
+                ? chalk.cyan("  ● plan created (auto-approved)\n") +
+                    checklist +
+                    "\n" +
+                    chalk.dim("  ✦ plan approved in agent mode — continue executing task by task.\n")
+                : chalk.cyan("  ● planning\n") +
+                    checklist +
+                    "\n" +
+                    chalk.dim("  ✦ plan created — Accept to run, Discard, View, or Suggest changes\n" +
+                        "    (/implement, /discard, Ctrl+P also work).\n");
+        const firstPending = readyPlanTasks(plan)[0];
         return {
             handled: true,
             ok: true,
             plan,
             display,
-            modelNote: `Plan saved with ${plan.tasks.length} task(s). STOP here and wait — produce NO other tool calls now. ` +
-                "Do NOT start executing tasks until the user approves with /implement. " +
-                "If the user's next message gives feedback instead of /implement, that is a REVISION: call plan.create " +
-                "again with the updated plan and STOP again. The user may cancel the whole plan with /discard. " +
-                "Only after /implement do you begin, working task by task, calling task.update to mark each " +
-                "in_progress before and done after you finish it.",
+            modelNote: additiveOnly
+                ? `Plan updated with additive task(s); ${plan.tasks.filter((t) => t.state === "done" || t.state === "skipped").length} prior task(s) stay done. ` +
+                    "Do NOT re-execute completed tasks (no re-scaffold). " +
+                    (firstPending
+                        ? `Continue from [${firstPending.id}] "${firstPending.title}" only. `
+                        : "") +
+                    "If the only new work is run/verify on an existing app, prefer shell.start + probe + report URL — " +
+                    "do not reboot the world. When the run/verify task finishes, final message MUST include " +
+                    "http://localhost:<port>, port, job id, and that the server is still running."
+                : autoApprove
+                    ? `Plan saved and approved with ${plan.tasks.length} task(s). Execute now. ` +
+                        (firstPending
+                            ? `Start with [${firstPending.id}] "${firstPending.title}". `
+                            : "") +
+                        "task.update in_progress → work → verify → done. When run/verify completes: report URL, port, job id, server still running."
+                    : `Plan saved with ${plan.tasks.length} task(s). STOP here and wait — produce NO other tool calls now. ` +
+                        "Do NOT start executing until the user accepts the plan. " +
+                        "If the user's next message gives feedback, that is a REVISION: call plan.create again with the updated plan and STOP again. " +
+                        "The user may discard the plan. After acceptance: task.update in_progress → work → verify → done. " +
+                        "When run/verify completes: report URL, port, job id, and that the server is still running.",
         };
     }
     // task.update
@@ -223,7 +620,11 @@ export async function handlePlanTool(call, session, ctx) {
             modelNote: "task.update failed: there is no active plan. Call plan.create first.",
         };
     }
-    const taskId = typeof call.args.taskId === "string" ? call.args.taskId : "";
+    const taskIdRaw = typeof call.args.taskId === "string"
+        ? call.args.taskId
+        : typeof call.args.id === "string"
+            ? call.args.id
+            : "";
     const stateRaw = typeof call.args.state === "string" ? call.args.state : "";
     const note = typeof call.args.note === "string" ? call.args.note : undefined;
     const validStates = [
@@ -241,50 +642,167 @@ export async function handlePlanTool(call, session, ctx) {
             modelNote: `task.update failed: state must be one of ${validStates.join(", ")}.`,
         };
     }
-    // Only one task may be in_progress at a time. This forces genuine
-    // task-by-task execution: the model must close (done/failed/skipped) the
-    // current task before opening the next one, instead of leaving a task
-    // "in_progress" as an umbrella while it quietly works through the rest
-    // of the plan underneath it.
+    // X3: accept t1..tn or model slug aliases / title slugs.
+    const taskId = resolvePlanTaskId(plan, taskIdRaw) ?? taskIdRaw;
     if (stateRaw === "in_progress") {
-        const otherInProgress = plan.tasks.find((t) => t.id !== taskId && t.state === "in_progress");
-        if (otherInProgress) {
+        const target = plan.tasks.find((task) => task.id === taskId);
+        const ready = readyPlanTasks(plan).some((task) => task.id === taskId);
+        const retryingFailedTask = target?.state === "failed";
+        if (target?.state === "done" || target?.state === "skipped") {
+            const nextPending = readyPlanTasks(plan)[0];
+            const nextHint = nextPending
+                ? ` Continue with task.update {taskId:"${nextPending.id}", state:"in_progress"} ("${nextPending.title}").`
+                : " All ready work is finished — write the final summary if needed.";
+            return {
+                handled: true,
+                ok: false,
+                display: chalk.red(`  ✗ task.update: [${taskId}] is already ${target.state} — do not re-open\n`),
+                modelNote: `task.update failed: [${taskId}] is already ${target.state}. ` +
+                    `Do not re-run completed tasks.${nextHint}`,
+            };
+        }
+        if (target?.state !== "in_progress") {
+            const incompleteDependencies = (target?.dependencies ?? []).filter((dependency) => {
+                const dependencyTask = plan.tasks.find((task) => task.id === dependency);
+                return !dependencyTask || (dependencyTask.state !== "done" && dependencyTask.state !== "skipped");
+            });
+            const heldLocks = new Set(plan.tasks
+                .filter((task) => task.state === "in_progress" && task.id !== taskId)
+                .flatMap((task) => task.resourceLocks ?? []));
+            const conflictingLocks = (target?.resourceLocks ?? []).filter((lock) => heldLocks.has(lock));
+            if ((!ready && !retryingFailedTask) ||
+                incompleteDependencies.length > 0 ||
+                conflictingLocks.length > 0) {
+                const nextReady = readyPlanTasks(plan)[0];
+                return {
+                    handled: true,
+                    ok: false,
+                    display: chalk.red(`  ✗ task.update: [${taskId}] is not dependency/resource ready\n`),
+                    modelNote: `task.update failed: [${taskId}] is not ready. ` +
+                        (incompleteDependencies.length ? `Incomplete dependencies: ${incompleteDependencies.join(", ")}. ` : "") +
+                        (conflictingLocks.length ? `Resources currently locked: ${conflictingLocks.join(", ")}. ` : "") +
+                        (nextReady
+                            ? `Open the next ready task first: ${nextReady.id} ("${nextReady.title}").`
+                            : ""),
+                };
+            }
+        }
+        // A retry is a new execution attempt. Previous receipts proved only the
+        // failed attempt and must not close the task before recovery work succeeds.
+        if (retryingFailedTask && target)
+            target.evidence = undefined;
+    }
+    if (stateRaw === "done") {
+        const target = plan.tasks.find((task) => task.id === taskId);
+        const incompleteDependencies = (target?.dependencies ?? []).filter((dependency) => {
+            const dependencyTask = plan.tasks.find((task) => task.id === dependency);
+            return !dependencyTask || (dependencyTask.state !== "done" && dependencyTask.state !== "skipped");
+        });
+        if (incompleteDependencies.length > 0) {
             return {
                 handled: true,
                 ok: false,
-                display: chalk.red(`  \u2717 task.update: task [${otherInProgress.id}] "${otherInProgress.title}" is still in_progress\n`),
-                modelNote: `task.update failed: task [${otherInProgress.id}] "${otherInProgress.title}" is still in_progress. ` +
-                    "Finish it first \u2014 call task.update with state 'done' (or 'failed'/'skipped' with a note) " +
-                    `for [${otherInProgress.id}] before starting [${taskId}].`,
+                display: chalk.red(`  ✗ task.update: cannot complete [${taskId}] before dependencies\n`),
+                modelNote: `task.update failed: earlier task/dependency ${incompleteDependencies.join(", ")} is not complete for [${taskId}].`,
             };
         }
+        if (target && target.state !== "in_progress") {
+            // Soft-auto: pending + dependency-ready → open then complete in one call.
+            // Models often skip the ritual in_progress step after work already landed.
+            if (target.state === "pending" && incompleteDependencies.length === 0) {
+                const opened = markTask(plan, taskId, "in_progress", note);
+                if (!opened) {
+                    return {
+                        handled: true,
+                        ok: false,
+                        display: chalk.red(`  ✗ task.update: could not auto-open [${taskId}] before completion\n`),
+                        modelNote: `task.update failed: could not auto-open pending [${taskId}].`,
+                    };
+                }
+                // Fall through to mark done below (state is now in_progress).
+            }
+            else if (target.state === "failed") {
+                return {
+                    handled: true,
+                    ok: false,
+                    display: chalk.red(`  ✗ task.update: [${taskId}] is failed — retry with in_progress first\n`),
+                    modelNote: `task.update failed: [${taskId}] is failed. ` +
+                        `Call task.update {taskId:"${taskId}", state:"in_progress"} to retry, then mark done after recovery work.`,
+                };
+            }
+            else {
+                const nextReady = readyPlanTasks(plan)[0];
+                return {
+                    handled: true,
+                    ok: false,
+                    display: chalk.red(`  ✗ task.update: [${taskId}] must be in_progress before completion\n`),
+                    modelNote: `task.update failed: [${taskId}] is ${target.state}. ` +
+                        "Start or retry it, perform fresh work, then mark it done." +
+                        (nextReady
+                            ? ` Open next ready: ${nextReady.id} ("${nextReady.title}").`
+                            : ""),
+                };
+            }
+        }
     }
     const ok = markTask(plan, taskId, stateRaw, note);
     if (!ok) {
-        const ids = plan.tasks.map((t) => t.id).join(", ");
+        const idMap = plan.tasks
+            .map((t) => `${t.id}="${t.title}"` +
+            (t.aliases?.length ? ` (also: ${t.aliases.join(", ")})` : ""))
+            .join("; ");
         return {
             handled: true,
             ok: false,
-            display: chalk.red(`  ✗ task.update: unknown taskId "${taskId}" (have: ${ids})\n`),
-            modelNote: `task.update failed: unknown taskId. Valid ids: ${ids}.`,
+            display: chalk.red(`  ✗ task.update: unknown taskId "${taskIdRaw}" (have: ${plan.tasks.map((t) => t.id).join(", ")})\n`),
+            modelNote: `task.update failed: unknown taskId "${taskIdRaw}". ` +
+                `Valid ids (use these, not title text): ${idMap}.`,
         };
     }
     if (plan.status === "draft" || plan.status === "approved") {
         plan.status = "in_progress";
     }
-    const allDone = plan.tasks.every((t) => t.state === "done" || t.state === "skipped" || t.state === "failed");
-    if (allDone)
-        plan.status = "completed";
+    const terminal = isPlanTerminal(plan);
+    const successful = isPlanSuccessful(plan);
+    if (terminal)
+        plan.status = successful ? "completed" : "abandoned";
     await savePlan(plan).catch(() => undefined);
     const checklist = renderPlanForTerminal(plan);
+    const nextPending = readyPlanTasks(plan)[0];
+    let modelNote;
+    if (successful) {
+        modelNote =
+            "Task updated. All required tasks succeeded or were explicitly skipped. Verify the result and give your final summary. " +
+                "If a dev server was started: report URL, port, job id, and that it is still running.";
+    }
+    else if (terminal) {
+        const failed = plan.tasks.filter((task) => task.state === "failed");
+        modelNote =
+            `Task updated. The plan is terminal but NOT successful: ${failed.length} task(s) failed. ` +
+                "Do not claim completion. Report a failed/partial outcome with the failed tasks and remaining user outcome.";
+    }
+    else if (stateRaw === "done" && nextPending) {
+        modelNote =
+            `Task [${taskId}] marked done after verified work. ` +
+                `NEXT: open only the next task with task.update {taskId:"${nextPending.id}", state:"in_progress"}, ` +
+                `then do work for "${nextPending.title}" only. Wait for tool results before marking that one done. ` +
+                "Do not batch later tasks. Do not start a later task's tools early.";
+    }
+    else if (stateRaw === "in_progress") {
+        modelNote =
+            `Task [${taskId}] is now in_progress. Do ONLY this task's work, wait for tool results, ` +
+                `and mark done only when you are satisfied the results prove success. ` +
+                `Then task.update {taskId:"${taskId}", state:"done"}. Do not open or work on later tasks yet.`;
+    }
+    else {
+        modelNote = "Task updated. Continue with the next pending task.";
+    }
     return {
         handled: true,
         ok: true,
         plan,
         display: checklist + "\n",
-        modelNote: allDone
-            ? "Task updated. ALL tasks are now finished. Verify the result and give your final summary."
-            : "Task updated. Continue with the next pending task.",
+        modelNote,
     };
 }
 //# sourceMappingURL=plan-tool.js.map